I have been trying out new toolchains for building the man pages, and I think
I've arrived at something I like now.
To improve/remove clarity, here are the available toolchains:
docbook2man-spec.pl -- This is the original one, which we currently use. It's
a Perl program that parses the output of nsgmls, an SGML parser, and prints
out manpage output. The last release was 2002, and it has been declared dead
by its author. The same tool was also repackaged at one time together with
other things as "docbook-utils", but that ships an even older version and is
now also a dead project. In fact, the last available version of docbook2man-
spec.pl works OK for us, but the problems are that it takes an expert to
install and run it, and we can't customize it.
docbook2X -- This is the successor, by the same author as the above. It uses
XSLT to process the SGML/XML and then uses Perl in a second stage to produce
man pages. I had worked for a while under the assumption that we could
eventually move to this, but I found that the output it produces is in various
aspects worse than that of the older product. Some of this you can work
around with customizations, but some of it you can't easily. It's also facing
a problem that the older code also had: It's just maintained sporadically by
one guy. There hasn't been a release in two years.
docbook-xsl -- I was surprised to learn that the "official" DocBook XSL
stylesheet set has also had a manpages option for a while. They offer the
same well though out customization options that we have come to know from the
HTML and FO variants, and I have managed to tweak the output to fit our
established practice. I think this is clearly the most viable option, as the
maintenance is very active and open, and the necessary tools are easy to
obtain and install.
What I would like to do now is to switch our man page build process to use
this last variant. I would like to ship updated man pages for the alpha
releases so we can ask users to verify the results, instead of having the type
of last-minute drama as we had with the 8.4 release, because we only build the
man pages about once a year and have no good feedback loop.
Eventually, I would like to ship both HTML and man page docs without any
intermediate tarballs as part of the regular tarball creating scripts.
Updating the man page toolchain is a prerequisite for that.