Man Linux: Main Page and Category List

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.