Building man pages with Docbook

For the few UNIX utilities I had developed, I wanted to create man pages to accompany them. The obvious choice seemed to be to develop them in Docbook, as I had used it for developing the BT Library documentation.

There is a stylesheet available as part of docbook-xsl that can be used in conjuction with xsltproc to convert a Docbook refentry to a man page. Both these are available as debian packages.

In order to validate the Docbook source before processing I decided to use onsgmls, which is part of the Debian opensp package. I can't remember why I decided to use this, and not the python script I'd developed...

Recently I found onsgmls was producing errors like the following:

  onsgmls:/usr/share/xml/docbook/schema/dtd/4.4/docbookx.dtd:116:15:W: named character reference
  onsgmls:/usr/share/xml/docbook/schema/dtd/4.4/docbookx.dtd:116:17:E: "X20AC" is not a function name

To eliminate these errors, I had to add a SGMLDECL line to my local catalog file:

  SGMLDECL /usr/share/sgml/declaration/xml.dcl
  CATALOG "docbook-xml-4.4/"
  CATALOG "xhtml/"

This ensures that the xml codes are declared before use. To ensure onsgmls uses the local catalog, use the -c command argument, as shown by the following command line:

   onsgmls -E5 -c ~/dtd/CATALOG -wxml -s file_to_be_validated

The other command arguments limit errors to 5 before bailing, warn on xml errors: -s instructs onsgmls to produce no output.

On successful validation, I could generate documentation in man format via xsltproc:

   xsltproc /usr/share/xml/docbook/stylesheet/nwalsh/manpages/docbook.xsl man_file.xml

The neat thing here is that I can also generate the man page as XHTML by a command of the form:

  	xsltproc -o . ~/doc/bt-doc/local.xsl vc-man.xml

where local.xsl is my local stylesheet, which contains the following:

  <?xml version='1.0'?>
  <xsl:stylesheet xmlns:xsl="" version="1.0">
  <xsl:import href="/usr/share/xml/docbook/stylesheet/nwalsh/xhtml/chunk.xsl"/>
  <xsl:param name="" select="ansi"/>
  <xsl:param name="html.stylesheet" select="'/styles/gen_styles.css'"/>

This local stylesheet sets the ansi style for the function synopsis and ensures that the standard hydrus CSS style sheet is added to the generated XHTML pages.