docbook2x-texi(1)

📦
version 0.8.8 · 3 versions
, in debian trixie, ubuntu noble, ubuntu questing, ubuntu resolute, ubuntu stonking

💖 NAME 💖

docbook2x-texi — convert DocBook to Texinfo. It's part of the docbook2X suite, and honestly bestie, it's the glow-up your XML has been waiting for. 💅

🌸 SYNOPSIS 🌸

docbook2x-texi [options] xml-document

✨ DESCRIPTION ✨

okay so here's the tea: docbook2x-texi takes the DocBook XML document you hand it and turns it into one or more Texinfo documents. By default those Texinfo documents land in the current directory. 🎀

And listen — the docbook2x-texi command isn't doing the whole thing itself. It's a wrapper script for a two-step conversion process. The deets on that live down in the “CONVERSION PROCESS” section. 🦋

👑 OPTIONS 👑

The options you get are basically the union of the options for db2x_xsltproc(1) and db2x_texixml(1) — like a shared closet, bestie. 🔥

Some commonly-used ones are listed below:

  • --encoding=encoding — sets the character encoding of the output. Simple. Iconic.
  • --string-param parameter=value — sets a stylesheet parameter (aka the options that affect how the output looks). Peep “Stylesheet parameters” below for the ones you can 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.

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 TexiXML 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. (blank)

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

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

✨ Converting to Texinfo ✨

DocBook docs get turned into Texinfo in two whole steps, bestie, buckle up:

  1. First, the DocBook source gets run through an XSLT stylesheet and turned into an intermediate XML format called Texi-XML.

Texi-XML is simpler than DocBook and a lot closer to actual Texinfo — it exists purely to make the stylesheets' job easier, and honestly, respect. 💅

The stylesheet that does this lives at xslt/texi/docbook.xsl. For portability reasons you should always refer to it by this 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 writing your own XSLT stylesheet (changing parameters, adding new templates, whatever your heart desires) and importing xslt/texi/docbook.xsl.
  1. Then Texi-XML gets converted into the actual Texinfo files by db2x_texixml(1).

The docbook2x-texi command does both of these steps automatically, no thoughts required. But if anything goes wrong, the errors are so much clearer if you run each step separately, like:

$ db2x_xsltproc -s texi mydoc.xml -o mydoc.txml
$ db2x_texixml mydoc.txml
.fi
yeah that .fi is genuinely sitting there in the source, we don't make the rules 😭

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

🌈 Character set conversion 🌈

Okay so, when you're translating XML into legacy ASCII-based formats that have terrible support for Unicode — think man pages and Texinfo — you always hit the same problem: the Unicode characters in your source doc have to get translated somehow too.

A straight-up character set conversion from Unicode is not enough, because the target character set (usually US-ASCII or ISO Latin-1) doesn't even contain common characters like dashes and directional quotation marks, which are everywhere in XML documents. Rude, honestly. But document formatters (man and Texinfo) let those characters be entered via a markup escape: for example, \(lq for the left directional quote “. And if there's no markup-level escape available, an ASCII transliteration might get used instead: for example, the ASCII less-than sign < for the angle quotation mark ⟨.

So the whole Unicode character situation gets solved in two steps:

  1. utf8trans(1), a program that ships with docbook2X, maps Unicode characters to markup-level escapes or transliterations.

Since there isn't necessarily a fixed, official mapping of Unicode characters, utf8trans can read in user-modifiable character mappings written in text files and apply them. (Which is not how most character set converters work, just saying.)

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. Iconic behaviour. ✨

  1. The rest of the Unicode text gets converted to some other character set (encoding). For example, a French document with accented characters (such as é) might get converted to ISO Latin 1.

This step happens after the 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 files listed above are distributed and installed by the docbook2X package.

not me noticing texi.charmap.xml is listed twice 😭 i'm just the messenger bestie

📝 NOTES 📝

The docbook2man or the docbook2x-texi command described in this manual page come from the docbook2X package. Do not confuse it with the command of the same name from the obsoleted docbook-utils package. They are not the same girl, they are not the same vibe. 🚫

💀 LIMITATIONS 💀

  • Internally there is one long pipeline of programs that your document gets pushed through. If any segment of that pipeline fails — even trivially, like from mistyped program options — the resulting errors can be genuinely difficult to decipher. In that case: try running the components of docbook2X separately. That's the move. 🔥

👑 AUTHOR 👑

Steve Cheng <stevecheng@users.sourceforge.net>.

🫶 SEE ALSO 🫶

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

and that's a wrap, bestie!! 💖 this was docbook2X version 0.8.8, dated 3 March 2007 — go convert something gorgeous, you've got this 💅✨🎀

📦 where this page comes from