Skip site navigation (1) Skip section navigation (2)

New man page toolchain

From: Peter Eisentraut <peter_e(at)gmx(dot)net>
To: pgsql-docs(at)postgresql(dot)org
Subject: New man page toolchain
Date: 2009-08-02 20:36:51
Message-ID: 200908022336.55936.peter_e@gmx.net (view raw or flat)
Thread:
Lists: pgsql-docs
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.


Responses

pgsql-docs by date

Next:From: Alvaro HerreraDate: 2009-08-02 21:48:12
Subject: Re: New man page toolchain
Previous:From: Emanuel Calvo FrancoDate: 2009-07-31 21:24:29
Subject: Re: 8.4 pdf manual

Privacy Policy | About PostgreSQL
Copyright © 1996-2014 The PostgreSQL Global Development Group