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.
A program listing with line numbering and callouts
@rem = '--*-Perl-*--
@echo off
perl.exe %_batchname %$
goto endofperl
@rem ';
# Compress mail...
require 'n:/home/nwalsh/lib/cygnus.pl';
require 'timelocal.pl';
use Cwd;
select (STDERR); $| = 1;
select (STDOUT); $| = 1;
@DIRS = ("/home/nwalsh/Mail");
while (@DIRS) {
$dir = shift @DIRS;
opendir (DIR, $dir);
while ($fname = readdir(DIR)) {
$file = "$dir/$fname";
next if ! -d $file;
next if $fname =~ /^\.\.?$/;
print "$file\n";
push (@DIRS, $file);
&compress ($file);
}
}
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:
Determine which extension jar file (in the extensions directory) corresponds most
closely to the Java XSLT engine you use.
Include the name of that jar file in your Java
CLASSPATH.
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).
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