1docbook2texi(1) docbook2X docbook2texi(1)
2
3
4
6 docbook2texi - Convert DocBook to Texinfo
7
9 docbook2texi [options] xml-document
10
12 docbook2texi converts the given DocBook XML document into one or more
13 Texinfo documents. By default, these Texinfo documents will be output
14 to the current directory.
15
16 The docbook2texi command is a wrapper script for a two-step conversion
17 process. See the section “CONVERSION PROCESS” below for details.
18
20 The available options are essentially the union of the options for
21 db2x_xsltproc(1) and db2x_texixml(1).
22
23 Some commonly-used options are listed below:
24
25 --encoding=encoding
26 Sets the character encoding of the output.
27
28 --string-param parameter=value
29 Sets a stylesheet parameter (options that affect how the output
30 looks). See “Stylesheet parameters” below for the parameters
31 that can be set.
32
33 --sgml Accept an SGML source document as input instead of XML.
34
35 STYLESHEET PARAMETERS
36 captions-display-as-headings
37 Brief. Use heading markup for minor captions?
38
39 Default setting. 0 (boolean false)
40
41 If true, title content in some (formal) objects are rendered
42 with the Texinfo @heading commands.
43
44 If false, captions are rendered as an emphasized paragraph.
45
46 links-use-pxref
47 Brief. Translate link using @pxref
48
49 Default setting. 1 (boolean true)
50
51 If true, link is translated with the hypertext followed by the
52 cross reference in parentheses.
53
54 Otherwise, the hypertext content serves as the cross-reference
55 name marked up using @ref. Typically info displays this contruct
56 badly.
57
58 explicit-node-names
59 Brief. Insist on manually constructed Texinfo node names
60
61 Default setting. 0 (boolean false)
62
63 Elements in the source document can influence the Texinfo node
64 name generation specifying either a xreflabel, or for the sec‐
65 tioning elements, a title with role='texinfo-node' in the *info
66 container.
67
68 However, for the majority of source documents, explicit Texinfo
69 node names are not available, and the stylesheet tries to gener‐
70 ate a reasonable one instead, e.g. from the normal title of an
71 element. The generated name may not be optimal. If this option
72 is set and the stylesheet needs to generate a name, a warning is
73 emitted and generate-id is always used for the name.
74
75 When the hashtable extension is not available, the stylesheet
76 cannot check for node name collisions, and in this case, setting
77 this option and using explicit node names are recommended.
78
79 This option is not set (i.e. false) by default.
80 Note
81
82 The absolute fallback for generating node names is using the
83 XSLT function generate-id, and the stylesheet always emits a
84 warning in this case regardless of the setting of explic‐
85 it-node-names.
86
87 show-comments
88 Brief. Display comment elements?
89
90 Default setting. 1 (boolean true)
91
92 If true, comments will be displayed, otherwise they are sup‐
93 pressed. Comments here refers to the comment element, which
94 will be renamed remark in DocBook V4.0, not XML comments (<--
95 like this -->) which are unavailable.
96
97 funcsynopsis-decoration
98 Brief. Decorate elements of a FuncSynopsis?
99
100 Default setting. 1 (boolean true)
101
102 If true, elements of the FuncSynopsis will be decorated (e.g.
103 bold or italic). The decoration is controlled by functions that
104 can be redefined in a customization layer.
105
106 function-parens
107 Brief. Generate parentheses after a function?
108
109 Default setting. 0 (boolean false)
110
111 If true, the formatting of a <function> element will include
112 generated parenthesis.
113
114 refentry-display-name
115 Brief. Output NAME header before 'RefName'(s)?
116
117 Default setting. 1 (boolean true)
118
119 If true, a "NAME" section title is output before the list of
120 'RefName's.
121
122 manvolnum-in-xref
123 Brief. Output manvolnum as part of refentry cross-reference?
124
125 Default setting. 1 (boolean true)
126
127 if true, the manvolnum is used when cross-referencing refentrys,
128 either with xref or citerefentry.
129
130 prefer-textobjects
131 Brief. Prefer textobject over imageobject?
132
133 Default setting. 1 (boolean true)
134
135 If true, the textobject in a mediaobject is preferred over any
136 imageobject.
137
138 (Of course, for output formats other than Texinfo, you usually
139 want to prefer the imageobject, but Info is a text-only format.)
140
141 In addition to the values true and false, this parameter may be
142 set to 2 to indicate that both the text and the images should be
143 output. You may want to do this because some Texinfo viewers
144 can read images. Note that the Texinfo @image command has its
145 own mechanism for switching between text and image output — but
146 we do not use this here.
147
148 The default is true.
149
150 semantic-decorations
151 Brief. Use Texinfo semantic inline markup?
152
153 Default setting. 1 (boolean true)
154
155 If true, the semantic inline markup of DocBook is translated in‐
156 to (the closest) Texinfo equivalent. This is the default.
157
158 However, because the Info format is limited to plain text, the
159 semantic inline markup is often distinguished by using explicit
160 quotes, which may not look good. You can set this option to
161 false to suppress these. (For finer control over the inline
162 formatting, you can use your own stylesheet.)
163
164 custom-localization-file
165 Brief. URI of XML document containing custom localization data
166
167 Default setting. (blank)
168
169 This parameter specifies the URI of a XML document that de‐
170 scribes text translations (and other locale-specific informa‐
171 tion) that is needed by the stylesheet to process the DocBook
172 document.
173
174 The text translations pointed to by this parameter always over‐
175 ride the default text translations (from the internal parameter
176 localization-file). If a particular translation is not present
177 here, the corresponding default translation is used as a fall‐
178 back.
179
180 This parameter is primarily for changing certain punctuation
181 characters used in formatting the source document. The settings
182 for punctuation characters are often specific to the source doc‐
183 ument, but can also be dependent on the locale.
184
185 To not use custom text translations, leave this parameter as the
186 empty string.
187
188 custom-l10n-data
189 Brief. XML document containing custom localization data
190
191 Default setting. document($custom-localization-file)
192
193 This parameter specifies the XML document that describes text
194 translations (and other locale-specific information) that is
195 needed by the stylesheet to process the DocBook document.
196
197 This parameter is internal to the stylesheet. To point to an
198 external XML document with a URI or a file name, you should use
199 the custom-localization-file parameter instead.
200
201 However, inside a custom stylesheet (not on the command-line)
202 this paramter can be set to the XPath expression document(''),
203 which will cause the custom translations directly embedded in‐
204 side the custom stylesheet to be read.
205
206 author-othername-in-middle
207 Brief. Is othername in author a middle name?
208
209 Default setting. 1
210
211 If true, the othername of an author appears between the first‐
212 name and surname. Otherwise, othername is suppressed.
213
214 output-file
215 Brief. Name of the Info file
216
217 Default setting. (blank)
218
219 This parameter specifies the name of the final Info file, over‐
220 riding the setting in the document itself and the automatic se‐
221 lection in the stylesheet. If the document is a set, this param‐
222 eter has no effect.
223 Important
224
225 Do not include the .info extension in the name.
226
227 (Note that this parameter has nothing to do with the name of the Texi-
228 XML output by the XSLT processor you are running this stylesheet from.)
229
230 directory-category
231 Brief. The categorization of the document in the Info directory
232
233 Default setting. (blank)
234
235 This is set to the category that the document should go under in
236 the Info directory of installed Info files. For example, Gener‐
237 al Commands.
238 Note
239
240 Categories may also be set directly in the source document. But
241 if this parameter is not empty, then it always overrides the
242 setting in the source document.
243
244 directory-description
245 Brief. The description of the document in the Info directory
246
247 Default setting. (blank)
248
249 This is a short description of the document that appears in the
250 Info directory of installed Info files. For example, An Inter‐
251 active Plotting Program.
252 Note
253
254 Menu descriptions may also be set directly in the source docu‐
255 ment. But if this parameter is not empty, then it always over‐
256 rides the setting in the source document.
257
258 index-category
259 Brief. The Texinfo index to use
260
261 Default setting. cp
262
263 The Texinfo index for indexterm and index is specified using the
264 role attribute. If the above elements do not have a role, then
265 the default specified by this parameter is used.
266
267 The predefined indices are:
268
269 c, cp Concept index
270
271 f, fn Function index
272
273 v, vr Variable index
274
275 k, ky Keystroke index
276
277 p, pg Program index
278
279 d, tp Data type index
280
281 User-defined indices are not yet supported.
282
283 qanda-defaultlabel
284 Brief. Sets the default for defaultlabel on QandASet.
285
286 Default setting.
287
288 If no defaultlabel attribute is specified on a QandASet, this
289 value is used. It must be one of the legal values for the de‐
290 faultlabel attribute.
291
292 qandaset-generate-toc
293 Brief. Is a Table of Contents created for QandASets?
294
295 Default setting.
296
297 If true, a ToC is constructed for QandASets.
298
300 $ docbook2texi tdg.xml
301 $ docbook2texi --encoding=utf-8//TRANSLIT tdg.xml
302 $ docbook2texi --string-param semantic-decorations=0 tdg.xml
303 .fi
304
306 Converting to Texinfo
307 DocBook documents are converted to Texinfo in two steps:
308
309 1. The DocBook source is converted by a XSLT stylesheet into an inter‐
310 mediate XML format, Texi-XML.
311
312 Texi-XML is simpler than DocBook and closer to the Texinfo format;
313 it is intended to make the stylesheets’ job easier.
314
315 The stylesheet for this purpose is in xslt/texi/docbook.xsl. For
316 portability, it should always be referred to by the following URI:
317
318 http://docbook2x.sourceforge.net/latest/xslt/texi/docbook.xsl
319
320 Run this stylesheet with db2x_xsltproc(1).
321
322 Customizing. You can also customize the output by creating your
323 own XSLT stylesheet — changing parameters or adding new templates —
324 and importing xslt/texi/docbook.xsl.
325
326 2. Texi-XML is converted to the actual Texinfo files by db2x_tex‐
327 ixml(1).
328
329 The docbook2texi command does both steps automatically, but if any
330 problems occur, you can see the errors more clearly if you do each step
331 separately:
332
333 $ db2x_xsltproc -s texi mydoc.xml -o mydoc.txml
334 $ db2x_texixml mydoc.txml
335 .fi
336
337 Options to the conversion stylesheet are described
338 in the Texinfo stylesheets
339 reference.
340
341 Character set conversion
342 When translating XML to legacy ASCII-based formats with poor support
343 for Unicode, such as man pages and Texinfo, there is always the problem
344 that Unicode characters in the source document also have to be trans‐
345 lated somehow.
346
347 A straightforward character set conversion from Unicode does not suf‐
348 fice, because the target character set, usually US-ASCII or ISO
349 Latin-1, do not contain common characters such as dashes and direction‐
350 al quotation marks that are widely used in XML documents. But document
351 formatters (man and Texinfo) allow such characters to be entered by a
352 markup escape: for example, \(lq for the left directional quote “. And
353 if a markup-level escape is not available, an ASCII transliteration
354 might be used: for example, using the ASCII less-than sign < for the
355 angle quotation mark ⟨.
356
357 So the Unicode character problem can be solved in two steps:
358
359 1. utf8trans(1), a program included in docbook2X, maps Unicode charac‐
360 ters to markup-level escapes or transliterations.
361
362 Since there is not necessarily a fixed, official mapping of Unicode
363 characters, utf8trans can read in user-modifiable character map‐
364 pings expressed in text files and apply them. (Unlike most charac‐
365 ter set converters.)
366
367 In charmaps/man/roff.charmap and charmaps/man/texi.charmap are
368 character maps that may be used for man-page and Texinfo conver‐
369 sion. The programs db2x_manxml(1) and db2x_texixml(1) will apply
370 these character maps, or another character map specified by the us‐
371 er, automatically.
372
373 2. The rest of the Unicode text is converted to some other character
374 set (encoding). For example, a French document with accented char‐
375 acters (such as é) might be converted to ISO Latin 1.
376
377 This step is applied after utf8trans character mapping, using the
378 iconv(1) encoding conversion tool. Both db2x_manxml(1) and
379 db2x_texixml(1) can call iconv(1) automatically when producing
380 their output.
381
383 /usr/local/share/docbook2X/xslt/texi/docbook.xsl
384 /usr/local/share/docbook2X/xslt/backend/db2x_texixml.xsl
385 /usr/local/share/docbook2X/xslt/catalog.xml
386 /usr/local/share/docbook2X/charmaps/texi.charmap.xml
387 /usr/local/share/docbook2X/charmaps/texi.charmap.xml
388
389 The above files are distributed and installed by the docbook2X package.
390
392 The docbook2man or the docbook2texi command described in this manual
393 page come from the docbook2X package. It should not be confused with
394 the command of the same name from the obsoleted docbook-utils package.
395
397 · Internally there is one long pipeline of programs which your document
398 goes through. If any segment of the pipeline fails (even trivially,
399 like from mistyped program options), the resulting errors can be dif‐
400 ficult to decipher — in this case, try running the components of doc‐
401 book2X separately.
402
404 Steve Cheng <stevecheng@users.sourceforge.net>.
405
407 db2x_xsltproc(1), db2x_texixml(1), utf8trans(1)
408
409 The docbook2X manual (in Texinfo or HTML format) fully describes how to
410 convert DocBook to man pages and Texinfo.
411
412 Up-to-date information about this program can be found at the docbook2X
413 Web site ⟨http://docbook2x.sourceforge.net/⟩ .
414
415
416
417docbook2X 0.8.8 3 March 2007 docbook2texi(1)