docbook2man — Convert DocBook to man pages
docbook2man
[options
] xml-document
docbook2man 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 docbook2man command is a wrapper script for a two-step conversion process.
The available options are essentially the union of the options from db2x_xsltproc and db2x_manxml.
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.
lowercase-file
Brief. Make man-page file names lowercase?
Default setting. 0
(boolean false)
Whenever a man-page title is all uppercase and this option is set, then the name of the file that contains that man-page should be changed to lowercase. If the man-page title is mixed-case, the file name will be unchanged.
This option is intended for the situation where the title of the man-page is an identifier in some language (e.g. SQL) that is case-insensitive, but the official version of the identifier is in uppercase. The user would probably prefer that the man-page should not be filed as all uppercase, even though the title displayed on the man-page should be upper-case.
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.
$
docbook2man --solinks manpages.xml
$
docbook2man --solinks --encoding=utf-8//TRANSLIT manpages.xml
$
docbook2man --string-param header-4="Free Recode 3.6" document.xml
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.