Man Linux: Main Page and Category List


       docbook2x-texi - Convert DocBook to Texinfo


       docbook2x-texi [options] xml-document


       docbook2x-texi converts the given DocBook XML document into one or more
       Texinfo documents.  By default, these Texinfo documents will be  output
       to the current directory.

       The   docbook2x-texi  command  is  a  wrapper  script  for  a  two-step
       conversion process.  See the section  “CONVERSION  PROCESS”  below  for


       The  available  options  are  essentially  the union of the options for
       db2x_xsltproc(1) and db2x_texixml(1).

       Some commonly-used options are listed below:

              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.

              Brief. Use heading markup for minor captions?

              Default setting. 0 (boolean false)

              If true, title content in some  (formal)  objects  are  rendered
              with the Texinfo @heading commands.

              If false, captions are rendered as an emphasized paragraph.

              Brief. Translate link using @pxref

              Default setting. 1 (boolean true)

              If  true,  link is translated with the hypertext followed by the
              cross reference in parentheses.

              Otherwise, the hypertext content serves as  the  cross-reference
              name marked up using @ref. Typically info displays this contruct

              Brief. Insist on manually constructed Texinfo node names

              Default setting. 0 (boolean false)

              Elements in the source document can influence the  Texinfo  node
              name  generation  specifying  either  a  xreflabel,  or  for the
              sectioning elements, a title  with  role=’texinfo-node’  in  the
              *info container.

              However,  for the majority of source documents, explicit Texinfo
              node names are  not  available,  and  the  stylesheet  tries  to
              generate a reasonable one instead, e.g. from the normal title of
              an element.  The generated name may  not  be  optimal.  If  this
              option  is  set  and  the stylesheet needs to generate a name, a
              warning is emitted and generate-id is always used for the  name.

              When  the  hashtable  extension is not available, the stylesheet
              cannot check for node name collisions, and in this case, setting
              this option and using explicit node names are recommended.

              This option is not set (i.e. false) by default.

              The  absolute  fallback  for  generating node names is using the
              XSLT function generate-id, and the  stylesheet  always  emits  a
              warning   in   this   case   regardless   of   the   setting  of

              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.

              Brief. Decorate elements of a FuncSynopsis?

              Default setting. 1 (boolean true)

              If  true,  elements  of the FuncSynopsis will be decorated (e.g.
              bold or italic). The decoration is controlled by functions  that
              can be redefined in a customization layer.

              Brief. Generate parentheses after a function?

              Default setting. 0 (boolean false)

              If  true,  the  formatting  of a <function> element will include
              generated parenthesis.

              Brief. Output NAME header before ’RefName’(s)?

              Default setting. 1 (boolean true)

              If true, a "NAME" section title is output  before  the  list  of

              Brief. Output manvolnum as part of refentry cross-reference?

              Default setting. 1 (boolean true)

              if true, the manvolnum is used when cross-referencing refentrys,
              either with xref or citerefentry.

              Brief. Prefer textobject over imageobject?

              Default setting. 1 (boolean true)

              If true, the textobject in a mediaobject is preferred  over  any

              (Of  course,  for output formats other than Texinfo, you usually
              want to prefer the imageobject, but Info is a text-only format.)

              In  addition to the values true and false, this parameter may be
              set to 2 to indicate that both the text and the images should be
              output.   You  may  want to do this because some Texinfo viewers
              can read images. Note that the Texinfo @image  command  has  its
              own  mechanism for switching between text and image output — but
              we do not use this here.

              The default is true.

              Brief. Use Texinfo semantic inline markup?

              Default setting. 1 (boolean true)

              If true, the semantic inline markup  of  DocBook  is  translated
              into (the closest) Texinfo equivalent. This is the default.

              However,  because  the Info format is limited to plain text, the
              semantic inline markup is often distinguished by using  explicit
              quotes,  which  may  not  look good.  You can set this option to
              false to suppress these.  (For finer  control  over  the  inline
              formatting, you can use your own stylesheet.)

              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.

              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.

              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.

              Brief. Name of the Info file

              Default setting. (blank)

              This parameter specifies  the  name  of  the  final  Info  file,
              overriding  the setting in the document itself and the automatic
              selection in the stylesheet. If the  document  is  a  set,  this
              parameter has no effect.

              Do not include the .info extension in the name.

       (Note  that this parameter has nothing to do with the name of the Texi-
       XML output by the XSLT processor you are running this stylesheet from.)

              Brief. The categorization of the document in the Info directory

              Default setting. (blank)

              This is set to the category that the document should go under in
              the Info  directory  of  installed  Info  files.   For  example,
              General Commands.

              Categories may also be set directly in the source document.  But
              if this parameter is not empty, then  it  always  overrides  the
              setting in the source document.

              Brief. The description of the document in the Info directory

              Default setting. (blank)

              This  is a short description of the document that appears in the
              Info  directory  of  installed  Info  files.   For  example,  An
              Interactive Plotting Program.

              Menu  descriptions  may  also  be  set  directly  in  the source
              document.  But if this parameter is not empty,  then  it  always
              overrides the setting in the source document.

              Brief. The Texinfo index to use

              Default setting. cp

              The Texinfo index for indexterm and index is specified using the
              role attribute. If the above elements do not have a  role,  then
              the default specified by this parameter is used.

              The predefined indices are:

              c, cp  Concept index

              f, fn  Function index

              v, vr  Variable index

              k, ky  Keystroke index

              p, pg  Program index

              d, tp  Data type index

       User-defined indices are not yet supported.

              Brief. Sets the default for defaultlabel on QandASet.

              Default setting.

              If  no  defaultlabel  attribute is specified on a QandASet, this
              value is used. It must be  one  of  the  legal  values  for  the
              defaultlabel attribute.

              Brief. Is a Table of Contents created for QandASets?

              Default setting.

              If true, a ToC is constructed for QandASets.


       $ docbook2x-texi tdg.xml
       $ docbook2x-texi --encoding=utf-8//TRANSLIT tdg.xml
       $ docbook2x-texi --string-param semantic-decorations=0 tdg.xml


   Converting to Texinfo
       DocBook documents are converted to Texinfo in two steps:

       1.  The  DocBook  source  is  converted  by  a  XSLT stylesheet into an
           intermediate XML format, Texi-XML.

           Texi-XML is simpler than DocBook and closer to the Texinfo  format;
           it is intended to make the stylesheets’ job easier.

           The  stylesheet  for this purpose is in xslt/texi/docbook.xsl.  For
           portability, it should always be referred to by the following URI:


           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/texi/docbook.xsl.

       2.  Texi-XML  is   converted   to   the   actual   Texinfo   files   by

       The  docbook2x-texi  command  does both steps automatically, but if any
       problems occur, you can see the errors more clearly if you do each step

       $ db2x_xsltproc -s texi mydoc.xml -o mydoc.txml
       $ db2x_texixml mydoc.txml

       Options  to  the  conversion  stylesheet  are  described in the Texinfo
       stylesheets reference.

   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.



       The above files are distributed and installed by the docbook2X package.


       The  docbook2man or the docbook2x-texi 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.


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


       Steve Cheng <>.


       db2x_xsltproc(1), db2x_texixml(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 〈〉 .