.\" -*- coding: us-ascii -*-

.if \n(.g .ds T< \\FC

.if \n(.g .ds T> \\F[\n[.fam]]

.de URL

\\$2 \(la\\$1\(ra\\$3

..

.if \n(.g .mso www.tmac

.TH docbook2texi 1 "3 March 2007" "docbook2X 0.8.8" docbook2X

.SH NAME

docbook2texi \- Convert DocBook to Texinfo

.SH SYNOPSIS

'nh

.fi

.ad l

\fBdocbook2texi\fR \kx

.if (\nx>(\n(.l/2)) .nr x (\n(.l/5)

'in \n(.iu+\nxu

[\fIoptions\fR] \fIxml-document\fR 

'in \n(.iu-\nxu

.ad b

'hy

.SH DESCRIPTION

\fBdocbook2texi\fR converts the given 

DocBook XML document into one or more Texinfo documents.

By default, these Texinfo documents will be output to the current

directory.

.PP

The \fBdocbook2texi\fR command is a wrapper script

for a two-step conversion process.

See the section \(lqCONVERSION PROCESS\(rq below

for details.

.SH OPTIONS

The available options are essentially the union of the options

for \fBdb2x_xsltproc\fR(1) and \fBdb2x_texixml\fR(1).

.PP

Some commonly-used options are listed below:

.TP 

\*(T<\fB\-\-encoding=\fR\*(T>\fIencoding\fR

Sets the character encoding of the output.

.TP 

\*(T<\fB\-\-string\-param \fR\*(T>\fIparameter\fR\*(T<\fB=\fR\*(T>\fIvalue\fR

Sets a stylesheet parameter (options that affect how the output looks).

See \(lqStylesheet parameters\(rq below for the parameters that

can be set.

.TP 

\*(T<\fB\-\-sgml\fR\*(T>

Accept an SGML source document as input instead of XML.

.SS "STYLESHEET PARAMETERS"

.TP 

\*(T<captions\-display\-as\-headings\*(T>

\fBBrief\fR. Use heading markup for minor captions?

\fBDefault setting\fR. \*(T<0\*(T> (boolean false)

If true, \*(T<title\*(T>

content in some (formal) objects are rendered with the Texinfo

\*(T<@\fIheading\fR\*(T> commands.

If false, captions are rendered as an emphasized paragraph.

.TP 

\*(T<links\-use\-pxref\*(T>

\fBBrief\fR. Translate \*(T<link\*(T> using

\*(T<@pxref\*(T>

\fBDefault setting\fR. \*(T<1\*(T> (boolean true)

If true, \*(T<link\*(T> is translated

with the hypertext followed by the cross reference in parentheses.

Otherwise, the hypertext content serves as the cross-reference name

marked up using \*(T<@ref\*(T>. Typically info displays this

contruct badly.

.TP 

\*(T<explicit\-node\-names\*(T>

\fBBrief\fR. Insist on manually constructed Texinfo node

names

\fBDefault setting\fR. \*(T<0\*(T> (boolean false)

Elements in the source document can influence the Texinfo node name

generation specifying either a \*(T<xreflabel\*(T>, or for the sectioning elements,

a \*(T<title\*(T> with \*(T<role='texinfo\-node'\*(T> in the 

\*(T<\fI*\fRinfo\*(T> container.

However, for the majority of source documents, explicit Texinfo node

names are not available, and the stylesheet tries to generate a

reasonable one instead, e.g. from the normal title of an element. 

The generated name may not be optimal. If this option is set and the

stylesheet needs to generate a name, a warning is emitted and 

\*(T<\fBgenerate\-id\fR\*(T> is always used for the name.

When the hashtable extension is not available, the stylesheet cannot

check for node name collisions, and in this case, setting this option

and using explicit node names are recommended. 

This option is not set (i.e. false) by default.

.RS 

\fBNote\fR

The absolute fallback for generating node names is using the XSLT

function \*(T<\fBgenerate\-id\fR\*(T>, and the stylesheet always

emits a warning in this case regardless of the setting of

\*(T<explicit\-node\-names\*(T>.

.RE

.TP 

\*(T<show\-comments\*(T>

\fBBrief\fR. Display \*(T<comment\*(T> elements?

\fBDefault setting\fR. \*(T<1\*(T> (boolean true)

If true, comments will be displayed, otherwise they are suppressed.

Comments here refers to the \*(T<comment\*(T> element,

which will be renamed \*(T<remark\*(T> in DocBook V4.0,

not XML comments (<-- like this -->) which are unavailable.

.TP 

\*(T<funcsynopsis\-decoration\*(T>

\fBBrief\fR. Decorate elements of a FuncSynopsis?

\fBDefault setting\fR. \*(T<1\*(T> (boolean true)

If true, elements of the FuncSynopsis will be decorated (e.g. bold or

italic). The decoration is controlled by functions that can be redefined

in a customization layer.

.TP 

\*(T<function\-parens\*(T>

\fBBrief\fR. Generate parentheses after a function?

\fBDefault setting\fR. \*(T<0\*(T> (boolean false)

If true, the formatting of

a \*(T<<function>\*(T> element will include

generated parenthesis.

.TP 

\*(T<refentry\-display\-name\*(T>

\fBBrief\fR. Output NAME header before 'RefName'(s)?

\fBDefault setting\fR. \*(T<1\*(T> (boolean true)

If true, a "NAME" section title is output before the list

of 'RefName's.

.TP 

\*(T<manvolnum\-in\-xref\*(T>

\fBBrief\fR. Output \*(T<manvolnum\*(T> as part of

\*(T<refentry\*(T> cross-reference?

\fBDefault setting\fR. \*(T<1\*(T> (boolean true)

if true, the \*(T<manvolnum\*(T> is used when cross-referencing

\*(T<refentry\*(T>s, either with \*(T<xref\*(T>

or \*(T<citerefentry\*(T>.

.TP 

\*(T<prefer\-textobjects\*(T>

\fBBrief\fR. Prefer \*(T<textobject\*(T>

over \*(T<imageobject\*(T>?

\fBDefault setting\fR. \*(T<1\*(T> (boolean true)

If true, the 

\*(T<textobject\*(T>

in a \*(T<mediaobject\*(T>

is preferred over any

\*(T<imageobject\*(T>.

(Of course, for output formats other than Texinfo, you usually

want to prefer the \*(T<imageobject\*(T>,

but Info is a text-only format.)

In addition to the values true and false, this parameter

may be set to \*(T<2\*(T> to indicate that

both the text and the images should be output.

You may want to do this because some Texinfo viewers

can read images. Note that the Texinfo \*(T<@image\*(T>

command has its own mechanism for switching between text

and image output \(em but we do not use this here.

The default is true.

.TP 

\*(T<semantic\-decorations\*(T>

\fBBrief\fR. Use Texinfo semantic inline markup?

\fBDefault setting\fR. \*(T<1\*(T> (boolean true)

If true, the semantic inline markup of DocBook is translated into

(the closest) Texinfo equivalent. This is the default.

However, because the Info format is limited to plain text,

the semantic inline markup is often distinguished by using 

explicit quotes, which may not look good. 

You can set this option to false to suppress these.

(For finer control over the inline formatting, you can

use your own stylesheet.)

.TP 

\*(T<custom\-localization\-file\*(T>

\fBBrief\fR. URI of XML document containing custom localization data

\fBDefault setting\fR. (blank)

This parameter specifies the URI of a XML document

that describes text translations (and other locale-specific information)

that is needed by the stylesheet to process the DocBook document.

The text translations pointed to by this parameter always

override the default text translations 

(from the internal parameter \*(T<localization\-file\*(T>).

If a particular translation is not present here,

the corresponding default translation 

is used as a fallback.

This parameter is primarily for changing certain

punctuation characters used in formatting the source document.

The settings for punctuation characters are often specific

to the source document, but can also be dependent on the locale.

To not use custom text translations, leave this parameter 

as the empty string.

.TP 

\*(T<custom\-l10n\-data\*(T>

\fBBrief\fR. XML document containing custom localization data

\fBDefault setting\fR. \*(T<document($custom\-localization\-file)\*(T>

This parameter specifies the XML document

that describes text translations (and other locale-specific information)

that is needed by the stylesheet to process the DocBook document.

This parameter is internal to the stylesheet.

To point to an external XML document with a URI or a file name, 

you should use the \*(T<custom\-localization\-file\*(T>

parameter instead.

However, inside a custom stylesheet 

(\fInot on the command-line\fR)

this paramter can be set to the XPath expression

\*(T<document('')\*(T>,

which will cause the custom translations 

directly embedded inside the custom stylesheet to be read.

.TP 

\*(T<author\-othername\-in\-middle\*(T>

\fBBrief\fR. Is \*(T<othername\*(T> in \*(T<author\*(T> a

middle name?

\fBDefault setting\fR. \*(T<1\*(T>

If true, the \*(T<othername\*(T> of an \*(T<author\*(T>

appears between the \*(T<firstname\*(T> and

\*(T<surname\*(T>. Otherwise, \*(T<othername\*(T>

is suppressed.

.TP 

\*(T<output\-file\*(T>

\fBBrief\fR. Name of the Info file

\fBDefault setting\fR. (blank)

This parameter specifies the name of the final Info file,

overriding the setting in the document itself and the automatic

selection in the stylesheet. If the document is a \*(T<set\*(T>, this parameter has no effect. 

.RS 

\fBImportant\fR

Do \fInot\fR include the \*(T<.info\*(T>

extension in the name.

.RE

(Note that this parameter has nothing to do with the name of

the \fITexi-XML output\fR by the XSLT processor you 

are running this stylesheet from.)

.TP 

\*(T<directory\-category\*(T>

\fBBrief\fR. The categorization of the document in the Info directory

\fBDefault setting\fR. (blank)

This is set to the category that the document

should go under in the Info directory of installed Info files.

For example, \*(T<General Commands\*(T>.

.RS 

\fBNote\fR

Categories may also be set directly in the source document.

But if this parameter is not empty, then it always overrides the 

setting in the source document.

.RE

.TP 

\*(T<directory\-description\*(T>

\fBBrief\fR. The description of the document in the Info directory

\fBDefault setting\fR. (blank)

This is a short description of the document that appears in

the Info directory of installed Info files.

For example, \*(T<An Interactive Plotting Program.\*(T>

.RS 

\fBNote\fR

Menu descriptions may also be set directly in the source document.

But if this parameter is not empty, then it always overrides the 

setting in the source document.

.RE

.TP 

\*(T<index\-category\*(T>

\fBBrief\fR. The Texinfo index to use

\fBDefault setting\fR. \*(T<cp\*(T>

The Texinfo index for \*(T<indexterm\*(T>

and \*(T<index\*(T> is specified using the

\*(T<role\*(T> attribute. If the above

elements do not have a \*(T<role\*(T>, then

the default specified by this parameter is used.

The predefined indices are:

.RS 

.TP 

\*(T<c\*(T>, \*(T<cp\*(T>

Concept index

.TP 

\*(T<f\*(T>, \*(T<fn\*(T>

Function index

.TP 

\*(T<v\*(T>, \*(T<vr\*(T>

Variable index

.TP 

\*(T<k\*(T>, \*(T<ky\*(T>

Keystroke index

.TP 

\*(T<p\*(T>, \*(T<pg\*(T>

Program index

.TP 

\*(T<d\*(T>, \*(T<tp\*(T>

Data type index

.RE

User-defined indices are not yet supported.

.TP 

\*(T<qanda\-defaultlabel\*(T>

\fBBrief\fR. Sets the default for defaultlabel on QandASet.

\fBDefault setting\fR. \*(T<\*(T>

If no defaultlabel attribute is specified on a QandASet, this

value is used. It must be one of the legal values for the defaultlabel

attribute.

.TP 

\*(T<qandaset\-generate\-toc\*(T>

\fBBrief\fR. Is a Table of Contents created for QandASets?

\fBDefault setting\fR. \*(T<\*(T>

If true, a ToC is constructed for QandASets.

.SH EXAMPLES

.nf

\*(T<\fB$ \fRdocbook2texi tdg.xml

\fB$ \fRdocbook2texi \-\-encoding=utf\-8//TRANSLIT tdg.xml

\fB$ \fRdocbook2texi \-\-string\-param semantic\-decorations=0 tdg.xml

\*(T>.fi

.SH "CONVERSION PROCESS"

.SS "Converting to Texinfo"

DocBook documents are converted to Texinfo in two steps:

.TP 0.4i

1.

The DocBook source is converted by a XSLT stylesheet into an intermediate

XML format, Texi-XML.

Texi-XML is simpler than DocBook and closer to the Texinfo format;

it is intended to make the stylesheets\(cq job easier.

The stylesheet for this purpose is in

\*(T<\fIxslt/texi/docbook.xsl\fR\*(T>.

For portability, it should always be referred to

by the following URI:

.nf

http://docbook2x.sourceforge.net/latest/xslt/texi/docbook.xsl

.fi

Run this stylesheet with \fBdb2x_xsltproc\fR(1).

\fBCustomizing\fR. 

You can also customize the output by

creating your own XSLT stylesheet \(em

changing parameters or adding new templates \(em

and importing \*(T<\fIxslt/texi/docbook.xsl\fR\*(T>.

.TP 0.4i

2.

Texi-XML is converted to the actual Texinfo files by \fBdb2x_texixml\fR(1).

.PP

The \fBdocbook2texi\fR command does both steps automatically,

but if any problems occur, you can see the errors more clearly

if you do each step separately:

.nf

\*(T<\fB$ \fRdb2x_xsltproc \-s texi \fImydoc\fR.xml \-o \fImydoc\fR.txml

\fB$ \fRdb2x_texixml \fImydoc\fR.txml

\*(T>.fi

.PP

Options to the conversion stylesheet are described

in the Texinfo stylesheets

reference.

.SS "Character set conversion"

When translating XML to legacy ASCII-based formats

with poor support for Unicode, such as man pages and Texinfo,

there is always the problem that Unicode characters in

the source document also have to be translated somehow.

.PP

A straightforward character set conversion from Unicode 

does not suffice,

because the target character set, usually US-ASCII or ISO Latin-1,

do not contain common characters such as 

dashes and directional quotation marks that are widely

used in XML documents. But document formatters (man and Texinfo)

allow such characters to be entered by a markup escape:

for example, \*(T<\e(lq\*(T> for the left directional quote 

\*(T<\(lq\*(T>.

And if a markup-level escape is not available,

an ASCII transliteration might be used: for example,

using the ASCII less-than sign \*(T<<\*(T> for 

the angle quotation mark \*(T<\(la\*(T>.

.PP

So the Unicode character problem can be solved in two steps:

.TP 0.4i

1.

\fButf8trans\fR(1), a program included in docbook2X, maps

Unicode characters to markup-level escapes or transliterations.

Since there is not necessarily a fixed, official mapping of Unicode characters,

\fButf8trans\fR can read in user-modifiable character mappings 

expressed in text files and apply them. (Unlike most character

set converters.)

In \*(T<\fIcharmaps/man/roff.charmap\fR\*(T>

and \*(T<\fIcharmaps/man/texi.charmap\fR\*(T>

are character maps that may be used for man-page and Texinfo conversion.

The programs \fBdb2x_manxml\fR(1) and \fBdb2x_texixml\fR(1) will apply

these character maps, or another character map specified by the user,

automatically.

.TP 0.4i

2.

The rest of the Unicode text is converted to some other character set 

(encoding).

For example, a French document with accented characters 

(such as \*(T<\('e\*(T>) might be converted to ISO Latin 1.

This step is applied after \fButf8trans\fR character mapping,

using the 

\fBiconv\fR(1) encoding conversion tool.

Both \fBdb2x_manxml\fR(1) and \fBdb2x_texixml\fR(1) can call

\fBiconv\fR(1) automatically when producing their output.

.SH FILES

\*(T<\fI/usr/local/share/docbook2X/xslt/texi/docbook.xsl\fR\*(T>

.br

\*(T<\fI/usr/local/share/docbook2X/xslt/backend/db2x_texixml.xsl\fR\*(T>

.br

\*(T<\fI/usr/local/share/docbook2X/xslt/catalog.xml\fR\*(T>

.br

\*(T<\fI/usr/local/share/docbook2X/charmaps/texi.charmap.xml\fR\*(T>

.br

\*(T<\fI/usr/local/share/docbook2X/charmaps/texi.charmap.xml\fR\*(T>

.PP

The above files are distributed and installed by the docbook2X package.

.SH NOTES

The \fBdocbook2man\fR or the \fBdocbook2texi\fR 

command described in this manual page

come from the docbook2X package.

It should not be confused with the command of the same

name from the obsoleted docbook-utils package.

.SH LIMITATIONS

.TP 0.2i

\(bu

Internally there is one long pipeline of programs which your 

document goes through. If any segment of the pipeline fails

(even trivially, like from mistyped program options), 

the resulting errors can be difficult to decipher \(em

in this case, try running the components of docbook2X

separately.

.SH AUTHOR

Steve Cheng <\*(T<stevecheng@users.sourceforge.net\*(T>>.

.SH "SEE ALSO"

\fBdb2x_xsltproc\fR(1), \fBdb2x_texixml\fR(1), \fButf8trans\fR(1)

.PP

The docbook2X manual (in Texinfo or HTML format) fully describes

how to convert DocBook to man pages and Texinfo.

.PP

Up-to-date information about this program

can be found 

at the 

.URL http://docbook2x.sourceforge.net/ "docbook2X Web site"

\&.