Chapter 2. Extensions
Prev |  | Next

## Chapter 2. 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:

- embed callouts in verbatim environments (program listings, for example)

- add line numbers to verbatim environments (program listings, for example)

- adjust the width of table columns in HTML output to match specs in the CALS table source

- directly include contents of a text file in rendered output

- determine the intrinsic size of an image

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

Example 2.1. A program listing with line numbering and callouts

      1 @rem = '--*-Perl-*--
        @echo off
        perl.exe %_batchname %$
        goto endofperl
      5 @rem ';

        # Compress mail...

        require 'n:/home/nwalsh/lib/cygnus.pl';
     10 require 'timelocal.pl';
        use Cwd;

        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);
            }
        }
     30
        exit;

| The prologue handles embedding a Perl script in a DOS batch file.
| The `goto` statement, interpreted by the DOS batch file interpreter, skips over the body of the Perl script.
| The `require` statement sources in external program fragments.
| 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.)
| This is a user subroutine call.

## Using the Extensions

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.

### Note

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

Example 2.2. Enabling the extensions from the command line

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

Prev | Up | Next
Customizing DocBook XSL stylesheets | Home | Chapter 3. Tools documentation