If you work in a Unix or Linux environment, then you are probably familiar with reference manual pages, or “man pages”. A man page typically documents a single command in great detail. It is divided into several standard subsections, such as Name, Synopsis, and Description, among others. The DocBook
refentry element was originally modeled on the man page structure. The format of a man page consists of text interspersed with nroff markup using the man macro set. The Unix or Linux man command converts such markup into a formatted page on demand.
You may be called upon to convert DocBook
refentry elements to standard man page format for distribution with a product. Fortunately, there is a stylesheet available to do just that. It is also named
docbook.xsl, and it is included in the DocBook XSL distribution in the
manpages subdirectory. This stylesheet is different from the other stylesheets in that it outputs plain text rather than HTML or XML. This is triggered by this
xsl:output stylesheet element:
<xsl:output method="text" encoding="ISO-8859-1" indent="no"/>
This stylesheet only knows how to convert
refentry elements to man page files. If you process a DocBook document that contains
refentry elements, it will generate one man page file for each
refentry element. It will ignore the other parts of the document.
The filename for each man page is generated from
refentry content elements. The filename prefix is the
refname, and the suffix is the
manvolnum from within the
refmeta element. A typical filename might be
myfunction.3. If there is more than one
refname in a refentry, then only the first one is used for the filename.
If you are processing many refentrys from the same document, make sure they will all produce unique filenames, or else any duplicates will overwrite each other.
To generate a set of man pages from a DocBook document, you can use a command like the following:
xsltproc manpages/docbook.xsl myfile.xml
You do not have to specify an output file because the names are generated by the stylesheet. The stylesheet will list each file as it is produced.
You may be faced with the opposite problem: you have man pages but you need to convert them to DocBook
refentry elements. In that case, you want to use the free doclifter utility written by Eric Raymond. It is designed to convert troff markup into DocBook files. You can download the utility from http://www.catb.org/~esr/doclifter/. The documentation provides the syntax and options. You may need to clean up some parts of the conversion, because man pages are quite varied in their use of troff macros.
|DocBook XSL: The Complete Guide - 4th Edition||PDF version available|
Copyright © 2002-2007 Sagehill Enterprises