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/docbook.cat" CATALOG "xhtml/xhtml.cat"
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="http://www.w3.org/1999/XSL/Transform" version="1.0"> <xsl:import href="/usr/share/xml/docbook/stylesheet/nwalsh/xhtml/chunk.xsl"/> <xsl:param name="funcsynopsis.style" select="ansi"/> <xsl:param name="html.stylesheet" select="'/styles/gen_styles.css'"/> </xsl:stylesheet>
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.
