Refentry to man

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.

Caution

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 this:

xsltproc  manpages/docbook.xsl  myfile.xml

You don't have to specify an output file because the names are generated by the stylesheet. The stylesheet will list each file as it is produced.

Man to refentry

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.tuxedo.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.