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.

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.