<!ENTITY db2x_version SYSTEM "../VERSION">

<!ENTITY docbook2manxml "<command>docbook2manxml</command>">

<!ENTITY sgml2xml-isoent "<command>sgml2xml-isoent</command>">
<!ENTITY sgml2xml-isoent_ref 
  '<xref linkend="sgml2xml-isoent" endterm="sgml2xml-isoent_name" />'>

<!ENTITY db2x_xsltproc "<command>db2x_xsltproc</command>">
<!ENTITY db2x_xsltproc_ref 
  '<xref linkend="db2x_xsltproc" endterm="db2x_xsltproc_name" />'>

<!ENTITY db2x_manxml "<command>db2x_manxml</command>">
<!ENTITY db2x_manxml_ref 
  '<xref linkend="db2x_manxml" endterm="db2x_manxml_name" />'>

<!ENTITY db2x_texixml "<command>db2x_texixml</command>">
<!ENTITY db2x_texixml_ref 
  '<xref linkend="db2x_texixml" endterm="db2x_texixml_name" />'>

<!ENTITY docbook2man "<command>docbook2man</command>">
<!ENTITY docbook2man_ref 
  '<link linkend="docbook2man">&docbook2man;</link>'>

<!ENTITY docbook2texi "<command>docbook2texi</command>">
<!ENTITY docbook2texi_ref 
  '<link linkend="docbook2texi">&docbook2texi;</link>'>

<!ENTITY utf8trans "<command>utf8trans</command>">
<!ENTITY utf8trans_ref 
  '<xref linkend="utf8trans" endterm="utf8trans_name" />'>

<!ENTITY iconv "
<citerefentry><refentrytitle><command>iconv</command></refentrytitle>
<manvolnum>1</manvolnum></citerefentry>">

<!ENTITY xsltproc_cmd "
<citerefentry><refentrytitle><command>xsltproc</command></refentrytitle>
<manvolnum>1</manvolnum></citerefentry>">

<!ENTITY sgml2xml "
<citerefentry><refentrytitle><command>sgml2xml</command></refentrytitle>
<manvolnum>1</manvolnum></citerefentry>">

<!ENTITY osx "
<citerefentry><refentrytitle><command>osx</command></refentrytitle>
<manvolnum>1</manvolnum></citerefentry>">

<!ENTITY makeinfo_ref "
<citerefentry><refentrytitle><command>makeinfo</command></refentrytitle>
<manvolnum>1</manvolnum></citerefentry>">
<!ENTITY makeinfo "<command>makeinfo</command>">

<!ENTITY groff_ref "
<citerefentry><refentrytitle><command>groff</command></refentrytitle>
<manvolnum>1</manvolnum></citerefentry>">
<!ENTITY groff "<command>groff</command>">

<!-- ============================================================ -->
<!-- Common text to man pages and Texinfo parts -->


<!-- With some more work we can have make the stylesheet
     insert this boilerplate on every man page, but it's easier
     to just put the entity in directly. -->
<!ENTITY man-page-author-section "
<refsect1 role='man-page'>
<title>Author</title>

<para>
Steve Cheng <email>stevecheng@users.sourceforge.net</email>.
</para>

</refsect1>">

<!ENTITY wrapper-script-common-options "
  <varlistentry>
    <term><option>--encoding=<replaceable>encoding</replaceable></option></term>
    <listitem>
      <para>
        Sets the character encoding of the output.
      </para>
    </listitem>
  </varlistentry>

  <varlistentry>
    <term><option>--string-param <replaceable>parameter</replaceable>=<replaceable>value</replaceable></option></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><option>--sgml</option></term>
    <listitem>
      <para>
        Accept an SGML source document as input instead of XML.
      </para>
    </listitem>
  </varlistentry>
">

<!ENTITY wrapper-script-limitations "
<refsect1>
  <title>Limitations</title>
  <itemizedlist>
    <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>
  </itemizedlist>
</refsect1>
">

<!ENTITY wrapper-script-notes "
<refsect1 role='man-page'>
<title>Notes</title>
<para>
The <command>docbook2man</command> or the <command>docbook2texi</command> 
command described in this manual page
come from the docbook2X package.
It should not be confused with the command of the same
name from the obsoleted docbook-utils package.
</para>
</refsect1>
">



<!ENTITY man-page-see-also "
<para role='man-page'>
The docbook2X manual (in Texinfo or HTML format) fully describes
how to convert DocBook to man pages and Texinfo.
</para>

<para role='man-page'>
Up-to-date information about this program
can be found 
at the 
<ulink url='http://docbook2x.sourceforge.net/'>docbook2X Web site</ulink>.
</para>
">



<!ENTITY common-options	"
<varlistentry>
<term><option>--help</option></term>
<listitem>
<para>Show brief usage information and exit.</para>
</listitem>
</varlistentry>

<varlistentry>
<term><option>--version</option></term>
<listitem>
<para>Show version and exit.</para>
</listitem>
</varlistentry>">



<!ENTITY db2x_-common-options "
<varlistentry>
<term><option>--encoding=<replaceable>encoding</replaceable></option></term>
<listitem>
<para>
Select the character encoding used for the output files.
The available encodings are those of &iconv;. 
The default encoding is <literal>us-ascii</literal>.  
</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;, you can affix 
<literal>//TRANSLIT</literal> 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 <literal>//TRANSLIT</literal> applied
to a Unicode encoding — in particular, <literal>utf-8//TRANSLIT</literal> —
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 
<option>--encoding=<literal>utf-8//TRANSLIT</literal></option>
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
<option>--encoding=<literal>us-ascii</literal></option>
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 
<literal>us-ascii</literal>.
</para>

<para>
To suppress any automatic character mapping or encoding conversion
whatsoever, pass the option 
<option>--encoding=<literal>utf-8</literal></option>.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term><option>--list-files</option></term>
<listitem>
<para>
Write a list of all the output files to standard output,
in addition to normal processing.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term><option>--output-dir=<replaceable>dir</replaceable></option></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 <option>--to-stdout</option>).
</para>
</listitem>
</varlistentry>

<varlistentry>
<term><option>--to-stdout</option></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 <option>--list-files</option>,
obviously.
</para>
</listitem>
</varlistentry>">




<!ENTITY db2x_-path-options "
<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:

<variablelist>
<varlistentry>
<term><option>--utf8trans-program=<replaceable>path</replaceable></option></term>
<term><option>--utf8trans-map=<replaceable>charmap</replaceable></option></term>
<listitem>
<para>Use the character map <replaceable>charmap</replaceable>
with the &utf8trans_ref; program, included with docbook2X, found
under <replaceable>path</replaceable>.</para>
</listitem>
</varlistentry>

<varlistentry>
<term><option>--iconv-program=<replaceable>path</replaceable></option></term>
<listitem>
<para>The location of the &iconv; program, used for encoding
conversions.</para>
</listitem>
</varlistentry>
</variablelist></para>
">