<title>Extensions</title>
<?dbhtml filename="extensions.html"?>
-<para>Extensions are supported in recent releases of Saxon and Xalan.</para>
-
-<para>These extensions enable callouts, numbered program listings, and
-the direct inclusion of text:</para>
-
+ <para>The DocBook XSL Stylesheets distribution includes a set of
+ DocBook-specific XSLT extensions (currently implemented in Java)
+ for performing a variety of functions that would be impractical to
+ implement with standard XSLT only:
+ <itemizedlist>
+ <listitem>
+ <para>embed callouts in verbatim environments (program
+ listings, for example)</para>
+ </listitem>
+ <listitem>
+ <para>add line numbers to verbatim environments (program
+ listings, for example)</para>
+ </listitem>
+ <listitem>
+ <para>adjust the width of table columns in HTML output to
+ match specs in the CALS table source</para>
+ </listitem>
+ <listitem>
+ <para>directly include contents of a text file in rendered
+ output</para>
+ </listitem>
+ <listitem>
+ <para>determine the intrinsic size of an image</para>
+ </listitem>
+ </itemizedlist>
+ </para>
+
+ <para>The line numbers and callouts in the following example are
+ made possible through the use of the DocBook XSLT extention
+ functions.
+ <example>
+ <title>A program listing with line numbering and callouts</title>
<programlistingco>
<areaspec>
<area coords="1" id="prologue"/>
</callout>
</calloutlist>
</programlistingco>
+</example>
+</para>
<section>
-<title>Saxon Extensions</title>
-
-<para>The DocBook XSL Stylesheets include a set of Java extensions for
-Saxon.</para>
-
-<section><title>Installation</title>
-
-<para>The extensions are included in the distribution in
-<filename>extensions/saxon642.jar</filename> and
-<filename>extensions/saxon643.jar</filename>. Use the former for Saxon
-version 6.4.2 and the latter for Saxon 6.4.3 or Saxon 6.4.4. Saxon
-version 6.4.1 and all prior releases contained a significant bug, they
-are not supported.</para>
-
-<para>Just make sure that the right jar file is in your CLASSPATH when
-you run Saxon.</para>
-
-</section>
-
-<section><title>Using the Extensions</title>
-
-<para>For compatibility with other processors, the extensions are disabled
-by default. To enable the extensions, turn on
-<literal>$saxon.extensions</literal>, for example by passing
-<literal>saxon.extensions=1</literal> to Saxon.</para>
-
-<para>For more control over the specific extensions, see
-<olink type="title" localinfo="html/param.html"
- targetdocent="html-param.xml"/>.</para>
-</section>
-</section>
-
-<section>
-<title>Xalan Extensions</title>
-
-<para>The DocBook XSL Stylesheets include a set of Java extensions for
-XalanJ version 2. Extensions are not provided for XalanC at this time.</para>
-
-<section><title>Installation</title>
-
-<para>The extensions are included in the distribution in
-<filename>extensions/xalan2.jar</filename>.
-Xalan 1 is not supported.</para>
-
-<para>Just make sure that the jar file is in your CLASSPATH when
-you run Xalan.</para>
-
-</section>
-
-<section><title>Using the Extensions</title>
-
-<para>For compatibility with other processors, the extensions are disabled
-by default. To enable the extensions, turn on
-<literal>$xalan.extensions</literal>, for example by passing
-<literal>-PARAM xalan.extensions 1</literal> to Xalan.</para>
-
-<para>For more control over the specific extensions, see
-<olink type="title" localinfo="html/param.html"
- targetdocent="html-param.xml"/>.</para>
-</section>
-</section>
-
-</chapter>
+<title>Using the Extensions</title>
+
+ <para>The extensions are included in the DocBook XSL Stylesheets
+ distribution in the <filename
+ class="directory">extensions</filename> directory.
+ </para>
+ <procedure>
+ <para>To use the extensions, you need to:</para>
+ <step>
+ <para>Determine which extension jar file (in the <filename
+ class="directory">extensions</filename>)corresponds mostly
+ closely to the Java XSLT engine you use.</para>
+ </step>
+ <step>
+ <para>Include the name of that jar file in your Java
+ <envar>CLASSPATH</envar>.</para>
+ </step>
+ <step>
+ <para>Set the correct <ulink url="html/" >XSLT extension
+ parameters</ulink> to enable the behavior you need. (For
+ compatibility with other processors, the extensions are
+ disabled by default.)</para>
+ </step>
+ </procedure>
+
+ <para>
+ For example, if you're using Saxon 6.4.4, include the
+ <filename>extensions/saxon644.jar</filename> file in your Java
+ classpath. If you're using Xalan-Java 2, include the
+ <filename>extensions/xalan2.jar</filename> file in your
+ classpath.
+
+ <note>
+ <para>The DocBook XSLT extensions are not supported for
+ Xalan-Java 1 or for versions of Saxon prior to 6.4.3. And
+ because the only current implementation of the extensions is
+ written in Java, you can't yet use them with xsltproc (which
+ is a written in C) or with the Xalan-C++.
+ </para>
+ </note>
+
+ At a minimum, you'll also need to set the value of the <ulink
+ url="html/use.extensions.html" >use.extensions</ulink>
+ parameter to <literal>1</literal> (instead of the default
+ <literal>0</literal>).</para>
+ <example>
+ <title>Enabling the Extensions from the Command Line</title>
+ <para>To enable the extensions for the command line, you need to
+ pass the the <parameter>use.extensions</parameter> parameter
+ to your XSLT engine. Here's an example of how to do that with Saxon:
+ <screen>
+java com.icl.saxon.StyleSheet <replaceable>filename.xml</replaceable> <replaceable>docbook/html/docbook.xsl</replaceable> use.extensions=1 > <replaceable>output.html</replaceable>
+</screen>
+ and here's an example of how to do it with Xalan:
+ <screen>
+java org.apache.xalan.xslt.Process -IN <replaceable>filename.xml</replaceable> -XSL <replaceable>docbook/html/docbook.xsl</replaceable> -PARAM use.extensions 1 -OUT <replaceable>output.html</replaceable>
+</screen>
+ </para>
+ </example>
+ </section>
+
+</chapter>
\ No newline at end of file
projects / docbook-dsssl / commitdiff