Using the Extensions

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:

The line numbers and callouts in the following example are made possible through the use of the DocBook XSLT extension functions.

  1 @rem = '--*-Perl-*--                                       (1)
    @echo off
    perl.exe %_batchname %$
    goto endofperl                                             (2)
  5 @rem ';
    
    # Compress mail...
    
    require 'n:/home/nwalsh/lib/cygnus.pl';                    (3)
 10 require 'timelocal.pl';                                    (3)
    use Cwd;   (4)
    
    select (STDERR); $| = 1;
    select (STDOUT); $| = 1;
 15 
    @DIRS = ("/home/nwalsh/Mail");
    while (@DIRS) {
        $dir = shift @DIRS;
        opendir (DIR, $dir);
 20     while ($fname = readdir(DIR)) {
            $file = "$dir/$fname";
            next if ! -d $file;
            next if $fname =~ /^\.\.?$/;
    
 25         print "$file\n";
            push (@DIRS, $file);
            &compress ($file);                                 (5)
        }
    }
 30 
    exit;
1

The prologue handles embedding a Perl script in a DOS batch file.

2

The goto statement, interpreted by the DOS batch file interpreter, skips over the body of the Perl script.

3

The require statement sources in external program fragments.

4

The use statement is similar, but has additional utility. It is a Perl5 function. (Note that this callout area specifies both a line and a column.)

5

This is a user subroutine call.

The extensions are included in the DocBook XSL Stylesheets distribution in the extensions directory.

To use the extensions, you need to:

  1. Determine which extension jar file (in the extensions directory) corresponds most closely to the Java XSLT engine you use.

  2. Include the name of that jar file in your Java CLASSPATH.

  3. Set the correct XSLT extension parameters to enable the behavior you need. (For compatibility with other processors, the extensions are disabled by default.)

For example, if you're using Saxon 6.4.4, include the extensions/saxon644.jar file in your Java classpath. If you're using Xalan-Java 2, include the extensions/xalan2.jar file in your classpath.

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 Xalan-C++.

At a minimum, you'll also need to set the value of the use.extensions parameter to 1 (instead of the default 0).

To enable the extensions from the command line, you need to pass the use.extensions parameter to your XSLT engine. Here's an example of how to do that with Saxon:

  java com.icl.saxon.StyleSheet  filename.xml docbook/html/docbook.xsl \
    use.extensions=1 > output.html

and here's an example of how to do it with Xalan:

  java org.apache.xalan.xslt.Process -IN filename.xml -XSL docbook/html/docbook.xsl \
    -PARAM use.extensions 1 -OUT output.html