docbook2man
<< Previous | Converting to man pages | Next >>

## Name

docbook2man — Convert DocBook to man pages

## Synopsis

`docbook2man` [`options`] `xml-document`

## Description

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.

## Options

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.

### 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

    $ docbook2man --solinks manpages.xml
    $ docbook2man --solinks --encoding=utf-8//TRANSLIT manpages.xml
    $ docbook2man --string-param header-4="Free Recode 3.6" document.xml

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

<< Previous | Up | Next >>
Converting to man pages | Table of Contents | db2x_manxml