some notes on man page build

I want to put some notes out of my head and on the record regarding the
docbook-xsl stylesheets and the man page build.

The release builds currently use version 1.76.1, because that's what's
in Debian stable on borka. That works fine. I didn't look into older
versions recently, so let's make sure we use at least that one.

In
<http://www.postgresql.org/message-id/1373416746.16613.2.camel@vanquo.pezone.net>
is asked for an upgrade to 1.78.1, which is the current upstream
release, because I wanted this bug fixed:

http://sourceforge.net/p/docbook/bugs/1233/

It turned out, however, that it introduced these two bugs

http://sourceforge.net/p/docbook/bugs/1321/
http://sourceforge.net/p/docbook/bugs/1322/

These are fixed upstream, but there hasn't been a new release in a while.

So the strategy going forward is to keep using 1.76.1 until borka gets
upgraded (or are we going to use wheezy-lts?). If it does get upgraded
and Debian jessie ships with 1.78.1, we'll need to decide about either
downgrading back to 1.76.1 or taking whatever new release might be out
there at the time. We should not ship a release built with 1.78.1.

Besides that, there are a few stylesheet bugs/shortcomings that we carry
local workarounds for. These are

http://sourceforge.net/p/docbook/bugs/1058/
http://sourceforge.net/p/docbook/bugs/1239/
http://sourceforge.net/p/docbook/bugs/1245/
http://sourceforge.net/p/docbook/bugs/1340/

The difference is merely that some bugs are easier to work around
locally than others. We might eventually remove these local workarounds
once the fixed stylesheet versions are ubiquitous. But there isn't
really a standard way to require a minimum stylesheet version, so it's
not clear yet how to do that.

Btw., the way I test this is something like

cd doc/src/sgml
make man
mkdir build-1
mv man? build-1/
rm man-stamp
# make stylesheet changes
make man
mkdir build-2
mv man? build-2/
diff -IGenerator -ur build-1 build-2

(The -I option skips hunks that are different merely because the version
embedded in the output is different.)

To use a different stylesheet version, edit stylesheet-man.xsl and
change the line

<xsl:import
href="http://docbook.sourceforge.net/release/xsl/current/manpages/docbook.xsl"/>

You can replace "current" by a specific version number such as "1.76.1"
or also "snapshot", to use the current development version. Our you can
replace the whole http URL with a local file URL.