Provided by: docbook2x_0.8.8-17_amd64 bug

NAME

       docbook2x-texi - Convert DocBook to Texinfo

SYNOPSIS

       docbook2x-texi [options] xml-document

DESCRIPTION

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

OPTIONS

       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:

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

   STYLESHEET PARAMETERS
       captions-display-as-headings
              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.

       links-use-pxref
              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 badly.

       explicit-node-names
              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.
              Note

              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 explicit-node-names.

       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.

       funcsynopsis-decoration
              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.

       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.

       refentry-display-name
              Brief. Output NAME header before 'RefName'(s)?

              Default setting. 1 (boolean true)

              If true, a "NAME" section title is output before the list of 'RefName's.

       manvolnum-in-xref
              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.

       prefer-textobjects
              Brief. Prefer textobject over imageobject?

              Default setting. 1 (boolean true)

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

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

       semantic-decorations
              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.)

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

       output-file
              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.
              Important

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

       directory-category
              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.
              Note

              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.

       directory-description
              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.
              Note

              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.

       index-category
              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.

       qanda-defaultlabel
              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.

       qandaset-generate-toc
              Brief. Is a Table of Contents created for QandASets?

              Default setting.

              If true, a ToC is constructed for QandASets.

EXAMPLES

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

CONVERSION PROCESS

   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:

           http://docbook2x.sourceforge.net/latest/xslt/texi/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/texi/docbook.xsl.

       2.  Texi-XML is converted to the actual Texinfo files by db2x_texixml(1).

       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 separately:

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

       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.

FILES

       /usr/local/share/docbook2X/xslt/texi/docbook.xsl
       /usr/local/share/docbook2X/xslt/backend/db2x_texixml.xsl
       /usr/local/share/docbook2X/xslt/catalog.xml
       /usr/local/share/docbook2X/charmaps/texi.charmap.xml
       /usr/local/share/docbook2X/charmaps/texi.charmap.xml

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

NOTES

       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.

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_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 ⟨http://
       docbook2x.sourceforge.net/⟩ .