db2x_docbook2texi

docbook2texi(1)                    docbook2X                   docbook2texi(1)



NAME
       docbook2texi - Convert DocBook to Texinfo

SYNOPSIS
       docbook2texi [options] xml-document

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

       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
       $ docbook2texi tdg.xml
       $ docbook2texi --encoding=utf-8//TRANSLIT tdg.xml
       $ docbook2texi --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 docbook2texi 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 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_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/⟩ .



docbook2X 0.8.8                  3 March 2007                  docbook2texi(1)