<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta name="generator" content=
"HTML Tidy for Linux/x86 (vers 1 September 2005), see www.w3.org" />
<meta http-equiv="Content-Type" content=
"text/html; charset=us-ascii" />
<title>docbook2X: docbook2man</title>
<link rel="stylesheet" href="docbook2X.css" type="text/css" />
<link rev="made" href="mailto:stevecheng@users.sourceforge.net" />
<meta name="generator" content="DocBook XSL Stylesheets V1.68.1" />
<link rel="start" href="docbook2X.html" title=
"docbook2X: Documentation Table of Contents" />
<link rel="up" href="manpages.html" title=
"docbook2X: Converting to man pages" />
<link rel="prev" href="manpages.html" title=
"docbook2X: Converting to man pages" />
<link rel="next" href="db2x_manxml.html" title=
"docbook2X: db2x_manxml" />
</head>
<body>
<div class="navheader">
<table width="100%" summary="Navigation header">
<tr>
<th colspan="3" align="center">docbook2man</th>
</tr>
<tr>
<td width="20%" align="left"><a accesskey="p" href=
"manpages.html"><< Previous</a> </td>
<th width="60%" align="center">Converting to man pages</th>
<td width="20%" align="right"> <a accesskey="n" href=
"db2x_manxml.html">Next >></a></td>
</tr>
</table>
<hr /></div>
<div class="refentry" lang="en" xml:lang="en"><a id="docbook2man"
name="docbook2man"></a>
<div class="titlepage"></div>
<a id="id2524051" class="indexterm" name="id2524051"></a><a id=
"id2524161" class="indexterm" name="id2524161"></a><a id=
"id2524167" class="indexterm" name="id2524167"></a><a id=
"id2524174" class="indexterm" name="id2524174"></a>
<div class="refnamediv">
<h2>Name</h2>
<p><span><strong class="command">docbook2man</strong></span>
— Convert DocBook to man pages</p>
</div>
<div class="refsynopsisdiv">
<h2>Synopsis</h2>
<div class="cmdsynopsis">
<p><code class="command">docbook2man</code> [<em class=
"replaceable"><code>options</code></em>] <em class=
"replaceable"><code>xml-document</code></em></p>
</div>
</div>
<div class="refsect1" lang="en" xml:lang="en"><a id="id2524255"
name="id2524255"></a>
<h2>Description</h2>
<p><span><strong class="command">docbook2man</strong></span>
converts the given DocBook XML document into man pages. By default,
the man pages will be output to the current directory.</p>
<p><a id="id2524274" class="indexterm" name="id2524274"></a> Only
the <code class="sgmltag-element">refentry</code> content in the
DocBook document is converted. (To convert content outside of a
<code class="sgmltag-element">refentry</code>, stylesheet
customization is required. See the docbook2X package for
details.)</p>
<p>The <span><strong class="command">docbook2man</strong></span>
command is a wrapper script for a two-step conversion process.</p>
</div>
<div class="refsect1" lang="en" xml:lang="en"><a id="id2524319"
name="id2524319"></a>
<h2>Options</h2>
<p>The available options are essentially the union of the options
from <a href="db2x_xsltproc.html"><span><strong class=
"command">db2x_xsltproc</strong></span></a> and <a href=
"db2x_manxml.html"><span><strong class=
"command">db2x_manxml</strong></span></a>.</p>
<p>Some commonly-used options are listed below:</p>
<div class="variablelist">
<dl>
<dt><span class="term"><code class="option">--encoding=<em class=
"replaceable"><code>encoding</code></em></code></span></dt>
<dd>
<p>Sets the character encoding of the output.</p>
</dd>
<dt><span class="term"><code class="option">--string-param
<em class="replaceable"><code>parameter</code></em>=<em class=
"replaceable"><code>value</code></em></code></span></dt>
<dd>
<p>Sets a stylesheet parameter (options that affect how the output
looks). See “Stylesheet parameters” below for the
parameters that can be set.</p>
</dd>
<dt><span class="term"><code class=
"option">--sgml</code></span></dt>
<dd>
<p>Accept an SGML source document as input instead of XML.</p>
</dd>
<dt><span class="term"><code class=
"option">--solinks</code></span></dt>
<dd>
<p>Make stub pages for alternate names for an output man page.</p>
</dd>
</dl>
</div>
<div class="refsect2" lang="en" xml:lang="en"><a id="id2524406"
name="id2524406"></a>
<h3>Stylesheet parameters</h3>
<a id="id2524411" class="indexterm" name="id2524411"></a>
<div class="variablelist">
<dl>
<dt><span class="term"><em class=
"parameter"><code>uppercase-headings</code></em></span></dt>
<dd>
<p><b>Brief. </b>Make headings uppercase?</p>
<p><b>Default setting. </b><code class="literal">1</code>
(boolean true)</p>
<p>Headings in man page content should be or should not be
uppercased.</p>
</dd>
<dt><span class="term"><em class=
"parameter"><code>manvolnum-cite-numeral-only</code></em></span></dt>
<dd>
<p><b>Brief. </b>Man page section citation should use only the
number</p>
<p><b>Default setting. </b><code class="literal">1</code>
(boolean true)</p>
<p>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 <code class="literal">3x</code>
becomes <code class="literal">3</code>). This option specifies
which style.</p>
</dd>
<dt><span class="term"><em class=
"parameter"><code>quotes-on-literals</code></em></span></dt>
<dd>
<p><b>Brief. </b>Display quotes on <code class=
"sgmltag-element">literal</code> elements?</p>
<p><b>Default setting. </b><code class="literal">0</code>
(boolean false)</p>
<p>If true, render <code class="sgmltag-element">literal</code>
elements with quotes around them.</p>
</dd>
<dt><span class="term"><em class=
"parameter"><code>show-comments</code></em></span></dt>
<dd>
<p><b>Brief. </b>Display <code class=
"sgmltag-element">comment</code> elements?</p>
<p><b>Default setting. </b><code class="literal">1</code>
(boolean true)</p>
<p>If true, comments will be displayed, otherwise they are
suppressed. Comments here refers to the <code class=
"sgmltag-element">comment</code> element, which will be renamed
<code class="sgmltag-element">remark</code> in DocBook V4.0, not
XML comments (<-- like this -->) which are unavailable.</p>
</dd>
<dt><span class="term"><em class=
"parameter"><code>function-parens</code></em></span></dt>
<dd>
<p><b>Brief. </b>Generate parentheses after a function?</p>
<p><b>Default setting. </b><code class="literal">0</code>
(boolean false)</p>
<p>If true, the formatting of a <code class=
"sgmltag-starttag"><function></code> element will include
generated parenthesis.</p>
</dd>
<dt><span class="term"><em class=
"parameter"><code>xref-on-link</code></em></span></dt>
<dd>
<p><b>Brief. </b>Should <code class=
"sgmltag-element">link</code> generate a cross-reference?</p>
<p><b>Default setting. </b><code class="literal">1</code>
(boolean true)</p>
<p>Man pages cannot render the hypertext links created by
<code class="sgmltag-element">link</code>. If this option is set,
then the stylesheet renders a cross reference to the target of the
link. (This may reduce clutter). Otherwise, only the content of the
<code class="sgmltag-element">link</code> is rendered and the
actual link itself is ignored.</p>
</dd>
<dt><span class="term"><em class=
"parameter"><code>header-3</code></em></span></dt>
<dd>
<p><b>Brief. </b>Third header text</p>
<p><b>Default setting. </b>(blank)</p>
<p>Specifies the text of the third header of a man page, typically
the date for the man page. If empty, the <code class=
"sgmltag-element">date</code> content for the <code class=
"sgmltag-element">refentry</code> is used.</p>
</dd>
<dt><span class="term"><em class=
"parameter"><code>header-4</code></em></span></dt>
<dd>
<p><b>Brief. </b>Fourth header text</p>
<p><b>Default setting. </b>(blank)</p>
<p>Specifies the text of the fourth header of a man page. If empty,
the <code class="sgmltag-element">refmiscinfo</code> content for
the <code class="sgmltag-element">refentry</code> is used.</p>
</dd>
<dt><span class="term"><em class=
"parameter"><code>header-5</code></em></span></dt>
<dd>
<p><b>Brief. </b>Fifth header text</p>
<p><b>Default setting. </b>(blank)</p>
<p>Specifies the text of the fifth header of a man page. If empty,
the “<span class="quote">manual name</span>”, that is,
the title of the <code class="sgmltag-element">book</code> or
<code class="sgmltag-element">reference</code> container is
used.</p>
</dd>
<dt><span class="term"><em class=
"parameter"><code>default-manpage-section</code></em></span></dt>
<dd>
<p><b>Brief. </b>Default man page section</p>
<p><b>Default setting. </b><code class="literal">1</code></p>
<p>The source document usually indicates the sections that each man
page should belong to (with <code class=
"sgmltag-element">manvolnum</code> in <code class=
"sgmltag-element">refmeta</code>). In case the source document does
not indicate man-page sections, this option specifies the
default.</p>
</dd>
<dt><span class="term"><em class=
"parameter"><code>custom-localization-file</code></em></span></dt>
<dd>
<p><b>Brief. </b>URI of XML document containing custom
localization data</p>
<p><b>Default setting. </b>(blank)</p>
<p>This parameter specifies the URI of a XML document that
describes text translations (and other locale-specific information)
that is needed by the stylesheet to process the DocBook
document.</p>
<p>The text translations pointed to by this parameter always
override the default text translations (from the internal parameter
<em class="parameter"><code>localization-file</code></em>). If a
particular translation is not present here, the corresponding
default translation is used as a fallback.</p>
<p>This parameter is primarily for changing certain punctuation
characters used in formatting the source document. The settings for
punctuation characters are often specific to the source document,
but can also be dependent on the locale.</p>
<p>To not use custom text translations, leave this parameter as the
empty string.</p>
</dd>
<dt><span class="term"><em class=
"parameter"><code>custom-l10n-data</code></em></span></dt>
<dd>
<p><b>Brief. </b>XML document containing custom localization
data</p>
<p><b>Default setting. </b><code class=
"literal">document($custom-localization-file)</code></p>
<p>This parameter specifies the XML document that describes text
translations (and other locale-specific information) that is needed
by the stylesheet to process the DocBook document.</p>
<p>This parameter is internal to the stylesheet. To point to an
external XML document with a URI or a file name, you should use the
<em class="parameter"><code>custom-localization-file</code></em>
parameter instead.</p>
<p>However, inside a custom stylesheet (<span class=
"emphasis"><em>not on the command-line</em></span>) this paramter
can be set to the XPath expression <code class=
"literal">document('')</code>, which will cause the custom
translations directly embedded inside the custom stylesheet to be
read.</p>
</dd>
<dt><span class="term"><em class=
"parameter"><code>author-othername-in-middle</code></em></span></dt>
<dd>
<p><b>Brief. </b>Is <code class=
"sgmltag-element">othername</code> in <code class=
"sgmltag-element">author</code> a middle name?</p>
<p><b>Default setting. </b><code class="literal">1</code></p>
<p>If true, the <code class="sgmltag-element">othername</code> of
an <code class="sgmltag-element">author</code> appears between the
<code class="sgmltag-element">firstname</code> and <code class=
"sgmltag-element">surname</code>. Otherwise, <code class=
"sgmltag-element">othername</code> is suppressed.</p>
</dd>
</dl>
</div>
</div>
</div>
<div class="refsect1" lang="en" xml:lang="en"><a id="id2525124"
name="id2525124"></a>
<h2>Examples</h2>
<a id="id2525130" class="indexterm" name="id2525130"></a>
<div class="informalexample">
<pre class="screen">
<code class="prompt">$ </code><strong class=
"userinput"><code>docbook2man --solinks manpages.xml</code></strong>
<code class="prompt">$ </code><strong class=
"userinput"><code>docbook2man --solinks --encoding=utf-8//TRANSLIT manpages.xml</code></strong>
<code class="prompt">$ </code><strong class=
"userinput"><code>docbook2man --string-param header-4="Free Recode 3.6" document.xml</code></strong>
</pre></div>
</div>
<div class="refsect1" lang="en" xml:lang="en"><a id="id2525799"
name="id2525799"></a>
<h2>Limitations</h2>
<div class="itemizedlist">
<ul>
<li>
<p>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.</p>
</li>
</ul>
</div>
</div>
</div>
<div class="navfooter">
<hr />
<table width="100%" summary="Navigation footer">
<tr>
<td width="40%" align="left"><a accesskey="p" href=
"manpages.html"><< Previous</a> </td>
<td width="20%" align="center"><a accesskey="u" href=
"manpages.html">Up</a></td>
<td width="40%" align="right"> <a accesskey="n" href=
"db2x_manxml.html">Next >></a></td>
</tr>
<tr>
<td width="40%" align="left" valign="top">Converting to man
pages </td>
<td width="20%" align="center"><a accesskey="h" href=
"docbook2X.html">Table of Contents</a></td>
<td width="40%" align="right" valign="top">
<span><strong class=
"command">db2x_manxml</strong></span></td>
</tr>
</table>
</div>
<p class="footer-homepage"><a href=
"http://docbook2x.sourceforge.net/" title=
"docbook2X: Home page">docbook2X home page</a></p>
</body>
</html>
