<sect1 id="xsltproc">

<sect1info>

<abstract role="texinfo-node">

  <para>How to run the docbook2X XSLT stylesheets</para>

</abstract>

</sect1info>

<title>The XSLT stylesheets</title>

<indexterm><primary>XSLT processor</primary></indexterm>

<indexterm><primary>libxslt</primary></indexterm>

<indexterm><primary>SAXON</primary></indexterm>

<indexterm><primary>catalog</primary></indexterm>

<indexterm><primary>&db2x_xsltproc;</primary></indexterm>

<para>

docbook2X uses a XSLT 1.0 processor to run its stylesheets.

docbook2X comes with a wrapper script,

&db2x_xsltproc_ref;, that invokes the XSLT processor, 

but you can invoke the XSLT processor in any other

way you wish.

</para>

<para>

The stylesheets are described in

<olink targetdocent="docbook2man-xslt">the man-pages stylesheets

reference</olink>

and <olink targetdocent="docbook2texi-xslt">the Texinfo stylesheets

reference</olink><footnote role="html">

<para>The HTML versions of these documents are not in the docbook2X

distribution, because they are too large.  Your alternatives are:

(i) use the HTML version on the docbook2X Web site, (ii) use the Texinfo

version that is distributed with docbook2X, or (iii) generate the HTML

yourself with the DocBook XSL stylesheets.  To do the last, simply

type <userinput>make html</userinput> in

the <filename>xslt/documentation/</filename> directory.</para>

</footnote>.

</para>

<indexterm><primary>pure XSLT</primary></indexterm>

<indexterm><primary><command>xsltproc</command></primary></indexterm>

<para>

Pure-XSLT implementations of &db2x_manxml;

and &db2x_texixml; also exist.  

They may be used as follows (assuming libxslt as the XSLT processor).

<example id="xsltproc.db2x_manxml">

<title>Convert to man pages using pure-XSLT &db2x_manxml;</title>

><prompt>$ </prompt><userinput>xsltproc -o mydoc.mxml \

    <replaceable>docbook2X-path</replaceable>/xslt/man/docbook.xsl \

    mydoc.xml</userinput>

<prompt>$ </prompt><userinput>xsltproc \

    <replaceable>docbook2X-path</replaceable>/xslt/backend/db2x_manxml.xsl \

    mydoc.mxml</userinput></screen>

</example>

<example id="xsltproc.db2x_texixml">

<title>Convert to Texinfo using Pure-XSLT &db2x_texixml;</title>

><prompt>$ </prompt><userinput>xsltproc -o mydoc.txml \

    <replaceable>docbook2X-path</replaceable>/xslt/texi/docbook.xsl \

    mydoc.xml</userinput>

<prompt>$ </prompt><userinput>xsltproc \

    <replaceable>docbook2X-path</replaceable>/xslt/backend/db2x_texixml.xsl \

    mydoc.txml</userinput></screen>

</example>

</para>

<para>

Here, &xsltproc_cmd; is used instead of &db2x_xsltproc;, since

if you are in a situtation where you cannot use the Perl implementation 

of &db2x_manxml;, you probably cannot use &db2x_xsltproc; either.

</para>

<para>

If for portability reasons you prefer not to use the file-system path 

to the docbook2X files, you can use the XML catalog

provided in <filename>xslt/catalog.xml</filename>

and the global URIs contained therein.

</para>

<refentry id="db2x_xsltproc">

<indexterm><primary>XSLT processor</primary></indexterm>

<indexterm><primary>libxslt</primary></indexterm>

<indexterm><primary>&db2x_xsltproc;</primary></indexterm>

<refmeta>

<refentrytitle id="db2x_xsltproc_name">&db2x_xsltproc;</refentrytitle>

<manvolnum>1</manvolnum>

</refmeta>

<refnamediv>

<refname>&db2x_xsltproc;</refname>

<refpurpose>XSLT processor invocation wrapper</refpurpose>

</refnamediv>

<refsynopsisdiv>

<cmdsynopsis>

<command>db2x_xsltproc</command>

<arg><replaceable>options</replaceable></arg>

<arg choice="plain"><replaceable>xml-document</replaceable></arg>

</cmdsynopsis>

</refsynopsisdiv>

<refsect1>

<title>Description</title>

<para>

&db2x_xsltproc; invokes the XSLT 1.0 processor for docbook2X.

</para>

<para>

This command applies the XSLT stylesheet 

(usually given by the <option>--stylesheet</option> option)

to the XML document in the file <replaceable>xml-document</replaceable>.

The result is written to standard output (unless changed with 

<option>--output</option>).  

</para>

<para>

To read the source XML document from standard input,

specify <literal>-</literal> as the input document.

</para>

</refsect1>

<refsect1>

<title>Options</title>

<variablelist>

<varlistentry>

<term><option>--version</option></term>

<listitem><para>

Display the docbook2X version.

</para></listitem>

</varlistentry>

</variablelist>

<refsect2>

<title>Transformation output options</title>

<variablelist>

<varlistentry>

<term><option>--output <replaceable>file</replaceable></option></term>

<term><option>-o <replaceable>file</replaceable></option></term>

<listitem><para>

Write output to the given file (or URI), instead of standard output.

</para></listitem>

</varlistentry>

</variablelist>

</refsect2>

<refsect2>

<title>Source document options</title>

<variablelist>

<varlistentry>

<term><option>--xinclude</option></term>

<term><option>-I</option></term>

<listitem><para>

Process XInclude directives in the source document.

</para></listitem>

</varlistentry>

<varlistentry>

<term><option>--sgml</option></term>

<term><option>-S</option></term>

<listitem>

<indexterm><primary>SGML</primary></indexterm>

<para>

Indicate that the input document is SGML instead of XML.

You need this set this option if <replaceable>xml-document</replaceable>

is actually a SGML file.

</para>

<para>

SGML parsing is implemented by conversion to XML via &sgml2xml; from the

SP package (or &osx; from the OpenSP package).  All tag names in the

SGML file will be normalized to lowercase (i.e. the <option>-xlower</option>

option of &sgml2xml; is used).  ID attributes are available

for the stylesheet (i.e. option <option>-xid</option>).  In addition,

any ISO SDATA entities used in the SGML document are automatically converted

to their XML Unicode equivalents.  (This is done by a

<command>sed</command> filter.)

</para>

<para>

The encoding of the SGML document, if it is not

<literal>us-ascii</literal>, must be specified with the standard

SP environment variables: <userinput>SP_CHARSET_FIXED=1

SP_ENCODING=<replaceable>encoding</replaceable></userinput>.

(Note that XML files specify their encoding with the XML declaration

<userinput><?xml version="1.0" encoding="<replaceable>encoding"</replaceable> ?></userinput>

at the top of the file.)

</para>

<para>

The above conversion options cannot be changed.  If you desire different

conversion options, you should invoke &sgml2xml; manually, and then pass

the results of that conversion to this program.

</para>

</listitem>

</varlistentry>

</variablelist>

</refsect2>

<refsect2>

<title>Retrieval options</title>

<variablelist>

<varlistentry>

<term><option>--catalogs <replaceable>catalog-files</replaceable></option></term>

<term><option>-C <replaceable>catalog-files</replaceable></option></term>

<listitem>

<indexterm><primary>catalog</primary></indexterm>

<para>

Specify additional XML catalogs to use for resolving Formal

Public Identifiers or URIs.  SGML catalogs are not supported.

</para>

<para>

These catalogs are <emphasis>not</emphasis> used for parsing an SGML

document under the <option>--sgml</option> option.  Use

the environment variable <envar>SGML_CATALOG_FILES</envar> instead 

to specify the catalogs for parsing the SGML document.

</para>

</listitem>

</varlistentry>

<varlistentry>

<term><option>--network</option></term>

<term><option>-N</option></term>

<listitem><para>

&db2x_xsltproc; 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.

</para>

<para>

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.

</para>

</listitem>

</varlistentry>

</variablelist>

</refsect2>

<refsect2>

<title>Stylesheet options</title>

<variablelist>

<varlistentry>

<term><option>--stylesheet <replaceable>file</replaceable></option></term>

<term><option>-s <replaceable>file</replaceable></option></term>

<listitem><para>

Specify the filename (or URI) of the stylesheet to use.  

The special values <literal>man</literal> and <literal>texi</literal> 

are accepted as abbreviations, to specify that

<replaceable>xml-document</replaceable> is in DocBook and

should be converted to man pages or Texinfo (respectively).

</para></listitem>

</varlistentry>

<varlistentry>

<term><option>--param <replaceable>name</replaceable>=<replaceable>expr</replaceable></option></term>

<term><option>-p <replaceable>name</replaceable>=<replaceable>expr</replaceable></option></term>

<listitem><para>

Add or modify a parameter to the stylesheet.

<replaceable>name</replaceable> is a XSLT parameter name, and

<replaceable>expr</replaceable> is an XPath expression that evaluates to

the desired value for the parameter.  (This means that strings must be

quoted, <emphasis>in addition</emphasis> to the usual quoting of shell

arguments; use <option>--string-param</option> to avoid this.)

</para></listitem>

</varlistentry>

<varlistentry>

<term><option>--string-param <replaceable>name</replaceable>=<replaceable>string</replaceable></option></term>

<term><option>-g <replaceable>name</replaceable>=<replaceable>string</replaceable></option></term>

<listitem><para>

Add or modify a string-valued parameter to the stylesheet.

</para>

<para>

The string must be encoded in UTF-8 (regardless of the locale 

character encoding).

</para>

</listitem>

</varlistentry>

</variablelist>

</refsect2>

<refsect2>

<title>Debugging and profiling</title>

<variablelist>

<varlistentry>

<term><option>--debug</option></term>

<term><option>-d</option></term>

<listitem><para>

Display, to standard error, logs of what is happening during the 

XSL transformation.

</para></listitem>

</varlistentry>

<varlistentry>

<term><option>--nesting-limit <replaceable>n</replaceable></option></term>

<term><option>-D <replaceable>n</replaceable></option></term>

<listitem><para>

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).

</para></listitem>

</varlistentry>

<varlistentry>

<term><option>--profile</option></term>

<term><option>-P</option></term>

<listitem><para>

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.

</para></listitem>

</varlistentry>

<varlistentry>

<term><option>--xslt-processor <replaceable>processor</replaceable></option></term>

<term><option>-X <replaceable>processor</replaceable></option></term>

<listitem><para>

Select the underlying XSLT processor used.  The possible choices for

<replaceable>processor</replaceable> are: <simplelist type="inline">

<member><literal>libxslt</literal></member>

<member><literal>saxon</literal></member>

<member><literal>xalan-j</literal></member></simplelist>.

</para>

<para>

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.

</para>

<para>

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.

</para>

</listitem>

</varlistentry>

</variablelist>

</refsect2>

</refsect1>

<refsect1>

<title>Environment</title>

<variablelist>

<varlistentry>

<term><envar>XML_CATALOG_FILES</envar></term>

<listitem><para>Specify XML Catalogs.

If not specified, the standard catalog

(<filename>/etc/xml/catalog</filename>) is loaded, if available.

</para>

</listitem>

</varlistentry>

<varlistentry>

<term><envar>DB2X_XSLT_PROCESSOR</envar></term>

<listitem><para>Specify the XSLT processor to use.

The effect is the same as the <option>--xslt-processor</option>

option.  The primary use of this variable is to allow you to quickly 

test different XSLT processors without having to add 

<option>--xslt-processor</option> to every script or make file in 

your documentation build system.

</para></listitem>

</varlistentry>

</variablelist>

</refsect1>

<refsect1>

<title>Conforming to</title>

<para>

<ulink url="http://www.w3.org/TR/xslt">XML Stylesheet Language – Transformations (XSLT), version

1.0</ulink>, a W3C Recommendation.

</para>

</refsect1>

<refsect1>

<title>Notes</title>

<indexterm><primary>XSLT extensions</primary></indexterm>

<para>

In its earlier versions (< 0.8.4),

docbook2X required XSLT extensions to run, and

&db2x_xsltproc; was a special libxslt-based processor that had these

extensions compiled-in. When the requirement for XSLT extensions

was dropped, &db2x_xsltproc; became a Perl script which translates

the options to &db2x_xsltproc; to conform to the format accepted by

the stock &xsltproc_cmd; which comes with libxslt.

</para>

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

</para>

</refsect1>

&man-page-author-section;

<refsect1>

<title>See Also</title>

&man-page-see-also;

<para>

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.

</para>

</refsect1>

</refentry>

<refentry id="sgml2xml-isoent">

<indexterm><primary>SGML</primary></indexterm>

<indexterm><primary>ISO entities</primary></indexterm>

<indexterm><primary>&sgml2xml-isoent;</primary></indexterm>

<indexterm><primary>DocBook</primary></indexterm>

<refmeta>

<refentrytitle id="sgml2xml-isoent_name">&sgml2xml-isoent;</refentrytitle>

<manvolnum>1</manvolnum>

</refmeta>

<refnamediv>

<refname>&sgml2xml-isoent;</refname>

<refpurpose>Convert SGML to XML with support for ISO

entities</refpurpose>

</refnamediv>

<refsynopsisdiv>

<cmdsynopsis>

<command>sgml2xml-isoent</command>

<arg><replaceable>sgml-document</replaceable></arg>

</cmdsynopsis>

</refsynopsisdiv>

<refsect1>

<title>Description</title>

<para>

&sgml2xml-isoent; converts an SGML document to XML,

with support for the ISO entities.

This is done by using &sgml2xml; from the

SP package (or &osx; from the OpenSP package),

and the declaration for the XML version of the ISO entities

is added to the output.

This means that the output of this conversion

should work as-is with any XML tool.

</para>

<para>

This program is often used for processing SGML DocBook documents

with XML-based tools.  In particular, &db2x_xsltproc_ref;

calls this program as part of its <option>--sgml</option>

option.  On the other hand, it is probably not helpful for 

migrating a source SGML text file to XML, since the conversion 

mangles the original formatting.

</para>

<para>

Since the XML version of the ISO entities 

are referred to directly, not via a DTD, this tool 

also works with document types other than DocBook.

</para>

</refsect1>

<refsect1>

<title>Notes</title>

<para>

The ISO entities are referred using the public identifiers 

<literal>ISO 8879:1986//ENTITIES//<replaceable>…</replaceable>//EN//XML</literal>.  

The catalogs used when parsing the converted document should 

resolve these entities to the appropriate place (on the local

filesystem).  If the entities are not resolved in the catalog, 

then the fallback is to get the entity files

from the <literal>http://www.docbook.org/</literal> Web site.

</para>

</refsect1>

&man-page-author-section;

<refsect1>

<title>See Also</title>

<para>

<simplelist type="inline">

<member>&sgml2xml;</member>

<member>&osx;</member>

</simplelist>

</para>

</refsect1>

</refentry>

</sect1>