<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook V3.1//EN"
"http://www.oasis-open.org/docbook/sgml/3.1/docbook.dtd">
<refentry id="docbook2man-sgmlspl">
<refmeta>
<refentrytitle><command>docbook2man-sgmlspl</command></refentrytitle>
<manvolnum>1</manvolnum>
</refmeta>
<refnamediv>
<refname><command>docbook2man-spec.pl</command></refname>
<refname><command>docbook2man-spec_makelinks</command></refname>
<refpurpose>Convert DocBook to man pages</refpurpose>
</refnamediv>
<refsynopsisdiv>
<cmdsynopsis>
<command>sgmlspl</command>
<!-- this is really part of the 'command', so forget the {} decoration -->
<arg choice="plain">docbook2man-spec.pl</arg>
<arg><option>--section <replaceable>label</replaceable></option></arg>
<arg><option>--date <replaceable>date</replaceable></option></arg>
<group>
<arg><option>--lowercase</option></arg>
<arg><option>--preserve-case</option></arg>
</group>
<group>
<arg><option>--cite-numeral-only</option></arg>
<arg><option>--nocite-numeral-only</option></arg>
</group>
</cmdsynopsis>
<cmdsynopsis>
<command>nsgmls</command>
<arg><replaceable>sgml document</replaceable></arg>
<arg choice="plain">|</arg>
<command>sgmlspl</command>
<arg choice="plain">docbook2man-spec.pl</arg>
<arg rep="repeat">options</arg>
</cmdsynopsis>
<cmdsynopsis>
<command>docbook2man-spec_makelinks</command>
<arg choice="plain"><</arg>
<arg choice="req"><replaceable>manpage.links</replaceable></arg>
</cmdsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Description</title>
<indexterm><primary>docbook2man-spec.pl</primary></indexterm>
<indexterm><primary>Man pages, converting to</primary></indexterm>
<para><command>docbook2man-spec.pl</command> produces man pages
from SGML DocBook documents.</para>
<para><command>docbook2man-spec.pl</command> must be used with
<citerefentry><refentrytitle>sgmlspl</refentrytitle><manvolnum>1</manvolnum>
</citerefentry>, a Perl SGML processor script. It
reads ESIS, such as that produced by <citerefentry>
<refentrytitle><command>nsgmls</command></refentrytitle>
<manvolnum>1</manvolnum></citerefentry>, from standard input.
The content in <sgmltag class="element">refentry</sgmltag> is
converted.</para>
<para>The man pages are written to the current
directory. If a particular <sgmltag class="element">refentry</sgmltag>
does not have any <sgmltag class="element">refmeta</sgmltag> information,
then the man page will be written to standard output.</para>
<para>An additional file <filename>manpage.links</filename> will
contains any aliases of the man pages generated. This file is in the
format:
<synopsis><token
><replaceable>man page</replaceable></token> <token
>[tab]</token
> <token><replaceable>alias manpage</replaceable></token>
</synopsis>
The script <command>docbook2man-spec_makelinks</command> creates
alias man pages that include the content of the principal man page using
the <literal>.so</literal> request.
</para>
<para>If the source document has any forward references (<sgmltag
class="element">xref</sgmltag>s to man pages in the same document), then
<command>docbook2man-spec.pl</command> may have to be invoked
twice to completely resolve them. The <filename>manpage.refs</filename>
file keeps track of these cross references. </para>
<note>
<para>New projects are recommended to use <citerefentry>
<refentrytitle><command>docbook2manxml</command></refentrytitle><manvolnum>1</manvolnum>
</citerefentry> from docbook2X (a separate package) instead, which is superior to this tool.
</para>
</note>
</refsect1>
<refsect1>
<title>Options</title>
<variablelist>
<varlistentry>
<term>
<option>--section <replaceable>label</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>--date <replaceable>date</replaceable></option></term>
<listitem>
<para>Set <replaceable>date</replaceable> as the date to use for man pages
that do not specify the date (using <sgmltag class="element">docinfo</sgmltag>/<sgmltag
class="element">date</sgmltag> markup).
If this option is not specified, the current date is used.</para>
<note>
<para>The <replaceable>date</replaceable> must be given as one argument;
i.e. shell quoting may have to be used for dates with spaces.</para>
</note>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--lowercase</option></term>
<term><option>--preserve-case</option></term>
<listitem><para>
When <option>--lowercase</option> is in effect, man-page file names
(specified using <sgmltag class="element">refentrytitle</sgmltag>) are
case-folded to lowercase. Otherwise, no case-folding will be performed.
The latter is the default.
</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>
</variablelist>
</refsect1>
<refsect1>
<title>Examples</title>
<example>
<title>Converting DocBook source to man pages</title>
<screen
><prompt>$</prompt> nsgmls <replaceable>mydoc.sgml</replaceable> | sgmlspl docbook2man-spec.pl
<prompt>$</prompt> docbook2man-spec_makelinks <manpage.refs
</screen>
</example>
</refsect1>
<refsect1>
<title>Limitations</title>
<itemizedlist>
<listitem>
<para>This script fails if <command>nsgmls</command> is parsing a file
with the XML SGML declaration, because SGML folds identifiers to uppercase
while XML does not, and XML DocBook uses all lowercase. Thus XML files
must be parsed as SGML.
</listitem>
<listitem><para>The code is obfuscated.</para></listitem>
<listitem>
<para>Some types of markup are incorrectly handled, according to
standard processing expectations.</para>
</listitem>
</itemizedlist>
</refsect1>
</refentry>