1docbook2man(1) docbook2X docbook2man(1)
2
6 docbook2man - Convert DocBook to man pages
7
9 docbook2man [options] xml-document
10
12 docbook2man converts the given DocBook XML document into man pages. By
13 default, the man pages will be output to the current directory.
14 Only the refentry content in the DocBook document is converted. (To
16 convert content outside of a refentry, stylesheet customization is re‐
17 quired. See the docbook2X package for details.)
18 The docbook2man command is a wrapper script for a two-step conversion
20 process. See the section “CONVERSION PROCESS” below for details.
21
23 The available options are essentially the union of the options from
24 db2x_xsltproc(1) and db2x_manxml(1).
25 Some commonly-used options are listed below:
27 --encoding=encoding
29 Sets the character encoding of the output.
30 --string-param parameter=value
32 Sets a stylesheet parameter (options that affect how the output
33 looks). See “Stylesheet parameters” below for the parameters
34 that can be set.
35 --sgml Accept an SGML source document as input instead of XML.
37 --solinks
39 Make stub pages for alternate names for an output man page.
40 STYLESHEET PARAMETERS
42 uppercase-headings
43 Brief. Make headings uppercase?
44 Default setting. 1 (boolean true)
46 Headings in man page content should be or should not be upper‐
48 cased.
49 manvolnum-cite-numeral-only
51 Brief. Man page section citation should use only the number
52 Default setting. 1 (boolean true)
54 When citing other man pages, the man-page section is either giv‐
56 en as is, or has the letters stripped from it, citing only the
57 number of the section (e.g. section 3x becomes 3). This option
58 specifies which style.
59 quotes-on-literals
61 Brief. Display quotes on literal elements?
62 Default setting. 0 (boolean false)
64 If true, render literal elements with quotes around them.
66 show-comments
68 Brief. Display comment elements?
69 Default setting. 1 (boolean true)
71 If true, comments will be displayed, otherwise they are sup‐
73 pressed. Comments here refers to the comment element, which
74 will be renamed remark in DocBook V4.0, not XML comments (<--
75 like this -->) which are unavailable.
76 function-parens
78 Brief. Generate parentheses after a function?
79 Default setting. 0 (boolean false)
81 If true, the formatting of a <function> element will include
83 generated parenthesis.
84 xref-on-link
86 Brief. Should link generate a cross-reference?
87 Default setting. 1 (boolean true)
89 Man pages cannot render the hypertext links created by link. If
91 this option is set, then the stylesheet renders a cross refer‐
92 ence to the target of the link. (This may reduce clutter). Oth‐
93 erwise, only the content of the link is rendered and the actual
94 link itself is ignored.
95 header-3
97 Brief. Third header text
98 Default setting. (blank)
100 Specifies the text of the third header of a man page, typically
102 the date for the man page. If empty, the date content for the
103 refentry is used.
104 header-4
106 Brief. Fourth header text
107 Default setting. (blank)
109 Specifies the text of the fourth header of a man page. If emp‐
111 ty, the refmiscinfo content for the refentry is used.
112 header-5
114 Brief. Fifth header text
115 Default setting. (blank)
117 Specifies the text of the fifth header of a man page. If empty,
119 the ‘manual name’, that is, the title of the book or reference
120 container is used.
121 default-manpage-section
123 Brief. Default man page section
124 Default setting. 1
126 The source document usually indicates the sections that each man
128 page should belong to (with manvolnum in refmeta). In case the
129 source document does not indicate man-page sections, this option
130 specifies the default.
131 custom-localization-file
133 Brief. URI of XML document containing custom localization data
134 Default setting. (blank)
136 This parameter specifies the URI of a XML document that de‐
138 scribes text translations (and other locale-specific informa‐
139 tion) that is needed by the stylesheet to process the DocBook
140 document.
141 The text translations pointed to by this parameter always over‐
143 ride the default text translations (from the internal parameter
144 localization-file). If a particular translation is not present
145 here, the corresponding default translation is used as a fall‐
146 back.
147 This parameter is primarily for changing certain punctuation
149 characters used in formatting the source document. The settings
150 for punctuation characters are often specific to the source doc‐
151 ument, but can also be dependent on the locale.
152 To not use custom text translations, leave this parameter as the
154 empty string.
155 custom-l10n-data
157 Brief. XML document containing custom localization data
158 Default setting. document($custom-localization-file)
160 This parameter specifies the XML document that describes text
162 translations (and other locale-specific information) that is
163 needed by the stylesheet to process the DocBook document.
164 This parameter is internal to the stylesheet. To point to an
166 external XML document with a URI or a file name, you should use
167 the custom-localization-file parameter instead.
168 However, inside a custom stylesheet (not on the command-line)
170 this paramter can be set to the XPath expression document(''),
171 which will cause the custom translations directly embedded in‐
172 side the custom stylesheet to be read.
173 author-othername-in-middle
175 Brief. Is othername in author a middle name?
176 Default setting. 1
178 If true, the othername of an author appears between the first‐
180 name and surname. Otherwise, othername is suppressed.
181
183 $ docbook2man --solinks manpages.xml
184 $ docbook2man --solinks --encoding=utf-8//TRANSLIT manpages.xml
185 $ docbook2man --string-param header-4="Free Recode 3.6" document.xml
186 .fi
187
189 Converting to man pages
190 DocBook documents are converted to man pages in two steps:
191 1. The DocBook source is converted by a XSLT stylesheet into an inter‐
193 mediate XML format, Man-XML.
194 Man-XML is simpler than DocBook and closer to the man page format;
196 it is intended to make the stylesheets’ job easier.
197 The stylesheet for this purpose is in xslt/man/docbook.xsl. For
199 portability, it should always be referred to by the following URI:
200 http://docbook2x.sourceforge.net/latest/xslt/man/docbook.xsl
202 Run this stylesheet with db2x_xsltproc(1).
204 Customizing. You can also customize the output by creating your
206 own XSLT stylesheet — changing parameters or adding new templates —
207 and importing xslt/man/docbook.xsl.
208 2. Man-XML is converted to the actual man pages by db2x_manxml(1).
210 The docbook2man command does both steps automatically, but if any prob‐
212 lems occur, you can see the errors more clearly if you do each step
213 separately:
214 $ db2x_xsltproc -s man mydoc.xml -o mydoc.mxml
216 $ db2x_manxml mydoc.mxml
217 .fi
218 Options to the conversion stylesheet are described in
220 the man-pages stylesheets
221 reference.
222 Pure XSLT conversion.
224 An alternative to the db2x_manxml Perl script is the XSLT
225 stylesheet in
226 xslt/backend/db2x_manxml.xsl.
227 This stylesheet performs a similar function
228 of converting Man-XML to actual man pages.
229 It is useful if you desire a pure XSLT
230 solution to man-page conversion.
231 Of course, the quality of the conversion using this stylesheet
232 will never be as good as the Perl db2x_manxml,
233 and it runs slower.
234 In particular, the pure XSLT version
235 currently does not support tables in man pages,
236 but its Perl counterpart does.
237 Character set conversion
239 When translating XML to legacy ASCII-based formats with poor support
240 for Unicode, such as man pages and Texinfo, there is always the problem
241 that Unicode characters in the source document also have to be trans‐
242 lated somehow.
243 A straightforward character set conversion from Unicode does not suf‐
245 fice, because the target character set, usually US-ASCII or ISO
246 Latin-1, do not contain common characters such as dashes and direction‐
247 al quotation marks that are widely used in XML documents. But document
248 formatters (man and Texinfo) allow such characters to be entered by a
249 markup escape: for example, \(lq for the left directional quote “. And
250 if a markup-level escape is not available, an ASCII transliteration
251 might be used: for example, using the ASCII less-than sign < for the
252 angle quotation mark ⟨.
253 So the Unicode character problem can be solved in two steps:
255 1. utf8trans(1), a program included in docbook2X, maps Unicode charac‐
257 ters to markup-level escapes or transliterations.
258 Since there is not necessarily a fixed, official mapping of Unicode
260 characters, utf8trans can read in user-modifiable character map‐
261 pings expressed in text files and apply them. (Unlike most charac‐
262 ter set converters.)
263 In charmaps/man/roff.charmap and charmaps/man/texi.charmap are
265 character maps that may be used for man-page and Texinfo conver‐
266 sion. The programs db2x_manxml(1) and db2x_texixml(1) will apply
267 these character maps, or another character map specified by the us‐
268 er, automatically.
269 2. The rest of the Unicode text is converted to some other character
271 set (encoding). For example, a French document with accented char‐
272 acters (such as é) might be converted to ISO Latin 1.
273 This step is applied after utf8trans character mapping, using the
275 iconv(1) encoding conversion tool. Both db2x_manxml(1) and
276 db2x_texixml(1) can call iconv(1) automatically when producing
277 their output.
278
280 /usr/local/share/docbook2X/xslt/man/docbook.xsl
281 /usr/local/share/docbook2X/xslt/backend/db2x_manxml.xsl
282 /usr/local/share/docbook2X/xslt/catalog.xml
283 /usr/local/share/docbook2X/charmaps/roff.charmap
284 /usr/local/share/docbook2X/charmaps/roff.charmap.xml
285 The above files are distributed and installed by the docbook2X package.
287
289 The docbook2man or the docbook2texi command described in this manual
290 page come from the docbook2X package. It should not be confused with
291 the command of the same name from the obsoleted docbook-utils package.
292
294 · Internally there is one long pipeline of programs which your document
295 goes through. If any segment of the pipeline fails (even trivially,
296 like from mistyped program options), the resulting errors can be dif‐
297 ficult to decipher — in this case, try running the components of doc‐
298 book2X separately.
299
301 Steve Cheng <stevecheng@users.sourceforge.net>.
302
304 db2x_xsltproc(1), db2x_manxml(1), utf8trans(1)
305 The docbook2X manual (in Texinfo or HTML format) fully describes how to
307 convert DocBook to man pages and Texinfo.
308 Up-to-date information about this program can be found at the docbook2X
310 Web site ⟨http://docbook2x.sourceforge.net/⟩ .
311docbook2X 0.8.7 18 April 2006 docbook2man(1)