<!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>