db2x_texixml(1)

1db2x_texixml(1)                    docbook2X                   db2x_texixml(1)
2
3
4

NAME

6       db2x_texixml - Make Texinfo files from Texi-XML
7

SYNOPSIS

9       db2x_texixml [options]... [xml-document]
10

DESCRIPTION

12       db2x_texixml converts a Texi-XML document into one or more Texinfo doc‐
13       uments.
14
15       If xml-document is not given, then the document to convert  comes  from
16       standard input.
17
18       The  filenames of the Texinfo documents are determined by markup in the
19       Texi-XML source. (If the filenames are not  specified  in  the  markup,
20       then  db2x_texixml  attempts  to deduce them from the name of the input
21       file. However, the Texi-XML source should specify the filename, because
22       it does not work when there are multiple output files or when the Texi-
23       XML source comes from standard input.)
24

OPTIONS

26       --encoding=encoding
27              Select the character encoding used for the  output  files.   The
28              available encodings are those of iconv(1).  The default encoding
29              is us-ascii.
30
31              The XML source may contain characters that are not representable
32              in  the  encoding that you select; in this case the program will
33              bomb out during processing, and you should choose another encod‐
34              ing.   (This is guaranteed not to happen with any Unicode encod‐
35              ing such as UTF-8, but unfortunately not  everyone  is  able  to
36              process Unicode texts.)
37
38              If  you  are  using  GNU’s  version  of  iconv(1), you can affix
39              //TRANSLIT to the end of the encoding name to attempt  translit‐
40              erations of any unconvertible characters in the output.  Beware,
41              however, that the really inconvertible characters will be turned
42              into another of those damned question marks. (Aren’t you sick of
43              this?)
44
45              The suffix //TRANSLIT applied to a Unicode encoding — in partic‐
46              ular,  utf-8//TRANSLIT  — means that the output files are to re‐
47              main in Unicode, but markup-level character  translations  using
48              utf8trans  are  still  to be done. So in most cases, an English-
49              language document,  converted  using  --encoding=utf-8//TRANSLIT
50              will actually end up as a US-ASCII document, but any untranslat‐
51              able characters will remain as UTF-8 without any warning whatso‐
52              ever.   (Note: strictly speaking this is not “transliteration”.)
53              This method of conversion is a compromise over  strict  --encod‐
54              ing=us-ascii  processing,  which  aborts  if  any untranslatable
55              characters are encountered.
56
57              Note that man pages and Texinfo documents in non-ASCII encodings
58              (including UTF-8) may not be portable to older (non-internation‐
59              alized) systems, which is why the default value for this  option
60              is us-ascii.
61
62              To  suppress any automatic character mapping or encoding conver‐
63              sion whatsoever, pass the option --encoding=utf-8.
64
65       --list-files
66              Write a list of all the output files to standard output, in  ad‐
67              dition to normal processing.
68
69       --output-dir=dir
70              Specify  the  directory  where the output files are placed.  The
71              default is the current working directory.
72
73              This option is ignored if the output is to be written  to  stan‐
74              dard output (triggered by the option --to-stdout).
75
76       --to-stdout
77              Write  the  output  to  standard output instead of to individual
78              files.
79
80              If this option is used even when there are supposed to be multi‐
81              ple  output  documents, then everything is concatenated to stan‐
82              dard output.  But beware that most other programs will  not  ac‐
83              cept this concatenated output.
84
85              This option is incompatible with --list-files, obviously.
86
87       --info Pipe  the Texinfo output to makeinfo(1), creating Info files di‐
88              rectly instead of Texinfo files.
89
90       --plaintext
91              Pipe the Texinfo output to makeinfo --no-headers, thereby creat‐
92              ing plain text files.
93
94       --help Show brief usage information and exit.
95
96       --version
97              Show version and exit.
98
99       This  program  uses  certain other programs for its operation.  If they
100       are not in their default installed locations, then  use  the  following
101       options to set their location:
102
103       --utf8trans-program=path, --utf8trans-map=charmap
104              Use the character map charmap with the utf8trans(1) program, in‐
105              cluded with docbook2X, found under path.
106
107       --iconv-program=path
108              The location of the iconv(1) program, used for encoding  conver‐
109              sions.
110

NOTES

112       Texinfo  language  compatibility.    The  Texinfo  files  generated  by
113       db2x_texixml sometimes require Texinfo version 4.7 (the latest version)
114       to work properly.  In particular:
115
116       · db2x_texixml  relies on makeinfo to automatically add punctuation af‐
117         ter a @ref if it it not already there. Otherwise the  hyperlink  will
118         not  work in the Info reader (although makeinfo will not emit any er‐
119         ror).
120
121       · The new @comma{} command is used for commas (,) occurring inside  ar‐
122         gument  lists  to Texinfo commands, to disambiguate it from the comma
123         used to separate different arguments. The only alternative  otherwise
124         would  be  to  translate  , to .  which is obviously undesirable (but
125         earlier docbook2X versions did this).
126
127         If you cannot use version 4.7 of makeinfo, you can still  use  a  sed
128         script to perform manually the procedure just outlined.
129
130       Relation  of  Texi-XML  with  the  XML output format of makeinfo.   The
131       Texi-XML format used by docbook2X is different  and  incompatible  with
132       the  XML  format  generated by makeinfo(1) with its --xml option.  This
133       situation arose partly because the Texi-XML format of docbook2X was de‐
134       signed  and  implemented independently before the appearance of makein‐
135       fo’s XML format.  Also Texi-XML is very much geared towards  being  ma‐
136       chine-generated from other XML formats, while there seems to be no non-
137       trivial applications of makeinfo’s XML format.  So there is  no  reason
138       at  this  point for docbook2X to adopt makeinfo’s XML format in lieu of
139       Texi-XML.
140

BUGS

142       · Text wrapping in menus is utterly broken for non-ASCII text.   It  is
143         probably also broken everywhere else in the output, but that would be
144         makeinfo’s fault.
145
146       · --list-files might not work correctly with --info. Specifically, when
147         the  output  Info  file get too big, makeinfo will decide to split it
148         into parts named abc.info-1, abc.info-2, abc.info-3, etc.   db2x_tex‐
149         ixml  does not know exactly how many of these files there are, though
150         you can just do an ls to find out.
151

AUTHOR

153       Steve Cheng <stevecheng@users.sourceforge.net>.
154