<chapter>
<title>Saxon Extensions</title>
<?dbhtml filename="extensions.html"?>

<para>Beginning with release 1.25, the DocBook XSL Stylesheets include
a set of Java extensions for Saxon.</para>

<para>These extensions enable callouts, numbered program listings, and
the direct inclusion of text:</para>

<programlistingco>
<areaspec>
<area coords="1" id="prologue"/>
<area coords="4" id="skipeof"/>
<areaset coords="" id="xreq">
<area coords="9" id="require1"/>
<area coords="10" id="require2"/>
</areaset>
<area coords="11 12" id="use"/>
<area coords="27" id="funccall"/>
</areaspec>
<programlisting linenumbering='numbered'>@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);
        &amp;compress ($file);
    }
}

exit;</programlisting>
<calloutlist>
<callout arearefs="prologue">
<para>The prologue handles embedding a Perl script in a DOS batch file.</para>
</callout>
<callout arearefs="skipeof">
<para>The <literal>goto</literal> statement, interpreted by the DOS batch
file interpreter, skips over the body of the Perl script.</para>
</callout>
<callout arearefs="require1">
<para>The <literal>require</literal> statement sources in external program
fragments.</para>
</callout>
<callout arearefs="use">
<para>The <literal>use</literal> statement is similar, but has additional
utility.  It is a Perl5 function.  (Note that this callout area specifies
both a line and a column.)</para>
</callout>
<callout arearefs="funccall">
<para>This is a user subroutine call.</para>
</callout>
</calloutlist>
</programlistingco>

<section><title>Installation</title>

<para>The extensions are included in the distribution in
<filename>extensions/nwalsh.jar</filename>. Just make sure that 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>

</chapter>
