<?xml version="1.0" encoding="utf-8" ?>
<sect1 id="manpages" xreflabel="Converting to man pages">
<sect1info>
<abstract role="texinfo-node">
  <para>Details on man-page conversion</para>
</abstract>
</sect1info>
<title>Converting to man pages</title>

<indexterm><primary>man pages</primary></indexterm>
<indexterm><primary>converting to man pages</primary></indexterm>
<indexterm><primary>XSLT stylesheets</primary></indexterm>
<indexterm><primary>Man-XML</primary></indexterm>

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

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

</listitem>

<listitem>
<para>
Man-XML is converted to the actual man pages by &db2x_manxml_ref;.
</para>
</listitem>


</orderedlist>
</para>

<para>
The &docbook2man_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 man <replaceable>mydoc</replaceable>.xml -o <replaceable>mydoc</replaceable>.mxml</userinput>
<prompt>$ </prompt><userinput>db2x_manxml <replaceable>mydoc</replaceable>.mxml</userinput>
</screen>

</para>

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

<indexterm><primary>pure XSLT</primary></indexterm>
<formalpara>
<title>Pure XSLT conversion</title>

<para>
An alternative to the &db2x_manxml; Perl script is the XSLT
stylesheet in 
<filename>xslt/backend/db2x_manxml.xsl</filename>.
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.
<phrase role="html">
For instructions on how to use the stylesheet,
 see <xref linkend="xsltproc.db2x_manxml" />.</phrase>
</para>

</formalpara>

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

<refentry id="docbook2man">
<indexterm><primary>man pages</primary></indexterm>
<indexterm><primary>converting to man pages</primary></indexterm>
<indexterm><primary>wrapper script</primary></indexterm>
<indexterm><primary>&docbook2man;</primary></indexterm>
<refentryinfo>
<titleabbrev role="texinfo-node">&docbook2man; wrapper script</titleabbrev>
</refentryinfo>

<refmeta>
<refentrytitle>docbook2man</refentrytitle>
<manvolnum>1</manvolnum>
</refmeta>

<refnamediv>
<refname>&docbook2man;</refname>
<refpurpose>Convert DocBook to man pages</refpurpose>
</refnamediv>

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

<refsect1>
<title>Description</title>

<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><primary><sgmltag class="element">refentry</sgmltag></primary></indexterm>
Only the <sgmltag class="element">refentry</sgmltag> content
in the DocBook document is converted.
(To convert content outside of a <sgmltag class="element">refentry</sgmltag>,
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.
<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
from &db2x_xsltproc_ref; and &db2x_manxml_ref;.
</para>

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

<variablelist>
  &wrapper-script-common-options;
  
  <varlistentry>
    <term><option>--solinks</option></term>
    <listitem>
      <para>
        Make stub pages for alternate names for an output man page.
      </para>
    </listitem>
  </varlistentry>
</variablelist>

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

</refsect1>

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

<informalexample>
<screen
><prompt>$ </prompt><userinput>docbook2man --solinks manpages.xml</userinput>
<prompt>$ </prompt><userinput>docbook2man --solinks --encoding=utf-8//TRANSLIT manpages.xml</userinput>
<prompt>$ </prompt><userinput>docbook2man --string-param header-4="Free Recode 3.6" document.xml</userinput>
</screen>
</informalexample>
</refsect1>


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

<?man-SS-include manpages?>
<?man-SS-include charsets?>
<!-- ?man-SS-include performance? -->

<!-- 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/man/docbook.xsl</filename></member>
<member><filename><?install-datadir?>xslt/backend/db2x_manxml.xsl</filename></member>
<member><filename><?install-datadir?>xslt/catalog.xml</filename></member>
<member><filename><?install-datadir?>charmaps/roff.charmap</filename></member>
<member><filename><?install-datadir?>charmaps/roff.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_manxml_ref;</member>
<member>&utf8trans_ref;</member>
</simplelist>

&man-page-see-also;

</refsect1>

</refentry>

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

<refentry id="db2x_manxml">
<indexterm><primary>man pages</primary></indexterm>
<indexterm><primary>converting to man pages</primary></indexterm>
<indexterm><primary>Man-XML</primary></indexterm>
<indexterm><primary>stub pages</primary></indexterm>
<indexterm><primary>symbolic links</primary></indexterm>
<indexterm><primary>encoding</primary></indexterm>
<indexterm><primary>output directory</primary></indexterm>
<indexterm><primary>&db2x_manxml;</primary></indexterm>
<refmeta>
<refentrytitle id="db2x_manxml_name">&db2x_manxml;</refentrytitle>
<manvolnum>1</manvolnum>
</refmeta>

<refnamediv>
<refname>&db2x_manxml;</refname>
<refpurpose>Make man pages from Man-XML</refpurpose>
</refnamediv>

<refsynopsisdiv>
<cmdsynopsis>
<command>db2x_manxml</command>
<arg><replaceable>options</replaceable></arg>
<arg><replaceable>xml-document</replaceable></arg>
</cmdsynopsis>

</refsynopsisdiv>

<refsect1>
<title>Description</title>

<para>
&db2x_manxml; converts a Man-XML document into one or 
more man pages.  They are written in the current directory.
</para>

<para>
If <replaceable>xml-document</replaceable> is not given, then the document
to convert is read from standard input.  
</para>

</refsect1>

<refsect1>
<title>Options</title>

<variablelist>
&db2x_-common-options;
&common-options;
</variablelist>

<para>Some man pages may be referenced under two or more
names, instead of just one.  For example, 
<citerefentry><refentrytitle>strcpy</refentrytitle><manvolnum>3</manvolnum></citerefentry>
and
<citerefentry><refentrytitle>strncpy</refentrytitle><manvolnum>3</manvolnum></citerefentry>
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>

<variablelist>
<varlistentry>
<term><option>--symlinks</option></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><option>--solinks</option></term>
<listitem>
<para>Generate stub pages (using <literal>.so</literal> roff requests)
for the alternate names, pointing them to the real man page content.</para>
</listitem>
</varlistentry>

<varlistentry>
<term><option>--no-links</option></term>
<listitem>
<para>Do not make any alternative names available.
The man page can only be referenced under its principal name.
</para>
</listitem>
</varlistentry>
	 
</variablelist>

&db2x_-path-options;

</refsect1>

<refsect1>
<title>Notes</title>
<indexterm><primary>&groff;</primary></indexterm>
<indexterm><primary>compatibility</primary></indexterm>
<para>
The man pages produced should be compatible
with most troff implementations and other tools
that process man pages.
Some backwards-compatible &groff_ref; extensions
are used to make the output look nicer.
</para>
</refsect1>

&man-page-author-section;

<refsect1>
<title>See Also</title>
&man-page-see-also;

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

</refsect1>

</refentry>

</sect1>