<?xml version="1.0" encoding="utf-8" ?>
<!-- vim: sta et sw=2
-->
<sect1 id="texinfo" xreflabel="Converting to Texinfo">
<sect1info>
<abstract role="texinfo-node">
  <para>Details on Texinfo conversion</para>
</abstract>
</sect1info>

<title>Converting to Texinfo</title>

<indexterm><primary>Texinfo</primary></indexterm>
<indexterm><primary>converting to Texinfo</primary></indexterm>
<indexterm><primary>XSLT stylesheets</primary></indexterm>
<indexterm><primary>Texi-XML</primary></indexterm>

<para>
DocBook documents are converted to Texinfo in two steps:

<orderedlist>
<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
<filename>xslt/texi/docbook.xsl</filename>.
For portability, it should always be referred to
by the following URI:
<synopsis
>http://docbook2x.sourceforge.net/latest/xslt/texi/docbook.xsl
</synopsis>
</para>

<para>
Run this stylesheet with &db2x_xsltproc_ref;.
</para>

<indexterm><primary>customizing</primary></indexterm>
<formalpara>
<title>Customizing</title>
<para>
You can also customize the output by
creating your own XSLT stylesheet —
changing parameters or adding new templates —
and importing <filename>xslt/texi/docbook.xsl</filename>.
</para>
</formalpara>

</listitem>

<listitem>
<para>
Texi-XML is converted to the actual Texinfo files by &db2x_texixml_ref;.
</para>
</listitem>
</orderedlist>

</para>

<para>
The &docbook2texi_ref; command does both steps automatically,
but if any problems occur, you can see the errors more clearly
if you do each step separately:

<screen
><prompt>$ </prompt><userinput>db2x_xsltproc -s texi <replaceable>mydoc</replaceable>.xml -o <replaceable>mydoc</replaceable>.txml</userinput>
<prompt>$ </prompt><userinput>db2x_texixml <replaceable>mydoc</replaceable>.txml</userinput>
</screen>

</para>

<para>
Options to the conversion stylesheet are described
in <olink targetdocent="docbook2texi-xslt">the Texinfo stylesheets
reference</olink>.
</para>


<!-- ==================================================================== -->
<refentry id="docbook2texi">
<indexterm><primary>Texinfo</primary></indexterm>
<indexterm><primary>converting to Texinfo</primary></indexterm>
<indexterm><primary>wrapper script</primary></indexterm>
<indexterm><primary>&docbook2texi;</primary></indexterm>
<refentryinfo>
<titleabbrev role="texinfo-node">&docbook2texi; wrapper script</titleabbrev>
</refentryinfo>

<refmeta>
<refentrytitle>docbook2texi</refentrytitle>
<manvolnum>1</manvolnum>
</refmeta>

<refnamediv>
<refname>&docbook2texi;</refname>
<refpurpose>Convert DocBook to Texinfo</refpurpose>
</refnamediv>

<refsynopsisdiv>
<cmdsynopsis>
<command>docbook2texi</command>
<arg><replaceable>options</replaceable></arg>
<arg choice='plain'><replaceable>xml-document</replaceable></arg>
</cmdsynopsis>

</refsynopsisdiv>

<refsect1>
<title>Description</title>

<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.
<phrase role="man-page">See the section “CONVERSION PROCESS” below
for details.</phrase>
</para>

</refsect1>

<refsect1>
<title>Options</title>

<para>
The available options are essentially the union of the options
for &db2x_xsltproc_ref; and &db2x_texixml_ref;.
</para>

<para>
Some commonly-used options are listed below:
</para>

<variablelist>
  &wrapper-script-common-options;
</variablelist>

<refsect2>
<title>Stylesheet parameters</title>
<indexterm><primary>stylesheet parameters</primary></indexterm>
&docbook2texi-param;
</refsect2>

</refsect1>

<refsect1>
<title>Examples</title>
<indexterm><primary>example usage</primary></indexterm>

<informalexample>
<screen
><prompt>$ </prompt><userinput>docbook2texi tdg.xml</userinput>
<prompt>$ </prompt><userinput>docbook2texi --encoding=utf-8//TRANSLIT tdg.xml</userinput>
<prompt>$ </prompt><userinput>docbook2texi --string-param semantic-decorations=0 tdg.xml</userinput>
</screen>
</informalexample>
</refsect1>

<refsect1 role="man-page">
<title>Conversion process</title>

<?man-SS-include texinfo?>
<?man-SS-include charsets?>

<!-- Dummy element, needed to satisfy DTD content model -->
<remark role="html" />

</refsect1>

<refsect1 role="man-page">
<title>Files</title>
<simplelist type="vert">
<member><filename><?install-datadir?>xslt/texi/docbook.xsl</filename></member>
<member><filename><?install-datadir?>xslt/backend/db2x_texixml.xsl</filename></member>
<member><filename><?install-datadir?>xslt/catalog.xml</filename></member>
<member><filename><?install-datadir?>charmaps/texi.charmap.xml</filename></member>
<member><filename><?install-datadir?>charmaps/texi.charmap.xml</filename></member>
</simplelist>
<para>
The above files are distributed and installed by the docbook2X package.
</para>
</refsect1>

&wrapper-script-notes;
&wrapper-script-limitations;
&man-page-author-section;

<refsect1 role="man-page">
<title>See Also</title>

<simplelist type="inline">
<member>&db2x_xsltproc_ref;</member>
<member>&db2x_texixml_ref;</member>
<member>&utf8trans_ref;</member>
</simplelist>

&man-page-see-also;
</refsect1>

</refentry>

<!-- ==================================================================== -->


<refentry id="db2x_texixml">
<indexterm><primary>Texinfo</primary></indexterm>
<indexterm><primary>converting to Texinfo</primary></indexterm>
<indexterm><primary>Texi-XML</primary></indexterm>
<indexterm><primary>encoding</primary></indexterm>
<indexterm><primary>output directory</primary></indexterm>
<indexterm><primary>&makeinfo;</primary></indexterm>
<refmeta>
<refentrytitle id="db2x_texixml_name">&db2x_texixml;</refentrytitle>
<manvolnum>1</manvolnum>
</refmeta>

<refnamediv>
<refname>&db2x_texixml;</refname>
<refpurpose>Make Texinfo files from Texi-XML</refpurpose>
</refnamediv>

<refsynopsisdiv>
<cmdsynopsis>
<command>db2x_texixml</command>
<arg rep="repeat">options</arg>
<arg><replaceable>xml-document</replaceable></arg>
</cmdsynopsis>
</refsynopsisdiv>

<refsect1>
<title>Description</title>

<para>
&db2x_texixml; converts a Texi-XML document into one or 
more Texinfo documents.
</para>

<para>
If <replaceable>xml-document</replaceable> 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>

</refsect1>


<refsect1>
<title>Options</title>

<variablelist>
&db2x_-common-options;

  <varlistentry>
    <term><option>--info</option></term>
    <listitem>
      <para>Pipe the Texinfo output to &makeinfo_ref;,
            creating Info files directly instead of
            Texinfo files.</para>
    </listitem>
  </varlistentry>
  
  <varlistentry>
    <term><option>--plaintext</option></term>
    <listitem>
      <para>Pipe the Texinfo output to <command>makeinfo
            <option>--no-headers</option></command>, thereby creating
            plain text files.</para>
    </listitem>
  </varlistentry>

&common-options;

</variablelist>

&db2x_-path-options;

</refsect1>

<refsect1>
  <title>Notes</title>

  <formalpara>
  <title>Texinfo language compatibility</title>
  <para>
    <indexterm><primary>compatibility</primary></indexterm>
    The Texinfo files generated by &db2x_texixml; sometimes require
    Texinfo version 4.7 (the latest version) to work properly.
    In particular:
    
    <itemizedlist>
      <listitem><para>   
        &db2x_texixml; relies on &makeinfo;
        to automatically add punctuation after a <markup>@ref</markup>
        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 <markup>@comma{}</markup> command is used for commas
        (<literal>,</literal>) 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 <literal>,</literal> to 
        <literal>.</literal>
        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
        <command>sed</command> script to perform manually the procedure 
        just outlined.</para>
      </listitem>
    </itemizedlist>
  </para>
  </formalpara>

  <formalpara>
  <title>Relation of Texi-XML with the XML output format of &makeinfo;</title>
  <para>
    The Texi-XML format used by docbook2X is <emphasis>different</emphasis>
    and incompatible with the XML format generated by &makeinfo_ref;
    with its <option>--xml</option> 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 
    <emphasis>machine-generated from other XML formats</emphasis>,
    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>
  </formalpara>

</refsect1>
      

<refsect1>
  <title>Bugs</title>

  <itemizedlist>
    <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>
      <option>--list-files</option> might not work correctly
      with <option>--info</option>.  Specifically, when the output
      Info file get too big, &makeinfo; will decide
      to split it into parts named 
      <filename><replaceable>abc</replaceable>.info-1</filename>,
      <filename><replaceable>abc</replaceable>.info-2</filename>,
      <filename><replaceable>abc</replaceable>.info-3</filename>, etc.
      &db2x_texixml; does not know exactly how many of these files
      there are, though you can just do an <command>ls</command> 
      to find out.
    </para></listitem>
  </itemizedlist>
</refsect1>

&man-page-author-section;

<refsect1>
<title>See Also</title>

&man-page-see-also;

<para>
The input to &db2x_texixml; is defined by the XML DTD
present at <filename>dtd/Texi-XML</filename> in the docbook2X
distribution.
</para>

</refsect1>

</refentry>

</sect1>