<?xml version="1.0"?>
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
  "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" [

<!ENTITY % textents SYSTEM "../../doc/textents.xml">
%textents;
]>

<refentry id="docbook2manxml">
<refmeta>
<refentrytitle id="docbook2manxml_name">&docbook2manxml;</refentrytitle>
<manvolnum>1</manvolnum>
</refmeta>

<refnamediv>
<refname>&docbook2manxml;</refname>
<refpurpose>Convert DocBook to Man-XML</refpurpose>
</refnamediv>

<refsynopsisdiv>
<cmdsynopsis>
<command>docbook2manxml</command>
<arg><replaceable>options</replaceable></arg>
<arg choice="req"><replaceable>xml-document</replaceable></arg>
</cmdsynopsis>

</refsynopsisdiv>

<refsect1>
<title>Description</title>

<indexterm><primary>&docbook2manxml;</primary></indexterm>
<indexterm><primary>Man pages, converting to</primary></indexterm>

<para>
&docbook2manxml; is used to
convert DocBook documents to man pages.  Specifically, this
program reads XML DocBook documents and generates Man-XML, which is an
intermediate XML document type to be run through
&db2x_manxml; to produce man pages.
</para>

<para>
The document in the file <replaceable>xml-document</replaceable> is
converted and written to standard output.  
</para>

<para>
&docbook2manxml; does event-based parsing and does not
build a tree in memory; therefore it must be run two times on
each source document to properly resolve cross references and links.
</para>

</refsect1>

<refsect1>
<title>Options</title>

<variablelist>

<varlistentry>
<term><option>--sgml</option></term>
<listitem>
<para>
Specifies that the input document is SGML DocBook, rather than
XML DocBook.
</para>
</listitem>
</varlistentry>
		
<varlistentry>
<term><option>--sdata-map=<replaceable>file</replaceable></option></term>
<listitem><para>
When parsing SGML, specifies that SDATA entities are to be translated to
Unicode according to the given SDATA map.
</para></listitem>
</varlistentry>

<varlistentry>
<term><option>--refs-file=<replaceable>file</replaceable></option></term>
<listitem><para>
Cross-reference information generated in the normal course of operation
is read from and written to the given <replaceable>file</replaceable>.  
If not specified, the file <filename>manpage.refs</filename> is used.
</para></listitem>
</varlistentry>

<varlistentry>
<term><option>--header-3=<replaceable>string</replaceable></option></term>
<listitem><para>
Specifies the text of the third header of a man page,
typically the date for the man page.  If empty, the <sgmltag
class="element">date</sgmltag> content for the <sgmltag
class="element">refentry</sgmltag> is used.
</para></listitem>
</varlistentry>

<varlistentry>
<term><option>--header-4=<replaceable>string</replaceable></option></term>
<listitem><para>
Specifies the text of the fourth header of a man page.
If empty, the <sgmltag class="element">refmiscinfo</sgmltag> content for the 
<sgmltag class="element">refentry</sgmltag> is used.
</para></listitem>
</varlistentry>

<varlistentry>
<term><option>--header-5=<replaceable>string</replaceable></option></term>
<listitem><para>
Specifies the text of the fifth header of a man page.
If empty, the <quote>manual name</quote>, that is, the title of the <sgmltag
class="element">book</sgmltag> or <sgmltag
class="element">reference</sgmltag> container is used.
</para></listitem>
</varlistentry>

<varlistentry>
<term><option>--default-section=<replaceable>section</replaceable></option></term>
<listitem>
<para>
The source document usually indicates the sections that each man page
should belong to (with <sgmltag class="element">manvolnum</sgmltag> in
<sgmltag class="element">refmeta</sgmltag>).  In case the source
document does not indicate man-page sections, this option specifies the
default.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term><option>--default-language=<replaceable>language</replaceable></option></term>
<listitem>
<para>
If the source document does not indicate the human language it is
written in (using the <sgmltag class="attribute">lang</sgmltag>
attribute), the specified <replaceable>language</replaceable> is used.
If the document does not indicate its language and this option is not
given, <literal>en</literal> (English) is assumed.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term><option>--uppercase-headings</option></term>
<term><option>--nouppercase-headings</option></term>
<listitem>
<para>
Headings in man page content should be or should not be uppercased.
The default is to uppercase.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term><option>--cite-numeral-only</option></term>
<term><option>--nocite-numeral-only</option></term>
<listitem>
<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 <literal>3x</literal> becomes
<literal>3</literal>).  This option specifies which style.  The default
is <option>--cite-numeral-only</option>.
</para>

</listitem>
</varlistentry>

<varlistentry>
<term><option>--xref-on-link</option></term>
<term><option>--noxref-on-link</option></term>
<listitem>
<para>
Normally, a <sgmltag class="element">link</sgmltag> element generates
the cross reference in brackets after the link content.
Use <option>--noxref-on-link</option> to suppress the cross-reference.
<option>--xref-on-link</option> is the default.
</para>
</listitem>
</varlistentry>

</variablelist>

</refsect1>

<refsect1>
<title>Processing Expectations</title>

<para>
This section describes how &docbook2manxml; treats
certain markup, in ways that are not specified in the 
DocBook documentation.  If you follow these rules and the standard
processing expectations judiciously, you should be able to create 
good man pages and other formats from one single source with a minimal
amount of conditional processing.
</para>

<variablelist>

<varlistentry>
<term><sgmltag class="element">link</sgmltag></term>
<listitem>
<para>
In man pages, you should probably avoid using <sgmltag
class="element">link</sgmltag>, because man pages cannot render
hypertext links.  Instead, the cross reference is rendered in brackets 
after the link text, or suppressed, depending on the
<option>--xref-on-link</option> option.  Rendering the cross reference
can clutter the man page, while suppressing the cross reference and
displaying only the link content may obviously be undesirable.  <sgmltag
class="element">xref</sgmltag> is more suitable in some situations.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term><sgmltag class="element">citerefentry</sgmltag></term>
<listitem>
<para>
<sgmltag class="element">citerefentry</sgmltag> may be used to refer to
either a <sgmltag class="element">refentry</sgmltag> in the same document
or any other man page.  (Pointing to any other man page is an extension of the
standard processing expectations.)
</para>

<para>
According to standard processing expectations, all display formats
should use a man-page-style citation (without an implicit link or cross
reference) for this element. Of course, in man pages the citation is the
cross reference.  
</para>

<para>
Use this element when a man page should have an inline citation to another
man page, while other display formats should not render a cross
reference to that other man page or section (that might not be in the
same document).  If a cross reference should also be rendered in the
other display formats, then use <sgmltag class="element">xref</sgmltag>
instead.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term><sgmltag class="element">refentry</sgmltag></term>
<listitem>
<para>
&docbook2manxml; only renders the <sgmltag
class="element">refentry</sgmltag>s in the document. 
Most man pages have to follow a strict style, and therefore converting
non-<sgmltag class="element">refentry</sgmltag> content is generally not
appropriate.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term><sgmltag class="element">xref</sgmltag></term>
<listitem>
<para>
If the cross reference points to <sgmltag class="element">refentry</sgmltag>,
then a standard man page citation is made.  Otherwise, the title of the
section that is pointed to is displayed.
</para>

<para>
<sgmltag class="element">xref</sgmltag> should be used to refer to other
sections of your document, particularly man page sections.
&docbook2manxml; does not use the <sgmltag
class="attribute">endterm</sgmltag> attribute and always renders a
man-page-style citation for this element.  (Other display formats can
generate the appropriate cross-reference text even if <sgmltag
class="attribute">endterm</sgmltag> is not given.)
</para>

<para>
Many man pages have a <quote>See Also</quote> section that list any
cross references, while other display formats would have them embedded
inline only.  &docbook2manxml; does not automatically
generate the <quote>See Also</quote> section.  Consider writing an
equivalent <sgmltag class="element">refsect1</sgmltag> with the cross
references listed as <sgmltag class="element">xref</sgmltag>s.
</para>

</listitem>
</varlistentry>

</variablelist>
</refsect1>


<refsect1>
<title>Examples</title>
<example>
<title>Converting DocBook source to man pages</title>

<screen
><prompt>$</prompt> docbook2manxml --header-3=`date "+%d %B %Y"` \
   --header-5="Jane Hacker's Amazing Manual" \
   --refs-file=<replaceable>mydoc</replaceable>.refs \
   <replaceable>mydoc</replaceable>.xml ><replaceable>mydoc</replaceable>.mxml
<prompt>$</prompt> db2x_manxml --solinks <replaceable>mydoc</replaceable>.mxml
</screen>

<para>Or more succinctly,

<screen
><prompt>$</prompt> docbook2manxml <replaceable>mydoc</replaceable>.xml | db2x_manxml --solinks
</screen>

</para>

</example>

</refsect1>
 
<refsect1>
<title>Environment</title>

<variablelist>
<varlistentry>
<term><envar>XML_CATALOG_FILES</envar></term>
<listitem><para>Use specified XML Catalogs when parsing the document.
If not specified, the system's default is assumed.  </para>
<para>
When parsing SGML, XML catalogs are not used and this setting is ignored.  
When parsing XML, <envar>XML_CATALOG_FILES</envar> always takes precedence 
over <envar>SGML_CATALOG_FILES</envar>.
</para></listitem>
</varlistentry>

<varlistentry>
<term><envar>SGML_CATALOG_FILES</envar></term>
<listitem><para>Use specified OASIS TR9041 catalogs when parsing the document.
If not specified, the system's default is assumed. 
</para></listitem>
</varlistentry>

</variablelist>

</refsect1>


<refsect1>
<title>See Also</title>
<simplelist>
<member>&db2x_manxml;</member>
</simplelist>
</refsect1>

</refentry>