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 Texi-
131       XML format used by docbook2X is different and incompatible with the XML
132       format  generated by makeinfo(1) with its --xml option.  This situation
133       arose partly because the Texi-XML format of docbook2X was designed  and
134       implemented  independently before the appearance of makeinfo’s XML for‐
135       mat.  Also Texi-XML is very much geared towards being machine-generated
136       from other XML formats, while there seems to be no non-trivial applica‐
137       tions of makeinfo’s XML format.  So there is no reason  at  this  point
138       for docbook2X to adopt makeinfo’s XML format in lieu of Texi-XML.
139

BUGS

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

AUTHOR

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