Re: [PATCH] Remove trailing whitespaces from documentation

Tom,

* Tom Lane (tgl(at)sss(dot)pgh(dot)pa(dot)us) wrote:
> The real problem here, IMO, is the break in expected regression outputs.
> The previous thread mainly discussed that in terms of its impact on
> third-party tests using pg_regress, but for our own purposes it would be
> just as nasty to need to adjust every single test case we back-patch for
> the next five years.

I agree, that'd be annoying. Having to rewrite the fix for dumping
casts with pg_dump for every single major version we support because the
patch from the prior version couldn't be applied has certainly been a
rather annoying exercise.

> Thinking about this, I'm wondering what is the connection between
> what psql does and what should be in the SGML (or XML) docs, anyway.
> Nobody says boo when we have to do s/</&lt;/g to an example in order
> to put it in the docs; why is stripping trailing whitespace a bigger
> issue?

For my 2c, at least, because we're going to be constantly fighting with
the trailing whitespace in those examples. If you forget to s/</&lt;/g,
the docs aren't going to build and it's going to be extremely obvious
that you need to do something. Not that I'm actually happy about that-
I'd much rather tell the doc engine "copy this verbatim until you see a
</closeverbatim> tag" or whatever, and not have to go hack up psql
output at all, which I contend is also rather tedious and annoying to do
when writing new code and new tests. Is that worse than having to deal
with back-patching regression test output? Who knows.

That said, if we can make git complain about trailing whitespace in the
docs but not mind it in the regression test output, then at least most
will hopefully realize that they need to go through and strip out the
trailing whitespace before committing. Maybe we can come up with a psql
output mode of "make this work for the docs" or a tool to pipe arbitrary
text through to have it "do the right thing" for including it in the
docs.

I'm still a bit split, as I do feel like it's 'bad' of psql to be
emitting the trailing whitespace in the first place, even if it's been
done that way forever and even though it'll be an annoyance if we
change it. Ultimately, I'm alright with either way though, I just don't
like the idea of removing all the whitespace from the docs without a way
to minimize the chance that we end up adding it back due to copy/paste
from psql output.

Thanks!

Stephen