|
Packit |
e4b6da |
.\" -*- coding: us-ascii -*-
|
|
Packit |
e4b6da |
.if \n(.g .ds T< \\FC
|
|
Packit |
e4b6da |
.if \n(.g .ds T> \\F[\n[.fam]]
|
|
Packit |
e4b6da |
.de URL
|
|
Packit |
e4b6da |
\\$2 \(la\\$1\(ra\\$3
|
|
Packit |
e4b6da |
..
|
|
Packit |
e4b6da |
.if \n(.g .mso www.tmac
|
|
Packit |
e4b6da |
.TH db2x_texixml 1 "3 March 2007" "docbook2X 0.8.8" docbook2X
|
|
Packit |
e4b6da |
.SH NAME
|
|
Packit |
e4b6da |
db2x_texixml \- Make Texinfo files from Texi-XML
|
|
Packit |
e4b6da |
.SH SYNOPSIS
|
|
Packit |
e4b6da |
'nh
|
|
Packit |
e4b6da |
.fi
|
|
Packit |
e4b6da |
.ad l
|
|
Packit |
e4b6da |
\fBdb2x_texixml\fR \kx
|
|
Packit |
e4b6da |
.if (\nx>(\n(.l/2)) .nr x (\n(.l/5)
|
|
Packit |
e4b6da |
'in \n(.iu+\nxu
|
|
Packit |
e4b6da |
[options]\&... [\fIxml-document\fR]
|
|
Packit |
e4b6da |
'in \n(.iu-\nxu
|
|
Packit |
e4b6da |
.ad b
|
|
Packit |
e4b6da |
'hy
|
|
Packit |
e4b6da |
.SH DESCRIPTION
|
|
Packit |
e4b6da |
\fBdb2x_texixml\fR converts a Texi-XML document into one or
|
|
Packit |
e4b6da |
more Texinfo documents.
|
|
Packit |
e4b6da |
.PP
|
|
Packit |
e4b6da |
If \fIxml-document\fR is not given, then the document
|
|
Packit |
e4b6da |
to convert comes from standard input.
|
|
Packit |
e4b6da |
.PP
|
|
Packit |
e4b6da |
The filenames of the Texinfo documents are determined by markup in the
|
|
Packit |
e4b6da |
Texi-XML source. (If the filenames are not specified in the markup,
|
|
Packit |
e4b6da |
then \fBdb2x_texixml\fR attempts to deduce them from the name of the input
|
|
Packit |
e4b6da |
file. However, the Texi-XML source should specify the filename, because
|
|
Packit |
e4b6da |
it does not work when there are multiple output files or when the
|
|
Packit |
e4b6da |
Texi-XML source comes from standard input.)
|
|
Packit |
e4b6da |
.SH OPTIONS
|
|
Packit |
e4b6da |
.TP
|
|
Packit |
e4b6da |
\*(T<\fB\-\-encoding=\fR\*(T>\fIencoding\fR
|
|
Packit |
e4b6da |
Select the character encoding used for the output files.
|
|
Packit |
e4b6da |
The available encodings are those of
|
|
Packit |
e4b6da |
\fBiconv\fR(1).
|
|
Packit |
e4b6da |
The default encoding is \*(T<us\-ascii\*(T>.
|
|
Packit |
e4b6da |
|
|
Packit |
e4b6da |
The XML source may contain characters that are not representable in the encoding that
|
|
Packit |
e4b6da |
you select; in this case the program will bomb out during processing, and you should
|
|
Packit |
e4b6da |
choose another encoding.
|
|
Packit |
e4b6da |
(This is guaranteed not to happen with any Unicode encoding such as
|
|
Packit |
e4b6da |
UTF-8, but unfortunately not everyone is able to
|
|
Packit |
e4b6da |
process Unicode texts.)
|
|
Packit |
e4b6da |
|
|
Packit |
e4b6da |
If you are using GNU\(cqs version of
|
|
Packit |
e4b6da |
\fBiconv\fR(1), you can affix
|
|
Packit |
e4b6da |
\*(T<//TRANSLIT\*(T> to the end of the encoding name
|
|
Packit |
e4b6da |
to attempt transliterations of any unconvertible characters in the output.
|
|
Packit |
e4b6da |
Beware, however, that the really inconvertible characters will be turned
|
|
Packit |
e4b6da |
into another of those damned question marks. (Aren\(cqt you sick of this?)
|
|
Packit |
e4b6da |
|
|
Packit |
e4b6da |
The suffix \*(T<//TRANSLIT\*(T> applied
|
|
Packit |
e4b6da |
to a Unicode encoding \(em in particular, \*(T<utf\-8//TRANSLIT\*(T> \(em
|
|
Packit |
e4b6da |
means that the output files are to remain in Unicode,
|
|
Packit |
e4b6da |
but markup-level character translations using \fButf8trans\fR
|
|
Packit |
e4b6da |
are still to be done. So in most cases, an English-language
|
|
Packit |
e4b6da |
document, converted using
|
|
Packit |
e4b6da |
\*(T<\fB\-\-encoding=\fR\*(T>\*(T<\fButf\-8//TRANSLIT\fR\*(T>
|
|
Packit |
e4b6da |
will actually end up as a US-ASCII document,
|
|
Packit |
e4b6da |
but any untranslatable characters
|
|
Packit |
e4b6da |
will remain as UTF-8 without any warning whatsoever.
|
|
Packit |
e4b6da |
(Note: strictly speaking this is not \(lqtransliteration\(rq.)
|
|
Packit |
e4b6da |
This method of conversion is a compromise over strict
|
|
Packit |
e4b6da |
\*(T<\fB\-\-encoding=\fR\*(T>\*(T<\fBus\-ascii\fR\*(T>
|
|
Packit |
e4b6da |
processing, which aborts if any untranslatable characters are
|
|
Packit |
e4b6da |
encountered.
|
|
Packit |
e4b6da |
|
|
Packit |
e4b6da |
Note that man pages and Texinfo documents
|
|
Packit |
e4b6da |
in non-ASCII encodings (including UTF-8)
|
|
Packit |
e4b6da |
may not be portable to older (non-internationalized) systems,
|
|
Packit |
e4b6da |
which is why the default value for this option is
|
|
Packit |
e4b6da |
\*(T<us\-ascii\*(T>.
|
|
Packit |
e4b6da |
|
|
Packit |
e4b6da |
To suppress any automatic character mapping or encoding conversion
|
|
Packit |
e4b6da |
whatsoever, pass the option
|
|
Packit |
e4b6da |
\*(T<\fB\-\-encoding=\fR\*(T>\*(T<\fButf\-8\fR\*(T>.
|
|
Packit |
e4b6da |
.TP
|
|
Packit |
e4b6da |
\*(T<\fB\-\-list\-files\fR\*(T>
|
|
Packit |
e4b6da |
Write a list of all the output files to standard output,
|
|
Packit |
e4b6da |
in addition to normal processing.
|
|
Packit |
e4b6da |
.TP
|
|
Packit |
e4b6da |
\*(T<\fB\-\-output\-dir=\fR\*(T>\fIdir\fR
|
|
Packit |
e4b6da |
Specify the directory where the output files are placed.
|
|
Packit |
e4b6da |
The default is the current working directory.
|
|
Packit |
e4b6da |
|
|
Packit |
e4b6da |
This option is ignored if the output is to be written
|
|
Packit |
e4b6da |
to standard output (triggered by the
|
|
Packit |
e4b6da |
option \*(T<\fB\-\-to\-stdout\fR\*(T>).
|
|
Packit |
e4b6da |
.TP
|
|
Packit |
e4b6da |
\*(T<\fB\-\-to\-stdout\fR\*(T>
|
|
Packit |
e4b6da |
Write the output to standard output instead of to individual files.
|
|
Packit |
e4b6da |
|
|
Packit |
e4b6da |
If this option is used even when there are supposed to be multiple
|
|
Packit |
e4b6da |
output documents, then everything is concatenated to standard output.
|
|
Packit |
e4b6da |
But beware that most other programs will not accept this concatenated
|
|
Packit |
e4b6da |
output.
|
|
Packit |
e4b6da |
|
|
Packit |
e4b6da |
This option is incompatible with \*(T<\fB\-\-list\-files\fR\*(T>,
|
|
Packit |
e4b6da |
obviously.
|
|
Packit |
e4b6da |
.TP
|
|
Packit |
e4b6da |
\*(T<\fB\-\-info\fR\*(T>
|
|
Packit |
e4b6da |
Pipe the Texinfo output to
|
|
Packit |
e4b6da |
\fBmakeinfo\fR(1),
|
|
Packit |
e4b6da |
creating Info files directly instead of
|
|
Packit |
e4b6da |
Texinfo files.
|
|
Packit |
e4b6da |
.TP
|
|
Packit |
e4b6da |
\*(T<\fB\-\-plaintext\fR\*(T>
|
|
Packit |
e4b6da |
Pipe the Texinfo output to \fBmakeinfo
|
|
Packit |
e4b6da |
\*(T<\fB\-\-no\-headers\fR\*(T>\fR, thereby creating
|
|
Packit |
e4b6da |
plain text files.
|
|
Packit |
e4b6da |
.TP
|
|
Packit |
e4b6da |
\*(T<\fB\-\-help\fR\*(T>
|
|
Packit |
e4b6da |
Show brief usage information and exit.
|
|
Packit |
e4b6da |
.TP
|
|
Packit |
e4b6da |
\*(T<\fB\-\-version\fR\*(T>
|
|
Packit |
e4b6da |
Show version and exit.
|
|
Packit |
e4b6da |
.PP
|
|
Packit |
e4b6da |
This program uses certain other programs for its operation.
|
|
Packit |
e4b6da |
If they are not in their default installed locations, then use
|
|
Packit |
e4b6da |
the following options to set their location:
|
|
Packit |
e4b6da |
.TP
|
|
Packit |
e4b6da |
\*(T<\fB\-\-utf8trans\-program=\fR\*(T>\fIpath\fR, \*(T<\fB\-\-utf8trans\-map=\fR\*(T>\fIcharmap\fR
|
|
Packit |
e4b6da |
Use the character map \fIcharmap\fR
|
|
Packit |
e4b6da |
with the \fButf8trans\fR(1) program, included with docbook2X, found
|
|
Packit |
e4b6da |
under \fIpath\fR.
|
|
Packit |
e4b6da |
.TP
|
|
Packit |
e4b6da |
\*(T<\fB\-\-iconv\-program=\fR\*(T>\fIpath\fR
|
|
Packit |
e4b6da |
The location of the
|
|
Packit |
e4b6da |
\fBiconv\fR(1) program, used for encoding
|
|
Packit |
e4b6da |
conversions.
|
|
Packit |
e4b6da |
.SH NOTES
|
|
Packit |
e4b6da |
\fBTexinfo language compatibility\fR.
|
|
Packit |
e4b6da |
The Texinfo files generated by \fBdb2x_texixml\fR sometimes require
|
|
Packit |
e4b6da |
Texinfo version 4.7 (the latest version) to work properly.
|
|
Packit |
e4b6da |
In particular:
|
|
Packit |
e4b6da |
.TP 0.2i
|
|
Packit |
e4b6da |
\(bu
|
|
Packit |
e4b6da |
\fBdb2x_texixml\fR relies on \fBmakeinfo\fR
|
|
Packit |
e4b6da |
to automatically add punctuation after a \*(T<@ref\*(T>
|
|
Packit |
e4b6da |
if it it not already there. Otherwise the hyperlink will
|
|
Packit |
e4b6da |
not work in the Info reader (although
|
|
Packit |
e4b6da |
\fBmakeinfo\fR will not emit any error).
|
|
Packit |
e4b6da |
.TP 0.2i
|
|
Packit |
e4b6da |
\(bu
|
|
Packit |
e4b6da |
The new \*(T<@comma{}\*(T> command is used for commas
|
|
Packit |
e4b6da |
(\*(T<,\*(T>) occurring inside argument lists to
|
|
Packit |
e4b6da |
Texinfo commands, to disambiguate it from the comma used
|
|
Packit |
e4b6da |
to separate different arguments. The only alternative
|
|
Packit |
e4b6da |
otherwise would be to translate \*(T<,\*(T> to
|
|
Packit |
e4b6da |
\*(T<\&.\*(T>
|
|
Packit |
e4b6da |
which is obviously undesirable (but earlier docbook2X versions
|
|
Packit |
e4b6da |
did this).
|
|
Packit |
e4b6da |
|
|
Packit |
e4b6da |
If you cannot use version 4.7 of
|
|
Packit |
e4b6da |
\fBmakeinfo\fR, you can still use a
|
|
Packit |
e4b6da |
\fBsed\fR script to perform manually the procedure
|
|
Packit |
e4b6da |
just outlined.
|
|
Packit |
e4b6da |
.PP
|
|
Packit |
e4b6da |
\fBRelation of Texi-XML with the XML output format of makeinfo\fR.
|
|
Packit |
e4b6da |
The Texi-XML format used by docbook2X is \fIdifferent\fR
|
|
Packit |
e4b6da |
and incompatible with the XML format generated by
|
|
Packit |
e4b6da |
\fBmakeinfo\fR(1)
|
|
Packit |
e4b6da |
with its \*(T<\fB\-\-xml\fR\*(T> option.
|
|
Packit |
e4b6da |
This situation arose partly because the Texi-XML format
|
|
Packit |
e4b6da |
of docbook2X was designed and implemented independently
|
|
Packit |
e4b6da |
before the appearance
|
|
Packit |
e4b6da |
of \fBmakeinfo\fR\(cqs XML format.
|
|
Packit |
e4b6da |
Also Texi-XML is very much geared towards being
|
|
Packit |
e4b6da |
\fImachine-generated from other XML formats\fR,
|
|
Packit |
e4b6da |
while there seems to be no non-trivial applications
|
|
Packit |
e4b6da |
of \fBmakeinfo\fR\(cqs XML format.
|
|
Packit |
e4b6da |
So there is no reason at this point for docbook2X
|
|
Packit |
e4b6da |
to adopt \fBmakeinfo\fR\(cqs XML format
|
|
Packit |
e4b6da |
in lieu of Texi-XML.
|
|
Packit |
e4b6da |
.SH BUGS
|
|
Packit |
e4b6da |
.TP 0.2i
|
|
Packit |
e4b6da |
\(bu
|
|
Packit |
e4b6da |
Text wrapping in menus is utterly broken for non-ASCII text.
|
|
Packit |
e4b6da |
It is probably also broken everywhere else in the output, but
|
|
Packit |
e4b6da |
that would be \fBmakeinfo\fR\(cqs fault.
|
|
Packit |
e4b6da |
.TP 0.2i
|
|
Packit |
e4b6da |
\(bu
|
|
Packit |
e4b6da |
\*(T<\fB\-\-list\-files\fR\*(T> might not work correctly
|
|
Packit |
e4b6da |
with \*(T<\fB\-\-info\fR\*(T>. Specifically, when the output
|
|
Packit |
e4b6da |
Info file get too big, \fBmakeinfo\fR will decide
|
|
Packit |
e4b6da |
to split it into parts named
|
|
Packit |
e4b6da |
\*(T<\fIabc.info\-1\fR\*(T>,
|
|
Packit |
e4b6da |
\*(T<\fIabc.info\-2\fR\*(T>,
|
|
Packit |
e4b6da |
\*(T<\fIabc.info\-3\fR\*(T>, etc.
|
|
Packit |
e4b6da |
\fBdb2x_texixml\fR does not know exactly how many of these files
|
|
Packit |
e4b6da |
there are, though you can just do an \fBls\fR
|
|
Packit |
e4b6da |
to find out.
|
|
Packit |
e4b6da |
.SH AUTHOR
|
|
Packit |
e4b6da |
Steve Cheng <\*(T<stevecheng@users.sourceforge.net\*(T>>.
|
|
Packit |
e4b6da |
.SH "SEE ALSO"
|
|
Packit |
e4b6da |
The docbook2X manual (in Texinfo or HTML format) fully describes
|
|
Packit |
e4b6da |
how to convert DocBook to man pages and Texinfo.
|
|
Packit |
e4b6da |
.PP
|
|
Packit |
e4b6da |
Up-to-date information about this program
|
|
Packit |
e4b6da |
can be found
|
|
Packit |
e4b6da |
at the
|
|
Packit |
e4b6da |
.URL http://docbook2x.sourceforge.net/ "docbook2X Web site"
|
|
Packit |
e4b6da |
\&.
|
|
Packit |
e4b6da |
.PP
|
|
Packit |
e4b6da |
The input to \fBdb2x_texixml\fR is defined by the XML DTD
|
|
Packit |
e4b6da |
present at \*(T<\fIdtd/Texi\-XML\fR\*(T> in the docbook2X
|
|
Packit |
e4b6da |
distribution.
|