<texinfoset xmlns="http://docbook2x.sourceforge.net/xmlns/Texi-XML"><nodenamemap>

<nodenamemapentry id="docbook2X" file="docbook2X"><nodename>Top</nodename></nodenamemapentry>

<nodenamemapentry id="quickstart" file="docbook2X"><nodename>Quick start</nodename></nodenamemapentry>

<nodenamemapentry id="manpages" file="docbook2X"><nodename>Converting to man pages</nodename></nodenamemapentry>

<nodenamemapentry id="docbook2man" file="docbook2X"><nodename>docbook2man wrapper script</nodename></nodenamemapentry>

<nodenamemapentry id="db2x_manxml" file="docbook2X"><nodename>db2x_manxml</nodename></nodenamemapentry>

<nodenamemapentry id="db2x_manxml_name" file="docbook2X"><nodename>db2x_manxml_name</nodename></nodenamemapentry>

<nodenamemapentry id="texinfo" file="docbook2X"><nodename>Converting to Texinfo</nodename></nodenamemapentry>

<nodenamemapentry id="docbook2texi" file="docbook2X"><nodename>docbook2texi wrapper script</nodename></nodenamemapentry>

<nodenamemapentry id="db2x_texixml" file="docbook2X"><nodename>db2x_texixml</nodename></nodenamemapentry>

<nodenamemapentry id="db2x_texixml_name" file="docbook2X"><nodename>db2x_texixml_name</nodename></nodenamemapentry>

<nodenamemapentry id="xsltproc" file="docbook2X"><nodename>The XSLT stylesheets</nodename></nodenamemapentry>

<nodenamemapentry id="xsltproc.db2x_manxml" file="docbook2X"><nodename>Convert to man pages using pure-XSLT db2x_manxml</nodename></nodenamemapentry>

<nodenamemapentry id="xsltproc.db2x_texixml" file="docbook2X"><nodename>Convert to Texinfo using Pure-XSLT db2x_texixml</nodename></nodenamemapentry>

<nodenamemapentry id="db2x_xsltproc" file="docbook2X"><nodename>db2x_xsltproc</nodename></nodenamemapentry>

<nodenamemapentry id="db2x_xsltproc_name" file="docbook2X"><nodename>db2x_xsltproc_name</nodename></nodenamemapentry>

<nodenamemapentry id="sgml2xml-isoent" file="docbook2X"><nodename>sgml2xml-isoent</nodename></nodenamemapentry>

<nodenamemapentry id="sgml2xml-isoent_name" file="docbook2X"><nodename>sgml2xml-isoent_name</nodename></nodenamemapentry>

<nodenamemapentry id="charsets" file="docbook2X"><nodename>Character set conversion</nodename></nodenamemapentry>

<nodenamemapentry id="utf8trans" file="docbook2X"><nodename>utf8trans</nodename></nodenamemapentry>

<nodenamemapentry id="utf8trans_name" file="docbook2X"><nodename>utf8trans_name</nodename></nodenamemapentry>

<nodenamemapentry id="faq" file="docbook2X"><nodename>FAQ</nodename></nodenamemapentry>

<nodenamemapentry id="performance" file="docbook2X"><nodename>Performance analysis</nodename></nodenamemapentry>

<nodenamemapentry id="testing" file="docbook2X"><nodename>How docbook2X is tested</nodename></nodenamemapentry>

<nodenamemapentry id="todo" file="docbook2X"><nodename>To-do list</nodename></nodenamemapentry>

<nodenamemapentry id="changes" file="docbook2X"><nodename>Release history</nodename></nodenamemapentry>

<nodenamemapentry id="changes-0.8.8" file="docbook2X"><nodename>docbook2X 0_8_8</nodename></nodenamemapentry>

<nodenamemapentry id="changes-0.8.7" file="docbook2X"><nodename>docbook2X 0_8_7</nodename></nodenamemapentry>

<nodenamemapentry id="changes-0.8.6" file="docbook2X"><nodename>docbook2X 0_8_6</nodename></nodenamemapentry>

<nodenamemapentry id="changes-0.8.5" file="docbook2X"><nodename>docbook2X 0_8_5</nodename></nodenamemapentry>

<nodenamemapentry id="changes-0.8.4" file="docbook2X"><nodename>docbook2X 0_8_4</nodename></nodenamemapentry>

<nodenamemapentry id="changes-0.8.3" file="docbook2X"><nodename>docbook2X 0_8_3</nodename></nodenamemapentry>

<nodenamemapentry id="changes-0.8.2" file="docbook2X"><nodename>docbook2X 0_8_2</nodename></nodenamemapentry>

<nodenamemapentry id="changes-0.8.1" file="docbook2X"><nodename>docbook2X 0_8_1</nodename></nodenamemapentry>

<nodenamemapentry id="changes-0.8.0" file="docbook2X"><nodename>docbook2X 0_8_0</nodename></nodenamemapentry>

<nodenamemapentry id="changes-0.7.0" file="docbook2X"><nodename>docbook2X 0_7_0</nodename></nodenamemapentry>

<nodenamemapentry id="changes-0.6.9" file="docbook2X"><nodename>docbook2X 0_6_9</nodename></nodenamemapentry>

<nodenamemapentry id="changes-0.6.1" file="docbook2X"><nodename>docbook2X 0_6_1</nodename></nodenamemapentry>

<nodenamemapentry id="changes-0.6.0" file="docbook2X"><nodename>docbook2X 0_6_0</nodename></nodenamemapentry>

<nodenamemapentry id="changes-0.5.9" file="docbook2X"><nodename>docbook2X 0_5_9</nodename></nodenamemapentry>

<nodenamemapentry id="design-notes" file="docbook2X"><nodename>Design notes</nodename></nodenamemapentry>

<nodenamemapentry id="xslt-extensions-move" file="docbook2X"><nodename>Design notes: the       elimination of XSLT extensions</nodename></nodenamemapentry>

<nodenamemapentry id="install" file="docbook2X"><nodename>Package installation</nodename></nodenamemapentry>

<nodenamemapentry id="install-procedure" file="docbook2X"><nodename>Installation</nodename></nodenamemapentry>

<nodenamemapentry id="install-problems" file="docbook2X"><nodename>Installation problems</nodename></nodenamemapentry>

<nodenamemapentry id="dependencies" file="docbook2X"><nodename>Dependencies on other software</nodename></nodenamemapentry>

<nodenamemapentry id="cindex" file="docbook2X"><nodename>Concept index</nodename></nodenamemapentry></nodenamemap><texinfo file="docbook2X"><settitle>docbook2X</settitle><directory category="Document Preparation"><menuentry file="docbook2X"><menuentrytitle>docbook2X</menuentrytitle><menuentrydescrip>Convert DocBook into man pages and Texinfo</menuentrydescrip></menuentry></directory><node id="docbook2X" previousid="" nextid="quickstart"/><documentlanguage lang="en"/><top>docbook2X</top><indexterm class="cp">DocBook</indexterm><para>

    docbook2X converts 

    DocBook

    documents into man pages and 

    Texinfo documents.

  </para><para>

    It aims to support DocBook version 4.2, excepting the features

    that cannot be supported or are not useful in a man page or 

    Texinfo document.

  </para><indexterm class="cp">web site</indexterm><indexterm class="cp">download</indexterm><para>

    For information on the latest releases of docbook2X, and downloads,

    please visit the <uref url="http://docbook2x.sourceforge.net/">docbook2X home page</uref>.

  </para><menu><menuentry idref="quickstart"><menuentrytitle>Quick start</menuentrytitle><menuentrydescrip>Examples to get you started</menuentrydescrip></menuentry><menuentry idref="manpages"><menuentrytitle>Converting to man pages</menuentrytitle><menuentrydescrip>Details on man-page conversion</menuentrydescrip></menuentry><menuentry idref="texinfo"><menuentrytitle>Converting to Texinfo</menuentrytitle><menuentrydescrip>Details on Texinfo conversion</menuentrydescrip></menuentry><menuentry idref="xsltproc"><menuentrytitle>The XSLT stylesheets</menuentrytitle><menuentrydescrip>How to run the docbook2X XSLT stylesheets</menuentrydescrip></menuentry><menuentry idref="charsets"><menuentrytitle>Character set conversion</menuentrytitle><menuentrydescrip>Discussion on reproducing non-ASCII characters in the 

        converted output</menuentrydescrip></menuentry><menuentry idref="faq"><menuentrytitle>FAQ</menuentrytitle><menuentrydescrip>Answers and tips for common problems</menuentrydescrip></menuentry><menuentry idref="performance"><menuentrytitle>Performance analysis</menuentrytitle><menuentrydescrip>Discussion on conversion speed</menuentrydescrip></menuentry><menuentry idref="testing"><menuentrytitle>How docbook2X is tested</menuentrytitle><menuentrydescrip>Discussion of correctness-testing</menuentrydescrip></menuentry><menuentry idref="todo"><menuentrytitle>To-do list</menuentrytitle><menuentrydescrip>Ideas for future improvements</menuentrydescrip></menuentry><menuentry idref="changes"><menuentrytitle>Release history</menuentrytitle><menuentrydescrip>Changes to the package between releases</menuentrydescrip></menuentry><menuentry idref="design-notes"><menuentrytitle>Design notes</menuentrytitle><menuentrydescrip>Author’s notes on the grand scheme of docbook2X</menuentrydescrip></menuentry><menuentry idref="install"><menuentrytitle>Package installation</menuentrytitle><menuentrydescrip>Where to get docbook2X, and details on how to install

        it</menuentrydescrip></menuentry><menuentry idref="cindex"><menuentrytitle>Index</menuentrytitle><menuentrydescrip/></menuentry><detailmenu><menuline>— The Detailed Node Listing —</menuline><menuline/><menuline>Converting to man pages</menuline><menuline/><menuentry idref="docbook2man"><menuentrytitle>docbook2man</menuentrytitle><menuentrydescrip>Convert DocBook to man pages</menuentrydescrip></menuentry><menuentry idref="db2x_manxml"><menuentrytitle>db2x_manxml</menuentrytitle><menuentrydescrip>Make man pages from Man-XML</menuentrydescrip></menuentry><menuline/><menuline>Converting to Texinfo</menuline><menuline/><menuentry idref="docbook2texi"><menuentrytitle>docbook2texi</menuentrytitle><menuentrydescrip>Convert DocBook to Texinfo</menuentrydescrip></menuentry><menuentry idref="db2x_texixml"><menuentrytitle>db2x_texixml</menuentrytitle><menuentrydescrip>Make Texinfo files from Texi-XML</menuentrydescrip></menuentry><menuline/><menuline>The XSLT stylesheets</menuline><menuline/><menuentry idref="db2x_xsltproc"><menuentrytitle>db2x_xsltproc</menuentrytitle><menuentrydescrip>XSLT processor invocation wrapper</menuentrydescrip></menuentry><menuentry idref="sgml2xml-isoent"><menuentrytitle>sgml2xml-isoent</menuentrytitle><menuentrydescrip>Convert SGML to XML with support for ISO

entities</menuentrydescrip></menuentry><menuline/><menuline>Character set conversion</menuline><menuline/><menuentry idref="utf8trans"><menuentrytitle>utf8trans</menuentrytitle><menuentrydescrip>Transliterate UTF-8 characters according to a table</menuentrydescrip></menuentry><menuline/><menuline>Package installation</menuline><menuline/><menuentry idref="install-procedure"><menuentrytitle>Installation</menuentrytitle><menuentrydescrip>Package install procedure</menuentrydescrip></menuentry><menuentry idref="dependencies"><menuentrytitle>Dependencies on other software</menuentrytitle><menuentrydescrip>Other software packages that docbook2X needs</menuentrydescrip></menuentry><menuline/></detailmenu></menu><node id="quickstart" previousid="docbook2X" nextid="manpages" upid="docbook2X"/><chapter>Quick start</chapter><indexterm class="cp">example usage</indexterm><indexterm class="cp">converting to man pages</indexterm><indexterm class="cp">converting to Texinfo</indexterm><para>

To convert to man pages, you run the command docbook2man (<pxref idref="docbook2man"/>).  For example,

<example>$ docbook2man --solinks manpages.xml

</example><para>

The man pages will be output to your current directory.

</para><para>

The --solinks options tells docbook2man to create man page

links.  You may want to omit this option when developing documentation

so that your working directory does not explode with many stub man pages.

(If you don’t know what this means, you can read about it in detail in db2x_manxml,

 or just ignore the previous two sentences and always specify this option.)

</para>

</para><para>

To convert to Texinfo, you run the command docbook2texi (<pxref idref="docbook2texi"/>).  For example,

<example>$ docbook2texi tdg.xml

</example><para>

One (or more) Texinfo files will be output to your current directory.

</para>

</para><para>

The rest of this manual describes in detail all the other options

and how to customize docbook2X’s output.

</para><node id="manpages" previousid="quickstart" nextid="texinfo" upid="docbook2X"/><chapter>Converting to man pages</chapter><indexterm class="cp">man pages</indexterm><indexterm class="cp">converting to man pages</indexterm><indexterm class="cp">XSLT stylesheets</indexterm><indexterm class="cp">Man-XML</indexterm><para>

DocBook documents are converted to man pages in two steps:

<enumerate><listitem><para>

The DocBook source is converted by a XSLT stylesheet into an 

intermediate XML format, Man-XML.</para><para>

Man-XML is simpler than DocBook and closer to the man page format;

it is intended to make the stylesheets’ job easier.

</para><para>

The stylesheet for this purpose is in

<file>xslt/man/docbook.xsl</file>.

For portability, it should always be referred to

by the following URI:

<example>http://docbook2x.sourceforge.net/latest/xslt/man/docbook.xsl

</example>

</para><para>

Run this stylesheet with <ref idref="db2x_xsltproc">db2x_xsltproc</ref>.

</para><indexterm class="cp">customizing</indexterm><para>Customizing.  

You can also customize the output by

creating your own XSLT stylesheet —

changing parameters or adding new templates —

and importing <file>xslt/man/docbook.xsl</file>.

</para></listitem><listitem><para>

Man-XML is converted to the actual man pages by <ref idref="db2x_manxml">db2x_manxml</ref>.

</para></listitem></enumerate>

</para><para>

The docbook2man (<pxref idref="docbook2man"/>) command does both steps automatically,

but if any problems occur, you can see the errors more clearly

if you do each step separately:

<example>$ db2x_xsltproc -s man mydoc.xml -o mydoc.mxml

$ db2x_manxml mydoc.mxml

</example>

</para><para>

Options to the conversion stylesheet are described in

<ref node="Top" file="docbook2man-xslt" printmanual="docbook2X Man-pages Stylesheets Reference">the man-pages stylesheets

reference</ref>.

</para><indexterm class="cp">pure XSLT</indexterm><para>Pure XSLT conversion.  

An alternative to the db2x_manxml Perl script is the XSLT

stylesheet in 

<file>xslt/backend/db2x_manxml.xsl</file>.

This stylesheet performs a similar function

of converting Man-XML to actual man pages.

It is useful if you desire a pure XSLT

solution to man-page conversion.

Of course, the quality of the conversion using this stylesheet

will never be as good as the Perl db2x_manxml,

and it runs slower.  

In particular, the pure XSLT version

currently does not support tables in man pages,

but its Perl counterpart does.

</para><menu><menuentry idref="docbook2man"><menuentrytitle>docbook2man</menuentrytitle><menuentrydescrip>Convert DocBook to man pages</menuentrydescrip></menuentry><menuentry idref="db2x_manxml"><menuentrytitle>db2x_manxml</menuentrytitle><menuentrydescrip>Make man pages from Man-XML</menuentrydescrip></menuentry></menu><node id="docbook2man" nextid="db2x_manxml" upid="manpages"/><section>docbook2man</section><indexterm class="cp">man pages</indexterm><indexterm class="cp">converting to man pages</indexterm><indexterm class="cp">wrapper script</indexterm><indexterm class="cp">docbook2man</indexterm><subheading>Name</subheading><para>docbook2man — Convert DocBook to man pages</para><subheading>Synopsis</subheading><quotation><para><t>docbook2man [options]  xml-document </t></para></quotation><subheading>Description</subheading><para>

docbook2man converts the given DocBook XML document into man pages.

By default, the man pages will be output to the current directory.

</para><para>

<indexterm class="cp">refentry</indexterm>

Only the refentry content

in the DocBook document is converted.

(To convert content outside of a refentry,

stylesheet customization is required.  See the docbook2X

package for details.)

</para><para>

The docbook2man command is a wrapper script

for a two-step conversion process.

</para><subheading>Options</subheading><para>

The available options are essentially the union of the options

from <ref idref="db2x_xsltproc">db2x_xsltproc</ref> and <ref idref="db2x_manxml">db2x_manxml</ref>.

</para><para>

Some commonly-used options are listed below:

</para><varlist><varlistentry><term>--encoding=encoding</term><listitem><para>

        Sets the character encoding of the output.

      </para></listitem></varlistentry><varlistentry><term>--string-param parameter=value</term><listitem><para>

        Sets a stylesheet parameter (options that affect how the output looks).

        See “Stylesheet parameters” below for the parameters that

        can be set.

      </para></listitem></varlistentry><varlistentry><term>--sgml</term><listitem><para>

        Accept an SGML source document as input instead of XML.

      </para></listitem></varlistentry><varlistentry><term>--solinks</term><listitem><para>

        Make stub pages for alternate names for an output man page.

      </para></listitem></varlistentry></varlist><subsubheading>Stylesheet parameters</subsubheading><indexterm class="cp">stylesheet parameters</indexterm><varlist><varlistentry><term>uppercase-headings</term><listitem><para>Brief.  Make headings uppercase?</para><para>Default setting.  <samp>1</samp> (boolean true)</para><para>

Headings in man page content should be or should not be uppercased.

</para></listitem></varlistentry><varlistentry><term>manvolnum-cite-numeral-only</term><listitem><para>Brief.  Man page section citation should use only the number</para><para>Default setting.  <samp>1</samp> (boolean true)</para><para>

When citing other man pages, the man-page section is either given as is,

or has the letters stripped from it, citing only the number of the

section (e.g. section <samp>3x</samp> becomes

<samp>3</samp>).  This option specifies which style. 

</para></listitem></varlistentry><varlistentry><term>quotes-on-literals</term><listitem><para>Brief.  Display quotes on literal

elements?</para><para>Default setting.  <samp>0</samp> (boolean false)</para><para>

If true, render literal elements

with quotes around them.

</para></listitem></varlistentry><varlistentry><term>show-comments</term><listitem><para>Brief.  Display comment elements?</para><para>Default setting.  <samp>1</samp> (boolean true)</para><para>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.

</para></listitem></varlistentry><varlistentry><term>function-parens</term><listitem><para>Brief.  Generate parentheses after a function?</para><para>Default setting.  <samp>0</samp> (boolean false)</para><para>If true, the formatting of

a <function> element will include

generated parenthesis.

</para></listitem></varlistentry><varlistentry><term>xref-on-link</term><listitem><para>Brief.  Should link generate a

cross-reference?</para><para>Default setting.  <samp>1</samp> (boolean true)</para><para>

Man pages cannot render the hypertext links created by link.  If this option is set, then the

stylesheet renders a cross reference to the target of the link.

(This may reduce clutter).  Otherwise, only the content of the link is rendered and the actual link itself is

ignored.

</para></listitem></varlistentry><varlistentry><term>header-3</term><listitem><para>Brief.  Third header text</para><para>Default setting.  (blank)</para><para>

Specifies the text of the third header of a man page,

typically the date for the man page.  If empty, the date content for the refentry is used.

</para></listitem></varlistentry><varlistentry><term>header-4</term><listitem><para>Brief.  Fourth header text</para><para>Default setting.  (blank)</para><para>

Specifies the text of the fourth header of a man page.

If empty, the refmiscinfo content for

the refentry is used.

</para></listitem></varlistentry><varlistentry><term>header-5</term><listitem><para>Brief.  Fifth header text</para><para>Default setting.  (blank)</para><para>

Specifies the text of the fifth header of a man page.

If empty, the ‘manual name’, that is, the title of the

book or reference container is used.

</para></listitem></varlistentry><varlistentry><term>default-manpage-section</term><listitem><para>Brief.  Default man page section</para><para>Default setting.  <samp>1</samp></para><para>

The source document usually indicates the sections that each man page

should belong to (with manvolnum in

refmeta).  In case the source

document does not indicate man-page sections, this option specifies the

default.

</para></listitem></varlistentry><varlistentry><term>custom-localization-file</term><listitem><para>Brief.  URI of XML document containing custom localization data</para><para>Default setting.  (blank)</para><para>

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.

</para><para>

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.

</para><para>

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.

</para><para>

To not use custom text translations, leave this parameter 

as the empty string.

</para></listitem></varlistentry><varlistentry><term>custom-l10n-data</term><listitem><para>Brief.  XML document containing custom localization data</para><para>Default setting.  <samp>document($custom-localization-file)</samp></para><para>

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.

</para><para>

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.

</para><para>

However, inside a custom stylesheet 

(<emph>not on the command-line</emph>)

this paramter can be set to the XPath expression

<samp>document('')</samp>,

which will cause the custom translations 

directly embedded inside the custom stylesheet to be read.

</para></listitem></varlistentry><varlistentry><term>author-othername-in-middle</term><listitem><para>Brief.  Is othername in author a

middle name?</para><para>Default setting.  <samp>1</samp></para><para>If true, the othername of an author

appears between the firstname and

surname.  Otherwise, othername

is suppressed.

</para></listitem></varlistentry></varlist><subheading>Examples</subheading><indexterm class="cp">example usage</indexterm><example>$ docbook2man --solinks manpages.xml

$ docbook2man --solinks --encoding=utf-8//TRANSLIT manpages.xml

$ docbook2man --string-param header-4="Free Recode 3.6" document.xml

</example><subheading>Limitations</subheading><itemize markchar="•"><listitem><para>

      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.

    </para></listitem></itemize><node id="db2x_manxml" previousid="docbook2man" upid="manpages"/><section>db2x_manxml</section><indexterm class="cp">man pages</indexterm><indexterm class="cp">converting to man pages</indexterm><indexterm class="cp">Man-XML</indexterm><indexterm class="cp">stub pages</indexterm><indexterm class="cp">symbolic links</indexterm><indexterm class="cp">encoding</indexterm><indexterm class="cp">output directory</indexterm><indexterm class="cp">db2x_manxml</indexterm><subheading>Name</subheading><para>db2x_manxml — Make man pages from Man-XML</para><subheading>Synopsis</subheading><quotation><para><t>db2x_manxml [options] [xml-document]</t></para></quotation><subheading>Description</subheading><para>

db2x_manxml converts a Man-XML document into one or 

more man pages.  They are written in the current directory.

</para><para>

If xml-document is not given, then the document

to convert is read from standard input.  

</para><subheading>Options</subheading><varlist><varlistentry><term>--encoding=encoding</term><listitem><para>

Select the character encoding used for the output files.

The available encodings are those of 

iconv(1). 

The default encoding is <samp>us-ascii</samp>.  

</para><para>

The XML source may contain characters that are not representable in the encoding that

you select;  in this case the program will bomb out during processing, and you should 

choose another encoding.

(This is guaranteed not to happen with any Unicode encoding such as 

UTF-8, but unfortunately not everyone is able to 

process Unicode texts.)

</para><para>

If you are using GNU’s version of 

iconv(1), you can affix 

<samp>//TRANSLIT</samp> to the end of the encoding name

to attempt transliterations of any unconvertible characters in the output.

Beware, however, that the really inconvertible characters will be turned

into another of those damned question marks.  (Aren’t you sick of this?)

</para><para>

The suffix <samp>//TRANSLIT</samp> applied

to a Unicode encoding — in particular, <samp>utf-8//TRANSLIT</samp> —

means that the output files are to remain in Unicode,

but markup-level character translations using utf8trans 

are still to be done.  So in most cases, an English-language

document, converted using 

--encoding=<samp>utf-8//TRANSLIT</samp>

will actually end up as a US-ASCII document,

but any untranslatable characters 

will remain as UTF-8 without any warning whatsoever.

(Note: strictly speaking this is not “transliteration”.)

This method of conversion is a compromise over strict

--encoding=<samp>us-ascii</samp>

processing, which aborts if any untranslatable characters are 

encountered.

</para><para>

Note that man pages and Texinfo documents 

in non-ASCII encodings (including UTF-8)

may not be portable to older (non-internationalized) systems,

which is why the default value for this option is 

<samp>us-ascii</samp>.

</para><para>

To suppress any automatic character mapping or encoding conversion

whatsoever, pass the option 

--encoding=<samp>utf-8</samp>.

</para></listitem></varlistentry><varlistentry><term>--list-files</term><listitem><para>

Write a list of all the output files to standard output,

in addition to normal processing.

</para></listitem></varlistentry><varlistentry><term>--output-dir=dir</term><listitem><para>

Specify the directory where the output files are placed.

The default is the current working directory.

</para><para>

This option is ignored if the output is to be written

to standard output (triggered by the 

option --to-stdout).

</para></listitem></varlistentry><varlistentry><term>--to-stdout</term><listitem><para>

Write the output to standard output instead of to individual files.

</para><para>

If this option is used even when there are supposed to be multiple

output documents, then everything is concatenated to standard output.

But beware that most other programs will not accept this concatenated

output.

</para><para>

This option is incompatible with --list-files,

obviously.

</para></listitem></varlistentry><varlistentry><term>--help</term><listitem><para>Show brief usage information and exit.</para></listitem></varlistentry><varlistentry><term>--version</term><listitem><para>Show version and exit.</para></listitem></varlistentry></varlist><para>Some man pages may be referenced under two or more

names, instead of just one.  For example, 

strcpy(3)

and

strncpy(3)

often point to the same man page which describes the two functions together.

Choose one of the following options to select

how such man pages are to be generated:

</para><varlist><varlistentry><term>--symlinks</term><listitem><para>For each of all the alternate names for a man page,

erect symbolic links to the file that contains the real man page content.

</para></listitem></varlistentry><varlistentry><term>--solinks</term><listitem><para>Generate stub pages (using <samp>.so</samp> roff requests)

for the alternate names, pointing them to the real man page content.</para></listitem></varlistentry><varlistentry><term>--no-links</term><listitem><para>Do not make any alternative names available.

The man page can only be referenced under its principal name.

</para></listitem></varlistentry></varlist><para>

This program uses certain other programs for its operation.

If they are not in their default installed locations, then use

the following options to set their location:

<varlist><varlistentry><term>--utf8trans-program=path</term><term>--utf8trans-map=charmap</term><listitem><para>Use the character map charmap

with the <ref idref="utf8trans">utf8trans</ref> program, included with docbook2X, found

under path.</para></listitem></varlistentry><varlistentry><term>--iconv-program=path</term><listitem><para>The location of the 

iconv(1) program, used for encoding

conversions.</para></listitem></varlistentry></varlist></para><subheading>Notes</subheading><indexterm class="cp">groff</indexterm><indexterm class="cp">compatibility</indexterm><para>

The man pages produced should be compatible

with most troff implementations and other tools

that process man pages.

Some backwards-compatible 

groff(1) extensions

are used to make the output look nicer.

</para><subheading>See Also</subheading><para>

The input to db2x_manxml is defined by the XML DTD

present at <file>dtd/Man-XML</file> in the docbook2X

distribution.

</para><node id="texinfo" previousid="manpages" nextid="xsltproc" upid="docbook2X"/><chapter>Converting to Texinfo</chapter><indexterm class="cp">Texinfo</indexterm><indexterm class="cp">converting to Texinfo</indexterm><indexterm class="cp">XSLT stylesheets</indexterm><indexterm class="cp">Texi-XML</indexterm><para>

DocBook documents are converted to Texinfo in two steps:

<enumerate><listitem><para>

The DocBook source is converted by a XSLT stylesheet into an intermediate

XML format, Texi-XML.</para><para>

Texi-XML is simpler than DocBook and closer to the Texinfo format;

it is intended to make the stylesheets’ job easier.

</para><para>

The stylesheet for this purpose is in

<file>xslt/texi/docbook.xsl</file>.

For portability, it should always be referred to

by the following URI:

<example>http://docbook2x.sourceforge.net/latest/xslt/texi/docbook.xsl

</example>

</para><para>

Run this stylesheet with <ref idref="db2x_xsltproc">db2x_xsltproc</ref>.

</para><indexterm class="cp">customizing</indexterm><para>Customizing.  

You can also customize the output by

creating your own XSLT stylesheet —

changing parameters or adding new templates —

and importing <file>xslt/texi/docbook.xsl</file>.

</para></listitem><listitem><para>

Texi-XML is converted to the actual Texinfo files by <ref idref="db2x_texixml">db2x_texixml</ref>.

</para></listitem></enumerate>

</para><para>

The docbook2texi (<pxref idref="docbook2texi"/>) command does both steps automatically,

but if any problems occur, you can see the errors more clearly

if you do each step separately:

<example>$ db2x_xsltproc -s texi mydoc.xml -o mydoc.txml

$ db2x_texixml mydoc.txml

</example>

</para><para>

Options to the conversion stylesheet are described

in <ref node="Top" file="docbook2texi-xslt" printmanual="docbook2X Texinfo Stylesheets Reference">the Texinfo stylesheets

reference</ref>.

</para><menu><menuentry idref="docbook2texi"><menuentrytitle>docbook2texi</menuentrytitle><menuentrydescrip>Convert DocBook to Texinfo</menuentrydescrip></menuentry><menuentry idref="db2x_texixml"><menuentrytitle>db2x_texixml</menuentrytitle><menuentrydescrip>Make Texinfo files from Texi-XML</menuentrydescrip></menuentry></menu><node id="docbook2texi" nextid="db2x_texixml" upid="texinfo"/><section>docbook2texi</section><indexterm class="cp">Texinfo</indexterm><indexterm class="cp">converting to Texinfo</indexterm><indexterm class="cp">wrapper script</indexterm><indexterm class="cp">docbook2texi</indexterm><subheading>Name</subheading><para>docbook2texi — Convert DocBook to Texinfo</para><subheading>Synopsis</subheading><quotation><para><t>docbook2texi [options]  xml-document </t></para></quotation><subheading>Description</subheading><para>

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.

</para><para>

The docbook2texi command is a wrapper script

for a two-step conversion process.

</para><subheading>Options</subheading><para>

The available options are essentially the union of the options

for <ref idref="db2x_xsltproc">db2x_xsltproc</ref> and <ref idref="db2x_texixml">db2x_texixml</ref>.

</para><para>

Some commonly-used options are listed below:

</para><varlist><varlistentry><term>--encoding=encoding</term><listitem><para>

        Sets the character encoding of the output.

      </para></listitem></varlistentry><varlistentry><term>--string-param parameter=value</term><listitem><para>

        Sets a stylesheet parameter (options that affect how the output looks).

        See “Stylesheet parameters” below for the parameters that

        can be set.

      </para></listitem></varlistentry><varlistentry><term>--sgml</term><listitem><para>

        Accept an SGML source document as input instead of XML.

      </para></listitem></varlistentry></varlist><subsubheading>Stylesheet parameters</subsubheading><indexterm class="cp">stylesheet parameters</indexterm><varlist><varlistentry><term>captions-display-as-headings</term><listitem><para>Brief.  Use heading markup for minor captions?</para><para>Default setting.  <samp>0</samp> (boolean false)</para><para>If true, title

content in some (formal) objects are rendered with the Texinfo

@heading commands.

</para><para>

If false, captions are rendered as an emphasized paragraph.

</para></listitem></varlistentry><varlistentry><term>links-use-pxref</term><listitem><para>Brief.  Translate link using

@pxref</para><para>Default setting.  <samp>1</samp> (boolean true)</para><para>

If true, link is translated

with the hypertext followed by the cross reference in parentheses.

</para><para>

Otherwise, the hypertext content serves as the cross-reference name

marked up using @ref.  Typically info displays this

contruct badly.

</para></listitem></varlistentry><varlistentry><term>explicit-node-names</term><listitem><para>Brief.  Insist on manually constructed Texinfo node

names</para><para>Default setting.  <samp>0</samp> (boolean false)</para><para>

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.

</para><para>

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.

</para><para>

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.  

</para><para>

This option is not set (i.e. false) by default.

</para><quotation><para>Note</para><para>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.</para></quotation></listitem></varlistentry><varlistentry><term>show-comments</term><listitem><para>Brief.  Display comment elements?</para><para>Default setting.  <samp>1</samp> (boolean true)</para><para>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.

</para></listitem></varlistentry><varlistentry><term>funcsynopsis-decoration</term><listitem><para>Brief.  Decorate elements of a FuncSynopsis?</para><para>Default setting.  <samp>1</samp> (boolean true)</para><para>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.

</para></listitem></varlistentry><varlistentry><term>function-parens</term><listitem><para>Brief.  Generate parentheses after a function?</para><para>Default setting.  <samp>0</samp> (boolean false)</para><para>If true, the formatting of

a <function> element will include

generated parenthesis.

</para></listitem></varlistentry><varlistentry><term>refentry-display-name</term><listitem><para>Brief.  Output NAME header before 'RefName'(s)?</para><para>Default setting.  <samp>1</samp> (boolean true)</para><para>If true, a "NAME" section title is output before the list

of 'RefName's.

</para></listitem></varlistentry><varlistentry><term>manvolnum-in-xref</term><listitem><para>Brief.  Output manvolnum as part of

refentry cross-reference?</para><para>Default setting.  <samp>1</samp> (boolean true)</para><para>if true, the manvolnum is used when cross-referencing

refentrys, either with xref

or citerefentry.

</para></listitem></varlistentry><varlistentry><term>prefer-textobjects</term><listitem><para>Brief.  Prefer textobject

over imageobject?

</para><para>Default setting.  <samp>1</samp> (boolean true)</para><para>

If true, the 

textobject

in a mediaobject

is preferred over any

imageobject.

</para><para>

(Of course, for output formats other than Texinfo, you usually

want to prefer the imageobject,

but Info is a text-only format.)

</para><para>

In addition to the values true and false, this parameter

may be set to <samp>2</samp> 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.

</para><para>

The default is true.

</para></listitem></varlistentry><varlistentry><term>semantic-decorations</term><listitem><para>Brief.  Use Texinfo semantic inline markup?</para><para>Default setting.  <samp>1</samp> (boolean true)</para><para>

If true, the semantic inline markup of DocBook is translated into

(the closest) Texinfo equivalent.  This is the default.

</para><para>

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

</para></listitem></varlistentry><varlistentry><term>custom-localization-file</term><listitem><para>Brief.  URI of XML document containing custom localization data</para><para>Default setting.  (blank)</para><para>

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.

</para><para>

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.

</para><para>

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.

</para><para>

To not use custom text translations, leave this parameter 

as the empty string.

</para></listitem></varlistentry><varlistentry><term>custom-l10n-data</term><listitem><para>Brief.  XML document containing custom localization data</para><para>Default setting.  <samp>document($custom-localization-file)</samp></para><para>

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.

</para><para>

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.

</para><para>

However, inside a custom stylesheet 

(<emph>not on the command-line</emph>)

this paramter can be set to the XPath expression

<samp>document('')</samp>,

which will cause the custom translations 

directly embedded inside the custom stylesheet to be read.

</para></listitem></varlistentry><varlistentry><term>author-othername-in-middle</term><listitem><para>Brief.  Is othername in author a

middle name?</para><para>Default setting.  <samp>1</samp></para><para>If true, the othername of an author

appears between the firstname and

surname.  Otherwise, othername

is suppressed.

</para></listitem></varlistentry><varlistentry><term>output-file</term><listitem><para>Brief.  Name of the Info file</para><para>Default setting.  (blank)</para><indexterm class="cp">Texinfo metadata</indexterm><para>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. </para><quotation><para>Important</para><para>

Do <emph>not</emph> include the <samp>.info</samp>

extension in the name.

</para></quotation><para>

(Note that this parameter has nothing to do with the name of

the <emph>Texi-XML output</emph> by the XSLT processor you 

are running this stylesheet from.)

</para></listitem></varlistentry><varlistentry><term>directory-category</term><listitem><para>Brief.  The categorization of the document in the Info directory</para><para>Default setting.  (blank)</para><indexterm class="cp">Texinfo metadata</indexterm><para>

This is set to the category that the document

should go under in the Info directory of installed Info files.

For example, <samp>General Commands</samp>.

</para><quotation><para>Note</para><para>

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.

</para></quotation></listitem></varlistentry><varlistentry><term>directory-description</term><listitem><para>Brief.  The description of the document in the Info directory</para><para>Default setting.  (blank)</para><indexterm class="cp">Texinfo metadata</indexterm><para>

This is a short description of the document that appears in

the Info directory of installed Info files.

For example, <samp>An Interactive Plotting Program.</samp>

</para><quotation><para>Note</para><para>

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.

</para></quotation></listitem></varlistentry><varlistentry><term>index-category</term><listitem><para>Brief.  The Texinfo index to use</para><para>Default setting.  <samp>cp</samp></para><para>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.

</para><para>

The predefined indices are:

<varlist><varlistentry><term><samp>c</samp></term><term><samp>cp</samp></term><listitem><para>Concept index</para></listitem></varlistentry><varlistentry><term><samp>f</samp></term><term><samp>fn</samp></term><listitem><para>Function index</para></listitem></varlistentry><varlistentry><term><samp>v</samp></term><term><samp>vr</samp></term><listitem><para>Variable index</para></listitem></varlistentry><varlistentry><term><samp>k</samp></term><term><samp>ky</samp></term><listitem><para>Keystroke index</para></listitem></varlistentry><varlistentry><term><samp>p</samp></term><term><samp>pg</samp></term><listitem><para>Program index</para></listitem></varlistentry><varlistentry><term><samp>d</samp></term><term><samp>tp</samp></term><listitem><para>Data type index</para></listitem></varlistentry></varlist>

User-defined indices are not yet supported.

</para></listitem></varlistentry><varlistentry><term>qanda-defaultlabel</term><listitem><para>Brief.  Sets the default for defaultlabel on QandASet.</para><para>Default setting.  <samp/></para><para>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.

</para></listitem></varlistentry><varlistentry><term>qandaset-generate-toc</term><listitem><para>Brief.  Is a Table of Contents created for QandASets?</para><para>Default setting.  <samp/></para><para>If true, a ToC is constructed for QandASets.

</para></listitem></varlistentry></varlist><subheading>Examples</subheading><indexterm class="cp">example usage</indexterm><example>$ docbook2texi tdg.xml

$ docbook2texi --encoding=utf-8//TRANSLIT tdg.xml

$ docbook2texi --string-param semantic-decorations=0 tdg.xml

</example><subheading>Limitations</subheading><itemize markchar="•"><listitem><para>

      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.

    </para></listitem></itemize><node id="db2x_texixml" previousid="docbook2texi" upid="texinfo"/><section>db2x_texixml</section><indexterm class="cp">Texinfo</indexterm><indexterm class="cp">converting to Texinfo</indexterm><indexterm class="cp">Texi-XML</indexterm><indexterm class="cp">encoding</indexterm><indexterm class="cp">output directory</indexterm><indexterm class="cp">makeinfo</indexterm><subheading>Name</subheading><para>db2x_texixml — Make Texinfo files from Texi-XML</para><subheading>Synopsis</subheading><quotation><para><t>db2x_texixml [options]… [xml-document]</t></para></quotation><subheading>Description</subheading><para>

db2x_texixml converts a Texi-XML document into one or 

more Texinfo documents.

</para><para>

If xml-document is not given, then the document

to convert comes from standard input.  

</para><para>

The filenames of the Texinfo documents are determined by markup in the

Texi-XML source.  (If the filenames are not specified in the markup,

then db2x_texixml attempts to deduce them from the name of the input

file.  However, the Texi-XML source should specify the filename, because

it does not work when there are multiple output files or when the

Texi-XML source comes from standard input.)

</para><subheading>Options</subheading><varlist><varlistentry><term>--encoding=encoding</term><listitem><para>

Select the character encoding used for the output files.

The available encodings are those of 

iconv(1). 

The default encoding is <samp>us-ascii</samp>.  

</para><para>

The XML source may contain characters that are not representable in the encoding that

you select;  in this case the program will bomb out during processing, and you should 

choose another encoding.

(This is guaranteed not to happen with any Unicode encoding such as 

UTF-8, but unfortunately not everyone is able to 

process Unicode texts.)

</para><para>

If you are using GNU’s version of 

iconv(1), you can affix 

<samp>//TRANSLIT</samp> to the end of the encoding name

to attempt transliterations of any unconvertible characters in the output.

Beware, however, that the really inconvertible characters will be turned

into another of those damned question marks.  (Aren’t you sick of this?)

</para><para>

The suffix <samp>//TRANSLIT</samp> applied

to a Unicode encoding — in particular, <samp>utf-8//TRANSLIT</samp> —

means that the output files are to remain in Unicode,

but markup-level character translations using utf8trans 

are still to be done.  So in most cases, an English-language

document, converted using 

--encoding=<samp>utf-8//TRANSLIT</samp>

will actually end up as a US-ASCII document,

but any untranslatable characters 

will remain as UTF-8 without any warning whatsoever.

(Note: strictly speaking this is not “transliteration”.)

This method of conversion is a compromise over strict

--encoding=<samp>us-ascii</samp>

processing, which aborts if any untranslatable characters are 

encountered.

</para><para>

Note that man pages and Texinfo documents 

in non-ASCII encodings (including UTF-8)

may not be portable to older (non-internationalized) systems,

which is why the default value for this option is 

<samp>us-ascii</samp>.

</para><para>

To suppress any automatic character mapping or encoding conversion

whatsoever, pass the option 

--encoding=<samp>utf-8</samp>.

</para></listitem></varlistentry><varlistentry><term>--list-files</term><listitem><para>

Write a list of all the output files to standard output,

in addition to normal processing.

</para></listitem></varlistentry><varlistentry><term>--output-dir=dir</term><listitem><para>

Specify the directory where the output files are placed.

The default is the current working directory.

</para><para>

This option is ignored if the output is to be written

to standard output (triggered by the 

option --to-stdout).

</para></listitem></varlistentry><varlistentry><term>--to-stdout</term><listitem><para>

Write the output to standard output instead of to individual files.

</para><para>

If this option is used even when there are supposed to be multiple

output documents, then everything is concatenated to standard output.

But beware that most other programs will not accept this concatenated

output.

</para><para>

This option is incompatible with --list-files,

obviously.

</para></listitem></varlistentry><varlistentry><term>--info</term><listitem><para>Pipe the Texinfo output to 

makeinfo(1),

            creating Info files directly instead of

            Texinfo files.</para></listitem></varlistentry><varlistentry><term>--plaintext</term><listitem><para>Pipe the Texinfo output to makeinfo

            --no-headers, thereby creating

            plain text files.</para></listitem></varlistentry><varlistentry><term>--help</term><listitem><para>Show brief usage information and exit.</para></listitem></varlistentry><varlistentry><term>--version</term><listitem><para>Show version and exit.</para></listitem></varlistentry></varlist><para>

This program uses certain other programs for its operation.

If they are not in their default installed locations, then use

the following options to set their location:

<varlist><varlistentry><term>--utf8trans-program=path</term><term>--utf8trans-map=charmap</term><listitem><para>Use the character map charmap

with the <ref idref="utf8trans">utf8trans</ref> program, included with docbook2X, found

under path.</para></listitem></varlistentry><varlistentry><term>--iconv-program=path</term><listitem><para>The location of the 

iconv(1) program, used for encoding

conversions.</para></listitem></varlistentry></varlist></para><subheading>Notes</subheading><para>Texinfo language compatibility.  

    <indexterm class="cp">compatibility</indexterm>

    The Texinfo files generated by db2x_texixml sometimes require

    Texinfo version 4.7 (the latest version) to work properly.

    In particular:

    <itemize markchar="•"><listitem><para>   

        db2x_texixml relies on makeinfo

        to automatically add punctuation after a @ref

        if it it not already there.  Otherwise the hyperlink will 

        not work in the Info reader (although

        makeinfo will not emit any error).

      </para></listitem><listitem><para>

        The new @comma{} command is used for commas

        (<samp>,</samp>) occurring inside argument lists to 

        Texinfo commands, to disambiguate it from the comma used

        to separate different arguments.  The only alternative 

        otherwise would be to translate <samp>,</samp> to 

        <samp>.</samp>

        which is obviously undesirable (but earlier docbook2X versions

        did this).</para><para>If you cannot use version 4.7 of

        makeinfo, you can still use a

        sed script to perform manually the procedure 

        just outlined.</para></listitem></itemize>

  </para><para>Relation of Texi-XML with the XML output format of makeinfo.  

    The Texi-XML format used by docbook2X is <emph>different</emph>

    and incompatible with the XML format generated by 

makeinfo(1)

    with its --xml option.

    This situation arose partly because the Texi-XML format

    of docbook2X was designed and implemented independently 

    before the appearance

    of makeinfo’s XML format.

    Also Texi-XML is very much geared towards being 

    <emph>machine-generated from other XML formats</emph>,

    while there seems to be no non-trivial applications

    of makeinfo’s XML format.

    So there is no reason at this point for docbook2X

    to adopt makeinfo’s XML format

    in lieu of Texi-XML.

  </para><subheading>Bugs</subheading><itemize markchar="•"><listitem><para>

      Text wrapping in menus is utterly broken for non-ASCII text.

      It is probably also broken everywhere else in the output, but 

      that would be makeinfo’s fault.

    </para></listitem><listitem><para>

      --list-files might not work correctly

      with --info.  Specifically, when the output

      Info file get too big, makeinfo will decide

      to split it into parts named 

      <file>abc.info-1</file>,

      <file>abc.info-2</file>,

      <file>abc.info-3</file>, etc.

      db2x_texixml does not know exactly how many of these files

      there are, though you can just do an ls 

      to find out.

    </para></listitem></itemize><subheading>See Also</subheading><para>

The input to db2x_texixml is defined by the XML DTD

present at <file>dtd/Texi-XML</file> in the docbook2X

distribution.

</para><node id="xsltproc" previousid="texinfo" nextid="charsets" upid="docbook2X"/><chapter>The XSLT stylesheets</chapter><indexterm class="cp">XSLT processor</indexterm><indexterm class="cp">libxslt</indexterm><indexterm class="cp">SAXON</indexterm><indexterm class="cp">catalog</indexterm><indexterm class="cp">db2x_xsltproc</indexterm><para>

docbook2X uses a XSLT 1.0 processor to run its stylesheets.

docbook2X comes with a wrapper script,

<ref idref="db2x_xsltproc">db2x_xsltproc</ref>, that invokes the XSLT processor, 

but you can invoke the XSLT processor in any other

way you wish.

</para><para>

The stylesheets are described in

<ref node="Top" file="docbook2man-xslt" printmanual="docbook2X Man-pages Stylesheets Reference">the man-pages stylesheets

reference</ref>

and <ref node="Top" file="docbook2texi-xslt" printmanual="docbook2X Texinfo Stylesheets Reference">the Texinfo stylesheets

reference</ref>.

</para><indexterm class="cp">pure XSLT</indexterm><indexterm class="cp">xsltproc</indexterm><para>

Pure-XSLT implementations of db2x_manxml

and db2x_texixml also exist.  

They may be used as follows (assuming libxslt as the XSLT processor).

<anchor id="xsltproc.db2x_manxml"/><para>Convert to man pages using pure-XSLT db2x_manxml</para><example>$ xsltproc -o mydoc.mxml \

    docbook2X-path/xslt/man/docbook.xsl \

    mydoc.xml

$ xsltproc \

    docbook2X-path/xslt/backend/db2x_manxml.xsl \

    mydoc.mxml</example>

<anchor id="xsltproc.db2x_texixml"/><para>Convert to Texinfo using Pure-XSLT db2x_texixml</para><example>$ xsltproc -o mydoc.txml \

    docbook2X-path/xslt/texi/docbook.xsl \

    mydoc.xml

$ xsltproc \

    docbook2X-path/xslt/backend/db2x_texixml.xsl \

    mydoc.txml</example>

</para><para>

Here, 

xsltproc(1) is used instead of db2x_xsltproc, since

if you are in a situtation where you cannot use the Perl implementation 

of db2x_manxml, you probably cannot use db2x_xsltproc either.

</para><para>

If for portability reasons you prefer not to use the file-system path 

to the docbook2X files, you can use the XML catalog

provided in <file>xslt/catalog.xml</file>

and the global URIs contained therein.

</para><menu><menuentry idref="db2x_xsltproc"><menuentrytitle>db2x_xsltproc</menuentrytitle><menuentrydescrip>XSLT processor invocation wrapper</menuentrydescrip></menuentry><menuentry idref="sgml2xml-isoent"><menuentrytitle>sgml2xml-isoent</menuentrytitle><menuentrydescrip>Convert SGML to XML with support for ISO

entities</menuentrydescrip></menuentry></menu><node id="db2x_xsltproc" nextid="sgml2xml-isoent" upid="xsltproc"/><section>db2x_xsltproc</section><indexterm class="cp">XSLT processor</indexterm><indexterm class="cp">libxslt</indexterm><indexterm class="cp">db2x_xsltproc</indexterm><subheading>Name</subheading><para>db2x_xsltproc — XSLT processor invocation wrapper</para><subheading>Synopsis</subheading><quotation><para><t>db2x_xsltproc [options]  xml-document </t></para></quotation><subheading>Description</subheading><para>

db2x_xsltproc invokes the XSLT 1.0 processor for docbook2X.

</para><para>

This command applies the XSLT stylesheet 

(usually given by the --stylesheet option)

to the XML document in the file xml-document.

The result is written to standard output (unless changed with 

--output).  

</para><para>

To read the source XML document from standard input,

specify <samp>-</samp> as the input document.

</para><subheading>Options</subheading><varlist><varlistentry><term>--version</term><listitem><para>

Display the docbook2X version.

</para></listitem></varlistentry></varlist><subsubheading>Transformation output options</subsubheading><varlist><varlistentry><term>--output file</term><term>-o file</term><listitem><para>

Write output to the given file (or URI), instead of standard output.

</para></listitem></varlistentry></varlist><subsubheading>Source document options</subsubheading><varlist><varlistentry><term>--xinclude</term><term>-I</term><listitem><para>

Process XInclude directives in the source document.

</para></listitem></varlistentry><varlistentry><term>--sgml</term><term>-S</term><listitem><indexterm class="cp">SGML</indexterm><para>

Indicate that the input document is SGML instead of XML.

You need this set this option if xml-document

is actually a SGML file.

</para><para>

SGML parsing is implemented by conversion to XML via 

sgml2xml(1) from the

SP package (or 

osx(1) from the OpenSP package).  All tag names in the

SGML file will be normalized to lowercase (i.e. the -xlower

option of 

sgml2xml(1) is used).  ID attributes are available

for the stylesheet (i.e. option -xid).  In addition,

any ISO SDATA entities used in the SGML document are automatically converted

to their XML Unicode equivalents.  (This is done by a

sed filter.)

</para><para>

The encoding of the SGML document, if it is not

<samp>us-ascii</samp>, must be specified with the standard

SP environment variables: <samp>SP_CHARSET_FIXED=1

SP_ENCODING=encoding</samp>.

(Note that XML files specify their encoding with the XML declaration

<samp><?xml version="1.0" encoding="encoding" ?></samp>

at the top of the file.)

</para><para>

The above conversion options cannot be changed.  If you desire different

conversion options, you should invoke 

sgml2xml(1) manually, and then pass

the results of that conversion to this program.

</para></listitem></varlistentry></varlist><subsubheading>Retrieval options</subsubheading><varlist><varlistentry><term>--catalogs catalog-files</term><term>-C catalog-files</term><listitem><indexterm class="cp">catalog</indexterm><para>

Specify additional XML catalogs to use for resolving Formal

Public Identifiers or URIs.  SGML catalogs are not supported.

</para><para>

These catalogs are <emph>not</emph> used for parsing an SGML

document under the --sgml option.  Use

the environment variable <env>SGML_CATALOG_FILES</env> instead