1docbook2man(1)                     docbook2X                    docbook2man(1)
2
3
4

NAME

6       docbook2man - Convert DocBook to man pages
7

SYNOPSIS

9       docbook2man [options] xml-document
10

DESCRIPTION

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
15       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
19       The docbook2man command is a wrapper script for a  two-step  conversion
20       process.  See the section “CONVERSION PROCESS” below for details.
21

OPTIONS

23       The  available  options  are  essentially the union of the options from
24       db2x_xsltproc(1) and db2x_manxml(1).
25
26       Some commonly-used options are listed below:
27
28       --encoding=encoding
29              Sets the character encoding of the output.
30
31       --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
36       --sgml Accept an SGML source document as input instead of XML.
37
38       --solinks
39              Make stub pages for alternate names for an output man page.
40
41   STYLESHEET PARAMETERS
42       uppercase-headings
43              Brief.  Make headings uppercase?
44
45              Default setting.  1 (boolean true)
46
47              Headings in man page content should be or should not  be  upper‐
48              cased.
49
50       manvolnum-cite-numeral-only
51              Brief.  Man page section citation should use only the number
52
53              Default setting.  1 (boolean true)
54
55              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
60       quotes-on-literals
61              Brief.  Display quotes on literal elements?
62
63              Default setting.  0 (boolean false)
64
65              If true, render literal elements with quotes around them.
66
67       show-comments
68              Brief.  Display comment elements?
69
70              Default setting.  1 (boolean true)
71
72              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
77       function-parens
78              Brief.  Generate parentheses after a function?
79
80              Default setting.  0 (boolean false)
81
82              If  true,  the  formatting  of a <function> element will include
83              generated parenthesis.
84
85       xref-on-link
86              Brief.  Should link generate a cross-reference?
87
88              Default setting.  1 (boolean true)
89
90              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
96       header-3
97              Brief.  Third header text
98
99              Default setting.  (blank)
100
101              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
105       header-4
106              Brief.  Fourth header text
107
108              Default setting.  (blank)
109
110              Specifies the text of the fourth header of a man page.  If  emp‐
111              ty, the refmiscinfo content for the refentry is used.
112
113       header-5
114              Brief.  Fifth header text
115
116              Default setting.  (blank)
117
118              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
122       default-manpage-section
123              Brief.  Default man page section
124
125              Default setting.  1
126
127              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
132       custom-localization-file
133              Brief.  URI of XML document containing custom localization data
134
135              Default setting.  (blank)
136
137              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
142              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
148              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
153              To not use custom text translations, leave this parameter as the
154              empty string.
155
156       custom-l10n-data
157              Brief.  XML document containing custom localization data
158
159              Default setting.  document($custom-localization-file)
160
161              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
165              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
169              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
174       author-othername-in-middle
175              Brief.  Is othername in author a middle name?
176
177              Default setting.  1
178
179              If true, the othername of an author appears between  the  first‐
180              name and surname. Otherwise, othername is suppressed.
181

EXAMPLES

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

CONVERSION PROCESS

189   Converting to man pages
190       DocBook documents are converted to man pages in two steps:
191
192       1.  The DocBook source is converted by a XSLT stylesheet into an inter‐
193           mediate XML format, Man-XML.
194
195           Man-XML is simpler than DocBook and closer to the man page  format;
196           it is intended to make the stylesheets’ job easier.
197
198           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
201           http://docbook2x.sourceforge.net/latest/xslt/man/docbook.xsl
202
203           Run this stylesheet with db2x_xsltproc(1).
204
205           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
209       2.  Man-XML is converted to the actual man pages by db2x_manxml(1).
210
211       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
215       $ db2x_xsltproc -s man mydoc.xml -o mydoc.mxml
216       $ db2x_manxml mydoc.mxml
217       .fi
218
219       Options to the conversion stylesheet are described in
220       the man-pages stylesheets
221       reference.
222
223       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
238   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
244       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
254       So the Unicode character problem can be solved in two steps:
255
256       1.  utf8trans(1), a program included in docbook2X, maps Unicode charac‐
257           ters to markup-level escapes or transliterations.
258
259           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
264           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
270       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
274           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

FILES

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
286       The above files are distributed and installed by the docbook2X package.
287

NOTES

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

LIMITATIONS

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

AUTHOR

301       Steve Cheng <stevecheng@users.sourceforge.net>.
302

SEE ALSO

304       db2x_xsltproc(1), db2x_manxml(1), utf8trans(1)
305
306       The docbook2X manual (in Texinfo or HTML format) fully describes how to
307       convert DocBook to man pages and Texinfo.
308
309       Up-to-date information about this program can be found at the docbook2X
310       Web site ⟨http://docbook2x.sourceforge.net/⟩ .
311
312
313
314docbook2X 0.8.7                  18 April 2006                  docbook2man(1)
Impressum