<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta name="generator" content=
"HTML Tidy for Linux/x86 (vers 1 September 2005), see www.w3.org" />
<meta http-equiv="Content-Type" content=
"text/html; charset=us-ascii" />
<title>docbook2X: db2x_xsltproc</title>
<link rel="stylesheet" href="docbook2X.css" type="text/css" />
<link rev="made" href="mailto:stevecheng@users.sourceforge.net" />
<meta name="generator" content="DocBook XSL Stylesheets V1.68.1" />
<link rel="start" href="docbook2X.html" title=
"docbook2X: Documentation Table of Contents" />
<link rel="up" href="xsltproc.html" title=
"docbook2X: The XSLT stylesheets" />
<link rel="prev" href="xsltproc.html" title=
"docbook2X: The XSLT stylesheets" />
<link rel="next" href="sgml2xml-isoent.html" title=
"docbook2X: sgml2xml-isoent" />
</head>
<body>
<div class="navheader">
<table width="100%" summary="Navigation header">
<tr>
<th colspan="3" align="center"><span><strong class=
"command">db2x_xsltproc</strong></span></th>
</tr>
<tr>
<td width="20%" align="left"><a accesskey="p" href=
"xsltproc.html"><< Previous</a> </td>
<th width="60%" align="center">The XSLT stylesheets</th>
<td width="20%" align="right"> <a accesskey="n" href=
"sgml2xml-isoent.html">Next >></a></td>
</tr>
</table>
<hr /></div>
<div class="refentry" lang="en" xml:lang="en"><a id="db2x_xsltproc"
name="db2x_xsltproc"></a>
<div class="titlepage"></div>
<a id="id2535843" class="indexterm" name="id2535843"></a><a id=
"id2535849" class="indexterm" name="id2535849"></a><a id=
"id2535856" class="indexterm" name="id2535856"></a>
<div class="refnamediv">
<h2>Name</h2>
<p><span><strong class="command">db2x_xsltproc</strong></span>
— XSLT processor invocation wrapper</p>
</div>
<div class="refsynopsisdiv">
<h2>Synopsis</h2>
<div class="cmdsynopsis">
<p><code class="command">db2x_xsltproc</code> [<em class=
"replaceable"><code>options</code></em>] <em class=
"replaceable"><code>xml-document</code></em></p>
</div>
</div>
<div class="refsect1" lang="en" xml:lang="en"><a id="id2535929"
name="id2535929"></a>
<h2>Description</h2>
<p><span><strong class="command">db2x_xsltproc</strong></span>
invokes the XSLT 1.0 processor for docbook2X.</p>
<p>This command applies the XSLT stylesheet (usually given by the
<code class="option">--stylesheet</code> option) to the XML
document in the file <em class=
"replaceable"><code>xml-document</code></em>. The result is written
to standard output (unless changed with <code class=
"option">--output</code>).</p>
<p>To read the source XML document from standard input, specify
<code class="literal">-</code> as the input document.</p>
</div>
<div class="refsect1" lang="en" xml:lang="en"><a id="id2535973"
name="id2535973"></a>
<h2>Options</h2>
<div class="variablelist">
<dl>
<dt><span class="term"><code class=
"option">--version</code></span></dt>
<dd>
<p>Display the docbook2X version.</p>
</dd>
</dl>
</div>
<div class="refsect2" lang="en" xml:lang="en"><a id="id2535995"
name="id2535995"></a>
<h3>Transformation output options</h3>
<div class="variablelist">
<dl>
<dt><span class="term"><code class="option">--output <em class=
"replaceable"><code>file</code></em></code>,</span> <span class=
"term"><code class="option">-o <em class=
"replaceable"><code>file</code></em></code></span></dt>
<dd>
<p>Write output to the given file (or URI), instead of standard
output.</p>
</dd>
</dl>
</div>
</div>
<div class="refsect2" lang="en" xml:lang="en"><a id="id2536028"
name="id2536028"></a>
<h3>Source document options</h3>
<div class="variablelist">
<dl>
<dt><span class="term"><code class=
"option">--xinclude</code>,</span> <span class="term"><code class=
"option">-I</code></span></dt>
<dd>
<p>Process XInclude directives in the source document.</p>
</dd>
<dt><span class="term"><code class="option">--sgml</code>,</span>
<span class="term"><code class="option">-S</code></span></dt>
<dd><a id="id2536066" class="indexterm" name="id2536066"></a>
<p>Indicate that the input document is SGML instead of XML. You
need this set this option if <em class=
"replaceable"><code>xml-document</code></em> is actually a SGML
file.</p>
<p>SGML parsing is implemented by conversion to XML via
<span class="citerefentry"><span class=
"refentrytitle"><span><strong class=
"command">sgml2xml</strong></span></span></span> from the SP
package (or <span class="citerefentry"><span class=
"refentrytitle"><span><strong class=
"command">osx</strong></span></span></span> from the OpenSP
package). All tag names in the SGML file will be normalized to
lowercase (i.e. the <code class="option">-xlower</code> option of
<span class="citerefentry"><span class=
"refentrytitle"><span><strong class=
"command">sgml2xml</strong></span></span></span> is used). ID
attributes are available for the stylesheet (i.e. option
<code class="option">-xid</code>). In addition, any ISO SDATA
entities used in the SGML document are automatically converted to
their XML Unicode equivalents. (This is done by a
<span><strong class="command">sed</strong></span> filter.)</p>
<p>The encoding of the SGML document, if it is not <code class=
"literal">us-ascii</code>, must be specified with the standard SP
environment variables: <strong class=
"userinput"><code>SP_CHARSET_FIXED=1 SP_ENCODING=<em class=
"replaceable"><code>encoding</code></em></code></strong>. (Note
that XML files specify their encoding with the XML declaration
<strong class="userinput"><code><?xml version="1.0"
encoding="<em class="replaceable"><code>encoding"</code></em>
?></code></strong> at the top of the file.)</p>
<p>The above conversion options cannot be changed. If you desire
different conversion options, you should invoke <span class=
"citerefentry"><span class="refentrytitle"><span><strong class=
"command">sgml2xml</strong></span></span></span> manually, and then
pass the results of that conversion to this program.</p>
</dd>
</dl>
</div>
</div>
<div class="refsect2" lang="en" xml:lang="en"><a id="id2536204"
name="id2536204"></a>
<h3>Retrieval options</h3>
<div class="variablelist">
<dl>
<dt><span class="term"><code class="option">--catalogs <em class=
"replaceable"><code>catalog-files</code></em></code>,</span>
<span class="term"><code class="option">-C <em class=
"replaceable"><code>catalog-files</code></em></code></span></dt>
<dd><a id="id2536229" class="indexterm" name="id2536229"></a>
<p>Specify additional XML catalogs to use for resolving Formal
Public Identifiers or URIs. SGML catalogs are not supported.</p>
<p>These catalogs are <span class="emphasis"><em>not</em></span>
used for parsing an SGML document under the <code class=
"option">--sgml</code> option. Use the environment variable
<code class="envar">SGML_CATALOG_FILES</code> instead to specify
the catalogs for parsing the SGML document.</p>
</dd>
<dt><span class="term"><code class=
"option">--network</code>,</span> <span class="term"><code class=
"option">-N</code></span></dt>
<dd>
<p><span><strong class="command">db2x_xsltproc</strong></span> 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.</p>
<p>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.</p>
</dd>
</dl>
</div>
</div>
<div class="refsect2" lang="en" xml:lang="en"><a id="id2536294"
name="id2536294"></a>
<h3>Stylesheet options</h3>
<div class="variablelist">
<dl>
<dt><span class="term"><code class="option">--stylesheet <em class=
"replaceable"><code>file</code></em></code>,</span> <span class=
"term"><code class="option">-s <em class=
"replaceable"><code>file</code></em></code></span></dt>
<dd>
<p>Specify the filename (or URI) of the stylesheet to use. The
special values <code class="literal">man</code> and <code class=
"literal">texi</code> are accepted as abbreviations, to specify
that <em class="replaceable"><code>xml-document</code></em> is in
DocBook and should be converted to man pages or Texinfo
(respectively).</p>
</dd>
<dt><span class="term"><code class="option">--param <em class=
"replaceable"><code>name</code></em>=<em class=
"replaceable"><code>expr</code></em></code>,</span> <span class=
"term"><code class="option">-p <em class=
"replaceable"><code>name</code></em>=<em class=
"replaceable"><code>expr</code></em></code></span></dt>
<dd>
<p>Add or modify a parameter to the stylesheet. <em class=
"replaceable"><code>name</code></em> is a XSLT parameter name, and
<em class="replaceable"><code>expr</code></em> is an XPath
expression that evaluates to the desired value for the parameter.
(This means that strings must be quoted, <span class=
"emphasis"><em>in addition</em></span> to the usual quoting of
shell arguments; use <code class="option">--string-param</code> to
avoid this.)</p>
</dd>
<dt><span class="term"><code class="option">--string-param
<em class="replaceable"><code>name</code></em>=<em class=
"replaceable"><code>string</code></em></code>,</span> <span class=
"term"><code class="option">-g <em class=
"replaceable"><code>name</code></em>=<em class=
"replaceable"><code>string</code></em></code></span></dt>
<dd>
<p>Add or modify a string-valued parameter to the stylesheet.</p>
<p>The string must be encoded in UTF-8 (regardless of the locale
character encoding).</p>
</dd>
</dl>
</div>
</div>
<div class="refsect2" lang="en" xml:lang="en"><a id="id2536426"
name="id2536426"></a>
<h3>Debugging and profiling</h3>
<div class="variablelist">
<dl>
<dt><span class="term"><code class="option">--debug</code>,</span>
<span class="term"><code class="option">-d</code></span></dt>
<dd>
<p>Display, to standard error, logs of what is happening during the
XSL transformation.</p>
</dd>
<dt><span class="term"><code class="option">--nesting-limit
<em class="replaceable"><code>n</code></em></code>,</span>
<span class="term"><code class="option">-D <em class=
"replaceable"><code>n</code></em></code></span></dt>
<dd>
<p>Change the maximum number of nested calls to XSL templates, used
to detect potential infinite loops. If not specified, the limit is
500 (libxslt’s default).</p>
</dd>
<dt><span class="term"><code class=
"option">--profile</code>,</span> <span class="term"><code class=
"option">-P</code></span></dt>
<dd>
<p>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.</p>
</dd>
<dt><span class="term"><code class="option">--xslt-processor
<em class="replaceable"><code>processor</code></em></code>,</span>
<span class="term"><code class="option">-X <em class=
"replaceable"><code>processor</code></em></code></span></dt>
<dd>
<p>Select the underlying XSLT processor used. The possible choices
for <em class="replaceable"><code>processor</code></em> are:
<span class="simplelist"><code class="literal">libxslt</code>,
<code class="literal">saxon</code>, <code class=
"literal">xalan-j</code></span>.</p>
<p>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.</p>
<p>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.</p>
</dd>
</dl>
</div>
</div>
</div>
<div class="refsect1" lang="en" xml:lang="en"><a id="id2536567"
name="id2536567"></a>
<h2>Environment</h2>
<div class="variablelist">
<dl>
<dt><span class="term"><code class=
"envar">XML_CATALOG_FILES</code></span></dt>
<dd>
<p>Specify XML Catalogs. If not specified, the standard catalog
(<code class="filename">/etc/xml/catalog</code>) is loaded, if
available.</p>
</dd>
<dt><span class="term"><code class=
"envar">DB2X_XSLT_PROCESSOR</code></span></dt>
<dd>
<p>Specify the XSLT processor to use. The effect is the same as the
<code class="option">--xslt-processor</code> option. The primary
use of this variable is to allow you to quickly test different XSLT
processors without having to add <code class=
"option">--xslt-processor</code> to every script or make file in
your documentation build system.</p>
</dd>
</dl>
</div>
</div>
<div class="refsect1" lang="en" xml:lang="en"><a id="id2536622"
name="id2536622"></a>
<h2>Conforming to</h2>
<p><a href="http://www.w3.org/TR/xslt" target="_top">XML Stylesheet
Language – Transformations (XSLT), version 1.0</a>, a W3C
Recommendation.</p>
</div>
<div class="refsect1" lang="en" xml:lang="en"><a id="id2536640"
name="id2536640"></a>
<h2>Notes</h2>
<a id="id2536646" class="indexterm" name="id2536646"></a>
<p>In its earlier versions (< 0.8.4), docbook2X required XSLT
extensions to run, and <span><strong class=
"command">db2x_xsltproc</strong></span> was a special libxslt-based
processor that had these extensions compiled-in. When the
requirement for XSLT extensions was dropped, <span><strong class=
"command">db2x_xsltproc</strong></span> became a Perl script which
translates the options to <span><strong class=
"command">db2x_xsltproc</strong></span> to conform to the format
accepted by the stock <span class="citerefentry"><span class=
"refentrytitle"><span><strong class=
"command">xsltproc</strong></span></span></span> which comes with
libxslt.</p>
<p>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!)</p>
</div>
<div class="refsect1" lang="en" xml:lang="en"><a id="id2536724"
name="id2536724"></a>
<h2>See Also</h2>
<p>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.</p>
</div>
</div>
<div class="navfooter">
<hr />
<table width="100%" summary="Navigation footer">
<tr>
<td width="40%" align="left"><a accesskey="p" href=
"xsltproc.html"><< Previous</a> </td>
<td width="20%" align="center"><a accesskey="u" href=
"xsltproc.html">Up</a></td>
<td width="40%" align="right"> <a accesskey="n" href=
"sgml2xml-isoent.html">Next >></a></td>
</tr>
<tr>
<td width="40%" align="left" valign="top">The XSLT
stylesheets </td>
<td width="20%" align="center"><a accesskey="h" href=
"docbook2X.html">Table of Contents</a></td>
<td width="40%" align="right" valign="top">
<span><strong class=
"command">sgml2xml-isoent</strong></span></td>
</tr>
</table>
</div>
<p class="footer-homepage"><a href=
"http://docbook2x.sourceforge.net/" title=
"docbook2X: Home page">docbook2X home page</a></p>
</body>
</html>
