Provided by: docbook2x_0.8.8-17_amd64 bug

NAME

       db2x_texixml - Make Texinfo files from Texi-XML

SYNOPSIS

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

DESCRIPTION

       db2x_texixml converts a Texi-XML document into one or more Texinfo documents.

       If xml-document is not given, then the document to convert comes from standard input.

       The  filenames  of  the Texinfo documents are determined by markup in the Texi-XML source.
       (If the filenames are not specified in the markup, then db2x_texixml  attempts  to  deduce
       them  from  the  name  of  the input file. However, the Texi-XML source should specify the
       filename, because it does not work when there are multiple output files or when the  Texi-
       XML source comes from standard input.)

OPTIONS

       --encoding=encoding
              Select  the  character encoding used for the output files.  The available encodings
              are those of iconv(1).  The default encoding is us-ascii.

              The XML source may contain characters that are not representable  in  the  encoding
              that  you select; in this case the program will bomb out during processing, and you
              should choose another encoding.  (This is guaranteed not to happen with any Unicode
              encoding  such  as UTF-8, but unfortunately not everyone is able to process Unicode
              texts.)

              If you are using GNU’s version of iconv(1), you can affix //TRANSLIT to the end  of
              the  encoding  name  to attempt transliterations of any unconvertible characters in
              the output.  Beware, however, that the  really  inconvertible  characters  will  be
              turned into another of those damned question marks. (Aren’t you sick of this?)

              The   suffix   //TRANSLIT   applied   to   a  Unicode  encoding  —  in  particular,
              utf-8//TRANSLIT — means that the output files are to remain in Unicode, but markup-
              level  character  translations  using  utf8trans  are  still to be done. So in most
              cases, an English-language  document,  converted  using  --encoding=utf-8//TRANSLIT
              will actually end up as a US-ASCII document, but any untranslatable characters will
              remain as UTF-8 without any warning whatsoever.  (Note: strictly speaking  this  is
              not  “transliteration”.)   This  method  of  conversion is a compromise over strict
              --encoding=us-ascii processing, which aborts if any untranslatable  characters  are
              encountered.

              Note  that man pages and Texinfo documents in non-ASCII encodings (including UTF-8)
              may not be portable to older (non-internationalized)  systems,  which  is  why  the
              default value for this option is us-ascii.

              To suppress any automatic character mapping or encoding conversion whatsoever, pass
              the option --encoding=utf-8.

       --list-files
              Write a list of all the output files to standard  output,  in  addition  to  normal
              processing.

       --output-dir=dir
              Specify  the  directory  where  the  output  files  are placed.  The default is the
              current working directory.

              This option is ignored if the output is to be written to standard output (triggered
              by the option --to-stdout).

       --to-stdout
              Write the output to standard output instead of to individual files.

              If  this  option  is  used  even  when  there  are  supposed  to be multiple output
              documents, then everything is concatenated to standard  output.   But  beware  that
              most other programs will not accept this concatenated output.

              This option is incompatible with --list-files, obviously.

       --info Pipe  the  Texinfo  output  to makeinfo(1), creating Info files directly instead of
              Texinfo files.

       --plaintext
              Pipe the Texinfo output to  makeinfo  --no-headers,  thereby  creating  plain  text
              files.

       --help Show brief usage information and exit.

       --version
              Show version and exit.

       This  program  uses  certain  other  programs for its operation.  If they are not in their
       default installed locations, then use the following options to set their location:

       --utf8trans-program=path, --utf8trans-map=charmap
              Use the  character  map  charmap  with  the  utf8trans(1)  program,  included  with
              docbook2X, found under path.

       --iconv-program=path
              The location of the iconv(1) program, used for encoding conversions.

NOTES

       Texinfo  language  compatibility.   The  Texinfo files generated by db2x_texixml sometimes
       require Texinfo version 4.7 (the latest version) to work properly.  In particular:

       • db2x_texixml relies on makeinfo to automatically add punctuation after a @ref if  it  it
         not  already  there.  Otherwise the hyperlink will not work in the Info reader (although
         makeinfo will not emit any error).

       • The new @comma{} command is used for commas  (,)  occurring  inside  argument  lists  to
         Texinfo  commands,  to  disambiguate  it  from  the  comma  used  to  separate different
         arguments. The only alternative otherwise would  be  to  translate  ,  to  .   which  is
         obviously undesirable (but earlier docbook2X versions did this).

         If  you  cannot  use  version 4.7 of makeinfo, you can still use a sed script to perform
         manually the procedure just outlined.

       Relation of Texi-XML with the XML output format of makeinfo.  The Texi-XML format used  by
       docbook2X  is different and incompatible with the XML format generated by makeinfo(1) with
       its --xml option.  This situation arose partly because the Texi-XML  format  of  docbook2X
       was designed and implemented independently before the appearance of makeinfo’s XML format.
       Also Texi-XML is very much geared towards being machine-generated from other XML  formats,
       while there seems to be no non-trivial applications of makeinfo’s XML format.  So there is
       no reason at this point for docbook2X to adopt makeinfo’s XML format in lieu of Texi-XML.

BUGS

       • Text wrapping in menus is utterly broken for non-ASCII text.  It is probably also broken
         everywhere else in the output, but that would be makeinfo’s fault.

       • --list-files  might  not  work correctly with --info. Specifically, when the output Info
         file get too big, makeinfo  will  decide  to  split  it  into  parts  named  abc.info-1,
         abc.info-2, abc.info-3, etc.  db2x_texixml does not know exactly how many of these files
         there are, though you can just do an ls to find out.

AUTHOR

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

SEE ALSO

       The docbook2X manual (in Texinfo or HTML format) fully describes how to convert DocBook to
       man pages and Texinfo.

       Up-to-date information about this program can be found at the docbook2X Web site ⟨http://
       docbook2x.sourceforge.net/⟩ .

       The input to db2x_texixml is defined by  the  XML  DTD  present  at  dtd/Texi-XML  in  the
       docbook2X distribution.