<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta name="generator" content=
"HTML Tidy for Linux/x86 (vers 1 September 2005), see www.w3.org" />
<meta http-equiv="Content-Type" content=
"text/html; charset=us-ascii" />
<title>docbook2X: docbook2texi</title>
<link rel="stylesheet" href="docbook2X.css" type="text/css" />
<link rev="made" href="mailto:stevecheng@users.sourceforge.net" />
<meta name="generator" content="DocBook XSL Stylesheets V1.68.1" />
<link rel="start" href="docbook2X.html" title=
"docbook2X: Documentation Table of Contents" />
<link rel="up" href="texinfo.html" title=
"docbook2X: Converting to Texinfo" />
<link rel="prev" href="texinfo.html" title=
"docbook2X: Converting to Texinfo" />
<link rel="next" href="db2x_texixml.html" title=
"docbook2X: db2x_texixml" />
</head>
<body>
<div class="navheader">
<table width="100%" summary="Navigation header">
<tr>
<th colspan="3" align="center">docbook2texi</th>
</tr>
<tr>
<td width="20%" align="left"><a accesskey="p" href=
"texinfo.html"><< Previous</a> </td>
<th width="60%" align="center">Converting to Texinfo</th>
<td width="20%" align="right"> <a accesskey="n" href=
"db2x_texixml.html">Next >></a></td>
</tr>
</table>
<hr /></div>
<div class="refentry" lang="en" xml:lang="en"><a id="docbook2texi"
name="docbook2texi"></a>
<div class="titlepage"></div>
<a id="id2529007" class="indexterm" name="id2529007"></a><a id=
"id2529014" class="indexterm" name="id2529014"></a><a id=
"id2529021" class="indexterm" name="id2529021"></a><a id=
"id2529027" class="indexterm" name="id2529027"></a>
<div class="refnamediv">
<h2>Name</h2>
<p><span><strong class="command">docbook2texi</strong></span>
— Convert DocBook to Texinfo</p>
</div>
<div class="refsynopsisdiv">
<h2>Synopsis</h2>
<div class="cmdsynopsis">
<p><code class="command">docbook2texi</code> [<em class=
"replaceable"><code>options</code></em>] <em class=
"replaceable"><code>xml-document</code></em></p>
</div>
</div>
<div class="refsect1" lang="en" xml:lang="en"><a id="id2529110"
name="id2529110"></a>
<h2>Description</h2>
<p><span><strong class="command">docbook2texi</strong></span>
converts the given DocBook XML document into one or more Texinfo
documents. By default, these Texinfo documents will be output to
the current directory.</p>
<p>The <span><strong class="command">docbook2texi</strong></span>
command is a wrapper script for a two-step conversion process.</p>
</div>
<div class="refsect1" lang="en" xml:lang="en"><a id="id2529146"
name="id2529146"></a>
<h2>Options</h2>
<p>The available options are essentially the union of the options
for <a href="db2x_xsltproc.html"><span><strong class=
"command">db2x_xsltproc</strong></span></a> and <a href=
"db2x_texixml.html"><span><strong class=
"command">db2x_texixml</strong></span></a>.</p>
<p>Some commonly-used options are listed below:</p>
<div class="variablelist">
<dl>
<dt><span class="term"><code class="option">--encoding=<em class=
"replaceable"><code>encoding</code></em></code></span></dt>
<dd>
<p>Sets the character encoding of the output.</p>
</dd>
<dt><span class="term"><code class="option">--string-param
<em class="replaceable"><code>parameter</code></em>=<em class=
"replaceable"><code>value</code></em></code></span></dt>
<dd>
<p>Sets a stylesheet parameter (options that affect how the output
looks). See “Stylesheet parameters” below for the
parameters that can be set.</p>
</dd>
<dt><span class="term"><code class=
"option">--sgml</code></span></dt>
<dd>
<p>Accept an SGML source document as input instead of XML.</p>
</dd>
</dl>
</div>
<div class="refsect2" lang="en" xml:lang="en"><a id="id2529242"
name="id2529242"></a>
<h3>Stylesheet parameters</h3>
<a id="id2529248" class="indexterm" name="id2529248"></a>
<div class="variablelist">
<dl>
<dt><span class="term"><em class=
"parameter"><code>captions-display-as-headings</code></em></span></dt>
<dd>
<p><b>Brief. </b>Use heading markup for minor captions?</p>
<p><b>Default setting. </b><code class="literal">0</code>
(boolean false)</p>
<p>If true, <code class="sgmltag-element">title</code> content in
some (formal) objects are rendered with the Texinfo <span class=
"markup">@<em class="replaceable"><code>heading</code></em></span>
commands.</p>
<p>If false, captions are rendered as an emphasized paragraph.</p>
</dd>
<dt><span class="term"><em class=
"parameter"><code>links-use-pxref</code></em></span></dt>
<dd>
<p><b>Brief. </b>Translate <code class=
"sgmltag-element">link</code> using <span class=
"markup">@pxref</span></p>
<p><b>Default setting. </b><code class="literal">1</code>
(boolean true)</p>
<p>If true, <code class="sgmltag-element">link</code> is translated
with the hypertext followed by the cross reference in
parentheses.</p>
<p>Otherwise, the hypertext content serves as the cross-reference
name marked up using <span class="markup">@ref</span>. Typically
info displays this contruct badly.</p>
</dd>
<dt><span class="term"><em class=
"parameter"><code>explicit-node-names</code></em></span></dt>
<dd>
<p><b>Brief. </b>Insist on manually constructed Texinfo node
names</p>
<p><b>Default setting. </b><code class="literal">0</code>
(boolean false)</p>
<p>Elements in the source document can influence the Texinfo node
name generation specifying either a <code class=
"sgmltag-attribute">xreflabel</code>, or for the sectioning
elements, a <code class="sgmltag-element">title</code> with
<code class="sgmltag-attribute">role='texinfo-node'</code> in the
<code class="sgmltag-element"><em class=
"replaceable"><code>*</code></em>info</code> container.</p>
<p>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
<code class="function">generate-id</code> is always used for the
name.</p>
<p>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.</p>
<p>This option is not set (i.e. false) by default.</p>
<div class="note" style="margin-left: 0.5in; margin-right: 0.5in;">
<h3 class="title">Note</h3>
<p>The absolute fallback for generating node names is using the
XSLT function <code class="function">generate-id</code>, and the
stylesheet always emits a warning in this case regardless of the
setting of <em class=
"parameter"><code>explicit-node-names</code></em>.</p>
</div>
</dd>
<dt><span class="term"><em class=
"parameter"><code>show-comments</code></em></span></dt>
<dd>
<p><b>Brief. </b>Display <code class=
"sgmltag-element">comment</code> elements?</p>
<p><b>Default setting. </b><code class="literal">1</code>
(boolean true)</p>
<p>If true, comments will be displayed, otherwise they are
suppressed. Comments here refers to the <code class=
"sgmltag-element">comment</code> element, which will be renamed
<code class="sgmltag-element">remark</code> in DocBook V4.0, not
XML comments (<-- like this -->) which are unavailable.</p>
</dd>
<dt><span class="term"><em class=
"parameter"><code>funcsynopsis-decoration</code></em></span></dt>
<dd>
<p><b>Brief. </b>Decorate elements of a FuncSynopsis?</p>
<p><b>Default setting. </b><code class="literal">1</code>
(boolean true)</p>
<p>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.</p>
</dd>
<dt><span class="term"><em class=
"parameter"><code>function-parens</code></em></span></dt>
<dd>
<p><b>Brief. </b>Generate parentheses after a function?</p>
<p><b>Default setting. </b><code class="literal">0</code>
(boolean false)</p>
<p>If true, the formatting of a <code class=
"sgmltag-starttag"><function></code> element will include
generated parenthesis.</p>
</dd>
<dt><span class="term"><em class=
"parameter"><code>refentry-display-name</code></em></span></dt>
<dd>
<p><b>Brief. </b>Output NAME header before 'RefName'(s)?</p>
<p><b>Default setting. </b><code class="literal">1</code>
(boolean true)</p>
<p>If true, a "NAME" section title is output before the list of
'RefName's.</p>
</dd>
<dt><span class="term"><em class=
"parameter"><code>manvolnum-in-xref</code></em></span></dt>
<dd>
<p><b>Brief. </b>Output <code class=
"sgmltag-element">manvolnum</code> as part of <code class=
"sgmltag-element">refentry</code> cross-reference?</p>
<p><b>Default setting. </b><code class="literal">1</code>
(boolean true)</p>
<p>if true, the <code class="sgmltag-element">manvolnum</code> is
used when cross-referencing <code class=
"sgmltag-element">refentry</code>s, either with <code class=
"sgmltag-element">xref</code> or <code class=
"sgmltag-element">citerefentry</code>.</p>
</dd>
<dt><span class="term"><em class=
"parameter"><code>prefer-textobjects</code></em></span></dt>
<dd>
<p><b>Brief. </b>Prefer <code class=
"sgmltag-element">textobject</code> over <code class=
"sgmltag-element">imageobject</code>?</p>
<p><b>Default setting. </b><code class="literal">1</code>
(boolean true)</p>
<p>If true, the <code class="sgmltag-element">textobject</code> in
a <code class="sgmltag-element">mediaobject</code> is preferred
over any <code class="sgmltag-element">imageobject</code>.</p>
<p>(Of course, for output formats other than Texinfo, you usually
want to prefer the <code class=
"sgmltag-element">imageobject</code>, but Info is a text-only
format.)</p>
<p>In addition to the values true and false, this parameter may be
set to <code class="literal">2</code> 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
<span class="markup">@image</span> command has its own mechanism
for switching between text and image output — but we do not
use this here.</p>
<p>The default is true.</p>
</dd>
<dt><span class="term"><em class=
"parameter"><code>semantic-decorations</code></em></span></dt>
<dd>
<p><b>Brief. </b>Use Texinfo semantic inline markup?</p>
<p><b>Default setting. </b><code class="literal">1</code>
(boolean true)</p>
<p>If true, the semantic inline markup of DocBook is translated
into (the closest) Texinfo equivalent. This is the default.</p>
<p>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.)</p>
</dd>
<dt><span class="term"><em class=
"parameter"><code>custom-localization-file</code></em></span></dt>
<dd>
<p><b>Brief. </b>URI of XML document containing custom
localization data</p>
<p><b>Default setting. </b>(blank)</p>
<p>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.</p>
<p>The text translations pointed to by this parameter always
override the default text translations (from the internal parameter
<em class="parameter"><code>localization-file</code></em>). If a
particular translation is not present here, the corresponding
default translation is used as a fallback.</p>
<p>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.</p>
<p>To not use custom text translations, leave this parameter as the
empty string.</p>
</dd>
<dt><span class="term"><em class=
"parameter"><code>custom-l10n-data</code></em></span></dt>
<dd>
<p><b>Brief. </b>XML document containing custom localization
data</p>
<p><b>Default setting. </b><code class=
"literal">document($custom-localization-file)</code></p>
<p>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.</p>
<p>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
<em class="parameter"><code>custom-localization-file</code></em>
parameter instead.</p>
<p>However, inside a custom stylesheet (<span class=
"emphasis"><em>not on the command-line</em></span>) this paramter
can be set to the XPath expression <code class=
"literal">document('')</code>, which will cause the custom
translations directly embedded inside the custom stylesheet to be
read.</p>
</dd>
<dt><span class="term"><em class=
"parameter"><code>author-othername-in-middle</code></em></span></dt>
<dd>
<p><b>Brief. </b>Is <code class=
"sgmltag-element">othername</code> in <code class=
"sgmltag-element">author</code> a middle name?</p>
<p><b>Default setting. </b><code class="literal">1</code></p>
<p>If true, the <code class="sgmltag-element">othername</code> of
an <code class="sgmltag-element">author</code> appears between the
<code class="sgmltag-element">firstname</code> and <code class=
"sgmltag-element">surname</code>. Otherwise, <code class=
"sgmltag-element">othername</code> is suppressed.</p>
</dd>
<dt><span class="term"><em class=
"parameter"><code>output-file</code></em></span></dt>
<dd>
<p><b>Brief. </b>Name of the Info file</p>
<p><b>Default setting. </b>(blank)</p>
<a id="id2530580" class="indexterm" name="id2530580"></a>
<p>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 <code class=
"sgmltag-element">set</code>, this parameter has no effect.</p>
<div class="important" style=
"margin-left: 0.5in; margin-right: 0.5in;">
<h3 class="title">Important</h3>
<p>Do <span class="emphasis"><em>not</em></span> include the
<code class="literal">.info</code> extension in the name.</p>
</div>
<p>(Note that this parameter has nothing to do with the name of the
<span class="emphasis"><em>Texi-XML output</em></span> by the XSLT
processor you are running this stylesheet from.)</p>
</dd>
<dt><span class="term"><em class=
"parameter"><code>directory-category</code></em></span></dt>
<dd>
<p><b>Brief. </b>The categorization of the document in the
Info directory</p>
<p><b>Default setting. </b>(blank)</p>
<a id="id2530647" class="indexterm" name="id2530647"></a>
<p>This is set to the category that the document should go under in
the Info directory of installed Info files. For example,
<code class="literal">General Commands</code>.</p>
<div class="note" style="margin-left: 0.5in; margin-right: 0.5in;">
<h3 class="title">Note</h3>
<p>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.</p>
</div>
</dd>
<dt><span class="term"><em class=
"parameter"><code>directory-description</code></em></span></dt>
<dd>
<p><b>Brief. </b>The description of the document in the Info
directory</p>
<p><b>Default setting. </b>(blank)</p>
<a id="id2530696" class="indexterm" name="id2530696"></a>
<p>This is a short description of the document that appears in the
Info directory of installed Info files. For example, <code class=
"literal">An Interactive Plotting Program.</code></p>
<div class="note" style="margin-left: 0.5in; margin-right: 0.5in;">
<h3 class="title">Note</h3>
<p>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.</p>
</div>
</dd>
<dt><span class="term"><em class=
"parameter"><code>index-category</code></em></span></dt>
<dd>
<p><b>Brief. </b>The Texinfo index to use</p>
<p><b>Default setting. </b><code class="literal">cp</code></p>
<p>The Texinfo index for <code class=
"sgmltag-element">indexterm</code> and <code class=
"sgmltag-element">index</code> is specified using the <code class=
"sgmltag-attribute">role</code> attribute. If the above elements do
not have a <code class="sgmltag-attribute">role</code>, then the
default specified by this parameter is used.</p>
<p>The predefined indices are:</p>
<div class="variablelist">
<dl>
<dt><span class="term"><code class="literal">c</code>,</span>
<span class="term"><code class="literal">cp</code></span></dt>
<dd>
<p>Concept index</p>
</dd>
<dt><span class="term"><code class="literal">f</code>,</span>
<span class="term"><code class="literal">fn</code></span></dt>
<dd>
<p>Function index</p>
</dd>
<dt><span class="term"><code class="literal">v</code>,</span>
<span class="term"><code class="literal">vr</code></span></dt>
<dd>
<p>Variable index</p>
</dd>
<dt><span class="term"><code class="literal">k</code>,</span>
<span class="term"><code class="literal">ky</code></span></dt>
<dd>
<p>Keystroke index</p>
</dd>
<dt><span class="term"><code class="literal">p</code>,</span>
<span class="term"><code class="literal">pg</code></span></dt>
<dd>
<p>Program index</p>
</dd>
<dt><span class="term"><code class="literal">d</code>,</span>
<span class="term"><code class="literal">tp</code></span></dt>
<dd>
<p>Data type index</p>
</dd>
</dl>
</div>
<p>User-defined indices are not yet supported.</p>
</dd>
<dt><span class="term"><em class=
"parameter"><code>qanda-defaultlabel</code></em></span></dt>
<dd>
<p><b>Brief. </b>Sets the default for defaultlabel on
QandASet.</p>
<p><b>Default setting. </b></p>
<p>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.</p>
</dd>
<dt><span class="term"><em class=
"parameter"><code>qandaset-generate-toc</code></em></span></dt>
<dd>
<p><b>Brief. </b>Is a Table of Contents created for
QandASets?</p>
<p><b>Default setting. </b></p>
<p>If true, a ToC is constructed for QandASets.</p>
</dd>
</dl>
</div>
</div>
</div>
<div class="refsect1" lang="en" xml:lang="en"><a id="id2531519"
name="id2531519"></a>
<h2>Examples</h2>
<a id="id2531525" class="indexterm" name="id2531525"></a>
<div class="informalexample">
<pre class="screen">
<code class="prompt">$ </code><strong class=
"userinput"><code>docbook2texi tdg.xml</code></strong>
<code class="prompt">$ </code><strong class=
"userinput"><code>docbook2texi --encoding=utf-8//TRANSLIT tdg.xml</code></strong>
<code class="prompt">$ </code><strong class=
"userinput"><code>docbook2texi --string-param semantic-decorations=0 tdg.xml</code></strong>
</pre></div>
</div>
<div class="refsect1" lang="en" xml:lang="en"><a id="id2531687"
name="id2531687"></a>
<h2>Limitations</h2>
<div class="itemizedlist">
<ul>
<li>
<p>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.</p>
</li>
</ul>
</div>
</div>
</div>
<div class="navfooter">
<hr />
<table width="100%" summary="Navigation footer">
<tr>
<td width="40%" align="left"><a accesskey="p" href=
"texinfo.html"><< Previous</a> </td>
<td width="20%" align="center"><a accesskey="u" href=
"texinfo.html">Up</a></td>
<td width="40%" align="right"> <a accesskey="n" href=
"db2x_texixml.html">Next >></a></td>
</tr>
<tr>
<td width="40%" align="left" valign="top">Converting to
Texinfo </td>
<td width="20%" align="center"><a accesskey="h" href=
"docbook2X.html">Table of Contents</a></td>
<td width="40%" align="right" valign="top">
<span><strong class=
"command">db2x_texixml</strong></span></td>
</tr>
</table>
</div>
<p class="footer-homepage"><a href=
"http://docbook2x.sourceforge.net/" title=
"docbook2X: Home page">docbook2X home page</a></p>
</body>
</html>