.\" -*- 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 db2x_xsltproc 1 "3 March 2007" "docbook2X 0.8.8" docbook2X
.SH NAME
db2x_xsltproc \- XSLT processor invocation wrapper
.SH SYNOPSIS
'nh
.fi
.ad l
\fBdb2x_xsltproc\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
\fBdb2x_xsltproc\fR invokes the XSLT 1.0 processor for docbook2X.
.PP
This command applies the XSLT stylesheet 
(usually given by the \*(T<\fB\-\-stylesheet\fR\*(T> option)
to the XML document in the file \fIxml-document\fR.
The result is written to standard output (unless changed with 
\*(T<\fB\-\-output\fR\*(T>). 
.PP
To read the source XML document from standard input,
specify \*(T<\-\*(T> as the input document.
.SH OPTIONS
.TP 
\*(T<\fB\-\-version\fR\*(T>
Display the docbook2X version.
.SS "TRANSFORMATION OUTPUT OPTIONS"
.TP 
\*(T<\fB\-\-output \fR\*(T>\fIfile\fR, \*(T<\fB\-o \fR\*(T>\fIfile\fR
Write output to the given file (or URI), instead of standard output.
.SS "SOURCE DOCUMENT OPTIONS"
.TP 
\*(T<\fB\-\-xinclude\fR\*(T>, \*(T<\fB\-I\fR\*(T>
Process XInclude directives in the source document.
.TP 
\*(T<\fB\-\-sgml\fR\*(T>, \*(T<\fB\-S\fR\*(T>
Indicate that the input document is SGML instead of XML.
You need this set this option if \fIxml-document\fR
is actually a SGML file.

SGML parsing is implemented by conversion to XML via 
\fBsgml2xml\fR(1) from the
SP package (or 
\fBosx\fR(1) from the OpenSP package). All tag names in the
SGML file will be normalized to lowercase (i.e. the \*(T<\fB\-xlower\fR\*(T>
option of 
\fBsgml2xml\fR(1) is used). ID attributes are available
for the stylesheet (i.e. option \*(T<\fB\-xid\fR\*(T>). In addition,
any ISO SDATA entities used in the SGML document are automatically converted
to their XML Unicode equivalents. (This is done by a
\fBsed\fR filter.)

The encoding of the SGML document, if it is not
\*(T<us\-ascii\*(T>, must be specified with the standard
SP environment variables: \*(T<\fBSP_CHARSET_FIXED=1
SP_ENCODING=\fIencoding\fB\fR\*(T>.
(Note that XML files specify their encoding with the XML declaration
\*(T<\fB<?xml version="1.0" encoding="\fIencoding"\fB ?>\fR\*(T>
at the top of the file.)

The above conversion options cannot be changed. If you desire different
conversion options, you should invoke 
\fBsgml2xml\fR(1) manually, and then pass
the results of that conversion to this program.
.SS "RETRIEVAL OPTIONS"
.TP 
\*(T<\fB\-\-catalogs \fR\*(T>\fIcatalog-files\fR, \*(T<\fB\-C \fR\*(T>\fIcatalog-files\fR
Specify additional XML catalogs to use for resolving Formal
Public Identifiers or URIs. SGML catalogs are not supported.

These catalogs are \fInot\fR used for parsing an SGML
document under the \*(T<\fB\-\-sgml\fR\*(T> option. Use
the environment variable \fBSGML_CATALOG_FILES\fR instead 
to specify the catalogs for parsing the SGML document.
.TP 
\*(T<\fB\-\-network\fR\*(T>, \*(T<\fB\-N\fR\*(T>
\fBdb2x_xsltproc\fR will normally refuse to load
external resources from the network, for security reasons. 
If you do want to load from the network, set this option.

Usually you want to have installed locally the relevent DTDs and other
files, and set up catalogs for them, rather than load them automatically
from the network.
.SS "STYLESHEET OPTIONS"
.TP 
\*(T<\fB\-\-stylesheet \fR\*(T>\fIfile\fR, \*(T<\fB\-s \fR\*(T>\fIfile\fR
Specify the filename (or URI) of the stylesheet to use. 
The special values \*(T<man\*(T> and \*(T<texi\*(T> 
are accepted as abbreviations, to specify that
\fIxml-document\fR is in DocBook and
should be converted to man pages or Texinfo (respectively).
.TP 
\*(T<\fB\-\-param \fR\*(T>\fIname\fR\*(T<\fB=\fR\*(T>\fIexpr\fR, \*(T<\fB\-p \fR\*(T>\fIname\fR\*(T<\fB=\fR\*(T>\fIexpr\fR
Add or modify a parameter to the stylesheet.
\fIname\fR is a XSLT parameter name, and
\fIexpr\fR is an XPath expression that evaluates to
the desired value for the parameter. (This means that strings must be
quoted, \fIin addition\fR to the usual quoting of shell
arguments; use \*(T<\fB\-\-string\-param\fR\*(T> to avoid this.)
.TP 
\*(T<\fB\-\-string\-param \fR\*(T>\fIname\fR\*(T<\fB=\fR\*(T>\fIstring\fR, \*(T<\fB\-g \fR\*(T>\fIname\fR\*(T<\fB=\fR\*(T>\fIstring\fR
Add or modify a string-valued parameter to the stylesheet.

The string must be encoded in UTF-8 (regardless of the locale 
character encoding).
.SS "DEBUGGING AND PROFILING"
.TP 
\*(T<\fB\-\-debug\fR\*(T>, \*(T<\fB\-d\fR\*(T>
Display, to standard error, logs of what is happening during the 
XSL transformation.
.TP 
\*(T<\fB\-\-nesting\-limit \fR\*(T>\fIn\fR, \*(T<\fB\-D \fR\*(T>\fIn\fR
Change the maximum number of nested calls to XSL templates, used to
detect potential infinite loops. 
If not specified, the limit is 500 (libxslt\(cqs default).
.TP 
\*(T<\fB\-\-profile\fR\*(T>, \*(T<\fB\-P\fR\*(T>
Display profile information: the total number of calls to each template
in the stylesheet and the time taken for each. This information is
output to standard error.
.TP 
\*(T<\fB\-\-xslt\-processor \fR\*(T>\fIprocessor\fR, \*(T<\fB\-X \fR\*(T>\fIprocessor\fR
Select the underlying XSLT processor used. The possible choices for
\fIprocessor\fR are: \*(T<libxslt\*(T>, \*(T<saxon\*(T>, \*(T<xalan\-j\*(T>.

The default processor is whatever was set when docbook2X was built.
libxslt is recommended (because it is lean and fast),
but SAXON is much more robust and would be more helpful when
debugging stylesheets.

All the processors have XML catalogs support enabled.
(docbook2X requires it.)
But note that not all the options above work with processors
other than the libxslt one.
.SH ENVIRONMENT
.TP 
\fBXML_CATALOG_FILES\fR
Specify XML Catalogs.
If not specified, the standard catalog
(\*(T<\fI/etc/xml/catalog\fR\*(T>) is loaded, if available.
.TP 
\fBDB2X_XSLT_PROCESSOR\fR
Specify the XSLT processor to use.
The effect is the same as the \*(T<\fB\-\-xslt\-processor\fR\*(T>
option. The primary use of this variable is to allow you to quickly 
test different XSLT processors without having to add 
\*(T<\fB\-\-xslt\-processor\fR\*(T> to every script or make file in 
your documentation build system.
.SH "CONFORMING TO"
.URL http://www.w3.org/TR/xslt "XML Stylesheet Language \(en Transformations (XSLT), version 1.0"
, a W3C Recommendation.
.SH NOTES
In its earlier versions (< 0.8.4),
docbook2X required XSLT extensions to run, and
\fBdb2x_xsltproc\fR was a special libxslt-based processor that had these
extensions compiled-in. When the requirement for XSLT extensions
was dropped, \fBdb2x_xsltproc\fR became a Perl script which translates
the options to \fBdb2x_xsltproc\fR to conform to the format accepted by
the stock 
\fBxsltproc\fR(1) which comes with libxslt.
.PP
The prime reason for the existence of this script
is backward compatibility with any scripts
or make files that invoke docbook2X. However,
it also became easy to add in support for invoking
other XSLT processors with a unified command-line interface.
Indeed, there is nothing special in this script to docbook2X, 
or even to DocBook, and it may be used for running other sorts of
stylesheets if you desire. Certainly the author prefers using this
command, because its invocation format is sane and is easy to 
use. (e.g. no typing long class names for the Java-based processors!)
.SH AUTHOR
Steve Cheng <\*(T<stevecheng@users.sourceforge.net\*(T>>.
.SH "SEE ALSO"
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"
\&.
.PP
You may wish to consult the documentation that comes
with libxslt, SAXON, or Xalan. The W3C XSLT 1.0 specification
would be useful for writing stylesheets.