db2x_docbook2man

docbook2man(1)                     docbook2X                    docbook2man(1)



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.  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
       $ docbook2man --solinks manpages.xml
       $ docbook2man --solinks --encoding=utf-8//TRANSLIT manpages.xml
       $ docbook2man --string-param header-4="Free Recode 3.6" document.xml
       .fi

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 docbook2man 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
       .fi

       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 docbook2man 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/⟩ .



docbook2X 0.8.8                  3 March 2007                   docbook2man(1)