docbook2X: docbook2texi

docbook2texi
<< Previous | Converting to Texinfo | Next >>

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

## Options

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

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 `refentry`s, 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

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

<< Previous | Up | Next >>
Converting to Texinfo | Table of Contents | db2x_texixml