1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
|
<!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>
|
