.\" -*- 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 docbook2man 1 "3 March 2007" "docbook2X 0.8.8" docbook2X
.SH NAME
docbook2man \- Convert DocBook to man pages
.SH SYNOPSIS
'nh
.fi
.ad l
\fBdocbook2man\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
\fBdocbook2man\fR converts the given DocBook XML document into man pages.
By default, the man pages will be output to the current directory.
.PP
Only the \*(T<refentry\*(T> content
in the DocBook document is converted.
(To convert content outside of a \*(T<refentry\*(T>,
stylesheet customization is required. See the docbook2X
package for details.)
.PP
The \fBdocbook2man\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
from \fBdb2x_xsltproc\fR(1) and \fBdb2x_manxml\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.
.TP 
\*(T<\fB\-\-solinks\fR\*(T>
Make stub pages for alternate names for an output man page.
.SS "STYLESHEET PARAMETERS"
.TP 
\*(T<uppercase\-headings\*(T>
\fBBrief\fR. Make headings uppercase?

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

Headings in man page content should be or should not be uppercased.
.TP 
\*(T<manvolnum\-cite\-numeral\-only\*(T>
\fBBrief\fR. Man page section citation should use only the number

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

When citing other man pages, the man-page section is either given as is,
or has the letters stripped from it, citing only the number of the
section (e.g. section \*(T<3x\*(T> becomes
\*(T<3\*(T>). This option specifies which style. 
.TP 
\*(T<quotes\-on\-literals\*(T>
\fBBrief\fR. Display quotes on \*(T<literal\*(T>
elements?

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

If true, render \*(T<literal\*(T> elements
with quotes around them.
.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<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<xref\-on\-link\*(T>
\fBBrief\fR. Should \*(T<link\*(T> generate a
cross-reference?

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

Man pages cannot render the hypertext links created by \*(T<link\*(T>. If this option is set, then the
stylesheet renders a cross reference to the target of the link.
(This may reduce clutter). Otherwise, only the content of the \*(T<link\*(T> is rendered and the actual link itself is
ignored.
.TP 
\*(T<header\-3\*(T>
\fBBrief\fR. Third header text

\fBDefault setting\fR. (blank)

Specifies the text of the third header of a man page,
typically the date for the man page. If empty, the \*(T<date\*(T> content for the \*(T<refentry\*(T> is used.
.TP 
\*(T<header\-4\*(T>
\fBBrief\fR. Fourth header text

\fBDefault setting\fR. (blank)

Specifies the text of the fourth header of a man page.
If empty, the \*(T<refmiscinfo\*(T> content for
the \*(T<refentry\*(T> is used.
.TP 
\*(T<header\-5\*(T>
\fBBrief\fR. Fifth header text

\fBDefault setting\fR. (blank)

Specifies the text of the fifth header of a man page.
If empty, the \(oqmanual name\(cq, that is, the title of the
\*(T<book\*(T> or \*(T<reference\*(T> container is used.
.TP 
\*(T<default\-manpage\-section\*(T>
\fBBrief\fR. Default man page section

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

The source document usually indicates the sections that each man page
should belong to (with \*(T<manvolnum\*(T> in
\*(T<refmeta\*(T>). In case the source
document does not indicate man-page sections, this option specifies the
default.
.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.
.SH EXAMPLES
.nf
\*(T<\fB$ \fRdocbook2man \-\-solinks manpages.xml
\fB$ \fRdocbook2man \-\-solinks \-\-encoding=utf\-8//TRANSLIT manpages.xml
\fB$ \fRdocbook2man \-\-string\-param header\-4="Free Recode 3.6" document.xml
\*(T>.fi
.SH "CONVERSION PROCESS"
.SS "Converting to man pages"
DocBook documents are converted to man pages in two steps:
.TP 0.4i
1.
The DocBook source is converted by a XSLT stylesheet into an 
intermediate XML format, Man-XML.

Man-XML is simpler than DocBook and closer to the man page format;
it is intended to make the stylesheets\(cq job easier.

The stylesheet for this purpose is in
\*(T<\fIxslt/man/docbook.xsl\fR\*(T>.
For portability, it should always be referred to
by the following URI:

.nf
http://docbook2x.sourceforge.net/latest/xslt/man/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/man/docbook.xsl\fR\*(T>.
.TP 0.4i
2.
Man-XML is converted to the actual man pages by \fBdb2x_manxml\fR(1).
.PP
The \fBdocbook2man\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 man \fImydoc\fR.xml \-o \fImydoc\fR.mxml
\fB$ \fRdb2x_manxml \fImydoc\fR.mxml
\*(T>.fi
.PP
Options to the conversion stylesheet are described in
the man-pages stylesheets
reference.
.PP
\fBPure XSLT conversion\fR. 
An alternative to the \fBdb2x_manxml\fR Perl script is the XSLT
stylesheet in 
\*(T<\fIxslt/backend/db2x_manxml.xsl\fR\*(T>.
This stylesheet performs a similar function
of converting Man-XML to actual man pages.
It is useful if you desire a pure XSLT
solution to man-page conversion.
Of course, the quality of the conversion using this stylesheet
will never be as good as the Perl \fBdb2x_manxml\fR,
and it runs slower. 
In particular, the pure XSLT version
currently does not support tables in man pages,
but its Perl counterpart does.
.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/man/docbook.xsl\fR\*(T>
.br
\*(T<\fI/usr/local/share/docbook2X/xslt/backend/db2x_manxml.xsl\fR\*(T>
.br
\*(T<\fI/usr/local/share/docbook2X/xslt/catalog.xml\fR\*(T>
.br
\*(T<\fI/usr/local/share/docbook2X/charmaps/roff.charmap\fR\*(T>
.br
\*(T<\fI/usr/local/share/docbook2X/charmaps/roff.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_manxml\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"
\&.