Previous INDEX Next
Hi-jack! Take this domain name to Spain Symbolic links on Windows

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.

Previous INDEX Next
Hi-jack! Take this domain name to Spain Symbolic links on Windows