1docbook2texi(1)                    docbook2X                   docbook2texi(1)
2
3
4

NAME

6       docbook2texi - Convert DocBook to Texinfo
7

SYNOPSIS

9       docbook2texi [options] xml-document
10

DESCRIPTION

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

OPTIONS

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

EXAMPLES

300       $ docbook2texi tdg.xml
301       $ docbook2texi --encoding=utf-8//TRANSLIT tdg.xml
302       $ docbook2texi --string-param semantic-decorations=0 tdg.xml
303       .fi
304

CONVERSION PROCESS

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

FILES

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

NOTES

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

LIMITATIONS

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

AUTHOR

404       Steve Cheng <stevecheng@users.sourceforge.net>.
405

SEE ALSO

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)
Impressum