Re: documentation is now XML

Peter Eisentraut <peter(dot)eisentraut(at)2ndquadrant(dot)com> writes:
> The documentation sources are now DocBook XML, not SGML. (The files are
> still named *.sgml. That's something to think about separately.)

I think we should have a discussion about whether it'd be smart
to convert the back branches' documentation to XML as well.

The main reason that I want to consider this is that back-patching
documentation fixes is going to be a huge problem if we don't.

Using the same doc-building toolchain across all branches seems like a win
as well. You could argue that switching build requirements in a minor
release is unfriendly to packagers; but those who build their own docs
have already had to adapt to the xsltproc/fop toolchain for v10, so
standardizing on that for 9.3-9.6 as well doesn't seem like it complicates
their lives. (Possibly we should canvass opinions on pgsql-packagers to
be sure of that.)

Also, we're way overdue for getting out from under the creaky TeX-based
toolchain for producing PDFs. Every time we make releases, I worry
whether we're going to get blindsided by its bugs with hotlinks that get
split across pages, since page breaks tend to vary in position depending
on exactly whose version of the toolchain and style sheets you build with.
I've also been living in fear of the day we hit some hardwired TeX limit
that we can't increase or work around. We've had to hack around such
limits repeatedly in the past (eg commit 944b41fc0). Now, it's probably
unlikely that growth of the release notes would be enough to put us over
the top in any back branch --- but if it did happen, we'd find out about
it at a point in the release cycle where there's very little margin for
error.

As against all that, there's our traditional conservatism about making
not-strictly-necessary changes in the back branches. Which is a strong
factor, for sure, but I think maybe here's a case for overriding it.

regards, tom lane