The upstream stylesheets for man output insert a *roff comment for an
occurrence of an indexterm, for reasons that have apparently been lost
in history. This, however, is done incorrectly and causes some
formatting problems. This hasn't been an issue until now, but the
reorganization of indexterm elements inside variablelists has triggered
this issue.
The upstream fix (http://sourceforge.net/p/docbook/bugs/1340/) is to
drop indexterms altogether in man output, and so we'll do the same here.
Create separate appendixes for contrib extensions and other server
plugins on the one hand, and utility programs on the other. Recast
the documentation of the latter as refentries, so that man pages are
generated.
There is what may actually be a mistake in our markup. The problem is
in a situation like
<para>
<command>FOO</command> is ...
there is strictly speaking a line break before "FOO". In the HTML
output, this does not appear to be a problem, but in the man page
output, this shows up, so you get double blank lines at odd places.
So far, we have attempted to work around this with an XSL hack, but
that causes other problems, such as creating run-ins in places like
<acronym>SQL</acronym> <command>COPY</command>
So fix the problem properly by removing the extra whitespace. I only
fixed the problems that affect the man page output, not all the
places.
Satoshi Nagayasu, reviewed and revised by Peter Eisentraut
Since this introduces new refentries that we probably don't want to publish as
man pages, tweak man page stylesheet to omit man pages without manvolnum
element.
Peter Eisentraut
This switches the man page building process to use the DocBook XSL stylesheet
toolchain. The previous targets for Docbook2X are removed. configure has been
updated to look for the new tools. The Documentation appendix contains the
new build instructions. There are also a few isolated tweaks in the
documentation to improve places that came out strangely in the man pages.