Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
db2x_texixml(1)			   docbook2X		       db2x_texixml(1)

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 doc-
       uments.

       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	encod-
	      ing.   (This is guaranteed not to	happen with any	Unicode	encod-
	      ing 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  translit-
	      erations 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  par-
	      ticular,	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 untranslat-
	      able characters will remain as UTF-8 without any warning whatso-
	      ever.   (Note: strictly speaking this is not "transliteration".)
	      This method of conversion	is a compromise	over  strict  --encod-
	      ing=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-internation-
	      alized) systems, which is	why the	default	value for this	option
	      is us-ascii.

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

       --list-files
	      Write a list of all the output files to standard output, in  ad-
	      dition 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	 stan-
	      dard 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	multi-
	      ple  output  documents, then everything is concatenated to stan-
	      dard output.  But	beware that most other programs	will  not  ac-
	      cept this	concatenated output.

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

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

       --plaintext
	      Pipe the Texinfo output to makeinfo --no-headers,	thereby	creat-
	      ing 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, in-
	      cluded with docbook2X, found under path.

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

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:

       o db2x_texixml  relies on makeinfo to automatically add punctuation af-
	 ter a @ref if it it not already there.	Otherwise the  hyperlink  will
	 not  work in the Info reader (although	makeinfo will not emit any er-
	 ror).

       o The new @comma{} command is used for commas (,) occurring inside  ar-
	 gument	 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 for-
       mat.  Also Texi-XML is very much	geared towards being machine-generated
       from other XML formats, while there seems to be no non-trivial applica-
       tions 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
       o 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.

       o --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_tex-
	 ixml 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.

docbook2X 0.8.8			 3 March 2007		       db2x_texixml(1)

NAME | SYNOPSIS | DESCRIPTION | OPTIONS | NOTES | BUGS | AUTHOR | SEE ALSO

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=db2x_texixml&sektion=1&manpath=FreeBSD+12.1-RELEASE+and+Ports>

home | help