NAME
docbook2x-man - Convert DocBook to man pages
SYNOPSIS
docbook2x-man [options] xml-document
DESCRIPTION
docbook2x-man converts the given DocBook XML document into man pages.
By default, the man pages will be output to the current directory.
Only the refentry content in the DocBook document is converted. (To
convert content outside of a refentry, stylesheet customization is
required. See the docbook2X package for details.)
The docbook2x-man command is a wrapper script for a two-step conversion
process. See the section “CONVERSION PROCESS” below for details.
OPTIONS
The available options are essentially the union of the options from
db2x_xsltproc(1) and db2x_manxml(1).
Some commonly-used options are listed below:
--encoding=encoding
Sets the character encoding of the output.
--string-param parameter=value
Sets a stylesheet parameter (options that affect how the output
looks). See “Stylesheet parameters” below for the parameters
that can be set.
--sgml Accept an SGML source document as input instead of XML.
--solinks
Make stub pages for alternate names for an output man page.
STYLESHEET PARAMETERS
uppercase-headings
Brief. Make headings uppercase?
Default setting. 1 (boolean true)
Headings in man page content should be or should not be
uppercased.
manvolnum-cite-numeral-only
Brief. Man page section citation should use only the number
Default setting. 1 (boolean true)
When citing other man pages, the man-page section is either
given as is, or has the letters stripped from it, citing only
the number of the section (e.g. section 3x becomes 3). This
option specifies which style.
quotes-on-literals
Brief. Display quotes on literal elements?
Default setting. 0 (boolean false)
If true, render literal elements with quotes around them.
show-comments
Brief. Display comment elements?
Default setting. 1 (boolean true)
If true, comments will be displayed, otherwise they are
suppressed. Comments here refers to the comment element, which
will be renamed remark in DocBook V4.0, not XML comments (<--
like this -->) which are unavailable.
function-parens
Brief. Generate parentheses after a function?
Default setting. 0 (boolean false)
If true, the formatting of a <function> element will include
generated parenthesis.
xref-on-link
Brief. Should link generate a cross-reference?
Default setting. 1 (boolean true)
Man pages cannot render the hypertext links created by link. If
this option is set, then the stylesheet renders a cross
reference to the target of the link. (This may reduce clutter).
Otherwise, only the content of the link is rendered and the
actual link itself is ignored.
header-3
Brief. Third header text
Default setting. (blank)
Specifies the text of the third header of a man page, typically
the date for the man page. If empty, the date content for the
refentry is used.
header-4
Brief. Fourth header text
Default setting. (blank)
Specifies the text of the fourth header of a man page. If
empty, the refmiscinfo content for the refentry is used.
header-5
Brief. Fifth header text
Default setting. (blank)
Specifies the text of the fifth header of a man page. If empty,
the ‘manual name’, that is, the title of the book or reference
container is used.
default-manpage-section
Brief. Default man page section
Default setting. 1
The source document usually indicates the sections that each man
page should belong to (with manvolnum in refmeta). In case the
source document does not indicate man-page sections, this option
specifies the default.
custom-localization-file
Brief. URI of XML document containing custom localization data
Default setting. (blank)
This parameter specifies the URI of a XML document that
describes text translations (and other locale-specific
information) that is needed by the stylesheet to process the
DocBook document.
The text translations pointed to by this parameter always
override the default text translations (from the internal
parameter localization-file). If a particular translation is
not present here, the corresponding default translation is used
as a fallback.
This parameter is primarily for changing certain punctuation
characters used in formatting the source document. The settings
for punctuation characters are often specific to the source
document, but can also be dependent on the locale.
To not use custom text translations, leave this parameter as the
empty string.
custom-l10n-data
Brief. XML document containing custom localization data
Default setting. document($custom-localization-file)
This parameter specifies the XML document that describes text
translations (and other locale-specific information) that is
needed by the stylesheet to process the DocBook document.
This parameter is internal to the stylesheet. To point to an
external XML document with a URI or a file name, you should use
the custom-localization-file parameter instead.
However, inside a custom stylesheet (not on the command-line)
this paramter can be set to the XPath expression document(’’),
which will cause the custom translations directly embedded
inside the custom stylesheet to be read.
author-othername-in-middle
Brief. Is othername in author a middle name?
Default setting. 1
If true, the othername of an author appears between the
firstname and surname. Otherwise, othername is suppressed.
EXAMPLES
$ docbook2x-man --solinks manpages.xml
$ docbook2x-man --solinks --encoding=utf-8//TRANSLIT manpages.xml
$ docbook2x-man --string-param header-4="Free Recode 3.6" document.xml
CONVERSION PROCESS
Converting to man pages
DocBook documents are converted to man pages in two steps:
1. The DocBook source is converted by a XSLT stylesheet into an
intermediate XML format, Man-XML.
Man-XML is simpler than DocBook and closer to the man page format;
it is intended to make the stylesheets’ job easier.
The stylesheet for this purpose is in xslt/man/docbook.xsl. For
portability, it should always be referred to by the following URI:
http://docbook2x.sourceforge.net/latest/xslt/man/docbook.xsl
Run this stylesheet with db2x_xsltproc(1).
Customizing. You can also customize the output by creating your
own XSLT stylesheet — changing parameters or adding new templates —
and importing xslt/man/docbook.xsl.
2. Man-XML is converted to the actual man pages by db2x_manxml(1).
The docbook2x-man command does both steps automatically, but if any
problems occur, you can see the errors more clearly if you do each step
separately:
$ db2x_xsltproc -s man mydoc.xml -o mydoc.mxml
$ db2x_manxml mydoc.mxml
Options to the conversion stylesheet are described in the man-pages
stylesheets reference.
Pure XSLT conversion. An alternative to the db2x_manxml Perl script is
the XSLT stylesheet in xslt/backend/db2x_manxml.xsl. This stylesheet
performs a similar function of converting Man-XML to actual man pages.
It is useful if you desire a pure XSLT solution to man-page conversion.
Of course, the quality of the conversion using this stylesheet will
never be as good as the Perl db2x_manxml, and it runs slower. In
particular, the pure XSLT version currently does not support tables in
man pages, but its Perl counterpart does.
Character set conversion
When translating XML to legacy ASCII-based formats with poor support
for Unicode, such as man pages and Texinfo, there is always the problem
that Unicode characters in the source document also have to be
translated somehow.
A straightforward character set conversion from Unicode does not
suffice, because the target character set, usually US-ASCII or ISO
Latin-1, do not contain common characters such as dashes and
directional quotation marks that are widely used in XML documents. But
document formatters (man and Texinfo) allow such characters to be
entered by a markup escape: for example, \(lq for the left directional
quote “. And if a markup-level escape is not available, an ASCII
transliteration might be used: for example, using the ASCII less-than
sign < for the angle quotation mark 〈.
So the Unicode character problem can be solved in two steps:
1. utf8trans(1), a program included in docbook2X, maps Unicode
characters to markup-level escapes or transliterations.
Since there is not necessarily a fixed, official mapping of Unicode
characters, utf8trans can read in user-modifiable character
mappings expressed in text files and apply them. (Unlike most
character set converters.)
In charmaps/man/roff.charmap and charmaps/man/texi.charmap are
character maps that may be used for man-page and Texinfo
conversion. The programs db2x_manxml(1) and db2x_texixml(1) will
apply these character maps, or another character map specified by
the user, automatically.
2. The rest of the Unicode text is converted to some other character
set (encoding). For example, a French document with accented
characters (such as é) might be converted to ISO Latin 1.
This step is applied after utf8trans character mapping, using the
iconv(1) encoding conversion tool. Both db2x_manxml(1) and
db2x_texixml(1) can call iconv(1) automatically when producing
their output.
FILES
/usr/local/share/docbook2X/xslt/man/docbook.xsl
/usr/local/share/docbook2X/xslt/backend/db2x_manxml.xsl
/usr/local/share/docbook2X/xslt/catalog.xml
/usr/local/share/docbook2X/charmaps/roff.charmap
/usr/local/share/docbook2X/charmaps/roff.charmap.xml
The above files are distributed and installed by the docbook2X package.
NOTES
The docbook2x-man or the docbook2texi command described in this manual
page come from the docbook2X package. It should not be confused with
the command of the same name from the obsoleted docbook-utils package.
LIMITATIONS
· Internally there is one long pipeline of programs which your document
goes through. If any segment of the pipeline fails (even trivially,
like from mistyped program options), the resulting errors can be
difficult to decipher — in this case, try running the components of
docbook2X separately.
AUTHOR
Steve Cheng <stevecheng@users.sourceforge.net>.
SEE ALSO
db2x_xsltproc(1), db2x_manxml(1), utf8trans(1)
The docbook2X manual (in Texinfo or HTML format) fully describes how to
convert DocBook to man pages and Texinfo.
Up-to-date information about this program can be found at the docbook2X
Web site 〈http://docbook2x.sourceforge.net/〉 .