Man Linux: Main Page and Category List

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/〉 .