/usr/share/doc/libsaxon-java/using-xsl.html is in libsaxon-java-doc 1:6.5.5-12.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 | <html>
<head>
<meta HTTP-EQUIV="Content-Type" CONTENT="text/html; charset=windows-1252">
<meta NAME="GENERATOR" CONTENT="Microsoft FrontPage 3.0">
<title>Using Stylesheets</title>
<body leftmargin="150" bgcolor="#ddeeff"><font face="Arial, Helvetica, sans-serif">
<div align=right><a href="index.html">SAXON home page</a></div>
<b><font FACE="Arial, Helvetica, sans-serif" SIZE="4">
<p></font><font FACE="Arial, Helvetica, sans-serif" color="#FF0080" size="7">Using Stylesheets</font><font FACE="Arial, Helvetica, sans-serif" SIZE="4"></p>
</font></b>
<hr>
<p>This page describes how to use SAXON XSLT Stylesheets, either from the command line,
or from the Java API.</p>
<table width="100%">
<tr>
<td colspan=2 width="719" bgcolor="#0000FF"><font color="#FFFFFF"><big><b>Contents</b></big></font></td>
</tr>
<tr>
<td width="60%" bgcolor="#0000FF"><font color="#FFFFFF"><big>Using Stylesheets</big></font></td>
<td bgcolor="#0000FF"><font color="#FFFFFF"><big>Reference</big></font></td>
</tr>
</tr>
<tr>
<td VALIGN="top" bgcolor="#00FFFF">
<a href="#Command-line">Using Saxon from the Command Line</a><br>
<a href="#Embedding">Embedding Saxon in an Application</a><br>
<!--<a href="#Applet">Running Saxon in an Applet</a><br>-->
</td>
<td VALIGN="top" bgcolor="#00FFFF">
See also:<br>
<a href="xsl-elements.html">XSL Elements</a><br>
<a href="expressions.html">XSL Expressions</a><br>
<a href="patterns.html">XSL Patterns</a><br>
<a href="extensibility.html">SAXON Extensibility</a><br>
<a href="conformance.html">SAXON XSL Conformance</a><br>
</td>
</tr>
</table>
<h2><a name="Command-line">Using Saxon from the Command Line</a></h2>
<font size="3"><p>The Java class com.icl.saxon.StyleSheet has a main program that
may be used to apply a given style sheet to a given source XML document. The form of
command is:</p>
<p><strong><font color="#FF0080">java com.icl.saxon.StyleSheet
[options] source-document stylesheet [ <i>params…</i>]</font></strong></p>
<p>The options must come first, then the two file names, then the params.
The stylesheet is omitted if the -a option is present.</p>
<p>The file <code>saxon.jar</code> must be on your classpath. If you are running under JDK 1.2 or 1.3, the classpath
must also include the file <code>saxon-xml-apis.jar</code>.</p>
<p>If you are using JDK 1.4 or later, and if your stylesheet does not use extensions functions,
you can use the simpler form of command:</p>
<p><strong><font color="#FF0080">java -jar <i>dir</i>/saxon.jar
[options] source-document stylesheet [ <i>params…</i>]</font></strong></p>
<p>The options are as follows (in any order): </p>
<table>
<tr><td valign="top" width="20%">-a</td>
<td>Use the xml-stylesheet processing instruction in the source document
to identify the stylesheet to be used. The stylesheet argument should be omitted.
</td></tr>
<tr><td valign="top">-ds | -dt</td>
<td>Selects the implementation of the internal tree model. -dt selects the "tinytree"
model (the default). -ds selects the traditional tree model. See <a href="#choosingmodel">
Choosing a tree model</a> below.</td></tr>
<tr><td valign="top">-l</td>
<td>Switches line numbering on for the source document. Line numbers are accessible
through the extension function saxon:line-number(), or from a trace listener.</td></tr>
<tr><td valign="top">-m classname</td>
<td>Use the specified Emitter to process the output from xsl:message. The class must implement
the com.icl.saxon.output.Emitter class. This interface is similar to a SAX ContentHandler,
it takes a stream of events to generate output. In general the content of a message is an XML
fragment. By default the standard XML emitter is used, configured to write to the standard error
stream, and to include no XML declaration. Each message is output as a new document.</td></tr>
<tr><td valign="top">-noext</td>
<td>Suppress calls on extension functions, other than system-supplied Saxon and EXSLT extension
functions. This option is useful when loading an untrusted stylesheet, perhaps from a remote
site using an <code>http://</code> URL; it ensures that the stylesheet cannot call Java methods
and thereby gain privileged access to resources on your machine.
</td></tr>
<tr><td valign="top">-o filename</td>
<td>Send output to named file. In the absence of this option, output goes to standard output.
If the source argument identifies a directory, this option is mandatory and must also identify
a directory; on completion it will contain one output file for each file in the source directory.
</td></tr>
<tr><td valign="top">-r classname</td>
<td>Use the specified URIResolver to process all URIs. The URIResolver is a user-defined class,
that extends the com.icl.saxon.URIResolver class, whose function is to take a URI supplied as
a string, and return a SAX InputSource. It is invoked to process URIs used in the document() function,
in the xsl:include and xsl:import elements, and (if -u is also specified) to process the URIs
of the source file and stylesheet file provided on the command line.</td></tr>
<tr><td valign="top">-t</td>
<td>Display version and timing information to the standard error output</td></tr>
<tr><td valign="top">-T</td>
<td>Display stylesheet tracing information to the standard error output.
Also switches line numbering on for the source document.</td></tr>
<tr><td valign="top">-TL classname</td>
<td>Run the stylesheet using the specified TraceListener. The classname names a user-defined
class, which must implement com.icl.saxon.trace.TraceListener</td></tr>
<tr><td valign="top">-u</td>
<td>Indicates that the names of the source document and the style document are URLs;
otherwise they are taken as filenames, unless they start with "http:" or "file:", in which
case they are taken as URLs</td></tr>
<tr><td valign="top">-w0, w1, or w2</td>
<td>Indicates the policy for handling recoverable errors in the stylesheet: w0 means
recover silently, w1 means recover after writing a warning message to the system error
output, w2 means signal the error and do not attempt recovery. (Note, this does not
currently apply to all errors that the XSLT recommendation describes as recoverable).
The default is w1.</td></tr>
<tr><td valign="top">-x classname</td>
<td>Use specified SAX parser for source file and any files loaded using the document() function.
The parser must be the fully-qualified class name
of a Java class that implements the org.xml.sax.Parser or org.xml.sax.XMLReader interface</td></tr>
<tr><td valign="top">-y classname</td>
<td>Use specified SAX parser for stylesheet file, including any loaded using xsl:include
or xsl:import. The parser must be the fully-qualified class name
of a Java class that implements the org.xml.sax.Parser or org.xml.sax.XMLReader interface</td></tr>
<tr><td valign="top">-?</td><td>Display command syntax</td></tr>
<tr><td valign="top">source-document</td>
<td>Identifies the source file or directory. Mandatory. If this is a directory, all the
files in the directory will be processed individually. In this case the -o option is
mandatory, and must also identify a directory, to contain the corresponding output files.
A directory must be specified as a filename, not as a URL.</td></tr>
<tr><td valign="top">stylesheet</td>
<td>Identifies the stylesheet. Mandatory unless the -a option is used.</td></tr>
</table>
<p>A param takes the form <i>name=value</i>, <i>name</i> being the
name of the parameter, and <i>value</i> the value of the parameter. These parameters are
accessible within the stylesheet as normal variables, using the $name syntax, provided
they are declared using a top-level xsl:param element. If there is no such declaration, the supplied
parameter value is silently ignored.</p>
<p>Under Windows it is possible to supply a value containing
spaces by enclosing it in double quotes, for example <b>name="John Smith"</b>. This is a feature
of the operating system shell, not something Saxon does, so it may not work the
same way under every operating system.</p>
<p>If the -a option is used, the name of the stylesheet is
omitted. The source document must contain a <?xml-stylesheet?> processing instruction
before the first element start tag; this processing instruction must have a pseudo-attribute <b>href</b> that
identifies the relative or absolute URL of the stylesheet document, and a pseudo-attribute type whose
value is "text/xml", "application/xml", or "text/xsl". For example:
<p><strong><font color="#FF0080"><?xml-stylesheet type="text/xsl" href="../style3.xsl" ?>
</font></strong></p>
<p>It is also possible to refer to a stylesheet embedded within the source document, provided
it has an id attribute and the id attribute is declared in the DTD as being of type ID. For example:
<p><strong><font color="#FF0080"><xmp>
<?xml-stylesheet type="text/xsl" href="#style1" ?>
<!DOCTYPE BOOKLIST SYSTEM "books.dtd"
<!ATTLIST xsl:transform id ID #IMPLIED>
>
<BOOKLIST>
...
<xsl:transform id="style1" version="1.0" xmlns:xsl="...">
...
</xsl:transform>
</BOOKLIST></xmp>
</font></strong></p>
</font>
<h3><a name="choosingmodel">Choosing a tree model</a></h3>
<p>Saxon provides two implementations of the internal tree data structure (or tree model).
The tree model can be chosen by an option on the command line (-dt for the tiny tree, -ds
for the standard tree) or from the Java API. The default is to use the tiny tree model.
The choice should make no difference to the results of a transformation (except the order
of attributes and namespace declarations) but only affects performance.</p>
<p>Generally speaking, the tiny tree model is faster to build but slower to navigate. It
therefore performs better when you visit each node on the tree once or less. The standard
tree model may perform better (in rare cases, much better) when each node is visited many
times, especially when you use the preceding or preceding-sibling axis.</p>
<p>The tiny tree model gives most benefit when you are processing a large document. It uses
a lot less memory, so it can prevent thrashing when the size of document
is such that the standard tree doesn't fit in real memory.</p>
<p>Choose the default tree model <code>-dt</code> unless your performance tests show that the
transformation runs faster with <code>-ds</code>. (Use the <code>-t</code> option to display
execution times.)
<hr>
<font FACE="Arial, Helvetica, sans-serif">
<h2><a name="Embedding">Embedding Saxon in an Application</a></h2>
</font>
<p>Rather than using the XSLT processor from the command line, you may want to include it in your
own application, perhaps one that enables it to be used within a servlet. If you run
the processor repeatedly, this will always be much faster than running it each time from
a command line. This is especially true if you use the same stylesheet repeatedly to transform
different source documents.</p>
<p>Saxon incorporates support for the
JAXP API (also known as TrAX). This is a standard API for invoking XSLT processors. Since JDK 1.4 it is included
as a standard part of the JDK. Saxon 6.5.4 includes its own copy of the JAXP classes and interfaces
in <code>saxon-xml-apis.jar</code>,
so that it can be used with earlier JDK releases.</p>
<p>This API is described in the javadoc documentation included with the Saxon download.
Look for the <code>javax.xml.transform</code> package. The documentation in JDK 1.4 is
an improved version of this.</p>
<p>More information and examples relating to the JAXP API can be found in the
example application found in the samples directory.</p>
<!--<hr>
<font FACE="Arial, Helvetica, sans-serif">
<h2><a name="Applet">Running Saxon from an Applet</a></h2>
</font>
<p>It is possible to run Saxon from an applet in the browser. This means that
the transformation will run on the client machine, which saves resources on the
server. It also means that it is possible for the user to navigate around the
downloaded XML document, performing repeated transformations to see different pages
of data, without ever returning to the server: this too reduces load on the server,
as well as giving the user an improved response time once the XML data and the
supporting Saxon software (saxon.jar is 550Kb) have been downloaded.</p>
<p>To support transformations running in an applet, Saxon includes a support routine
com.icl.saxonXSLTProcessorApplet.class which can be used to drive the transformation.
This rountine is in fact borrowed from the class of the same name included in the Xalan-Java 2.0.0
product. It drives the transformation using TrAX interfaces, which means that the code
works equally well with either product.</p>
<p>To use this routine, you first need to include an applet in your HTML page. This might
take the form:</p>
<code><xmp>
<applet
name="xslControl"
code="com.icl.saxon.XSLTProcessorApplet.class"
archive="../../saxon.jar"
height="0"
width"0">
<param name="documentURL" value="source.xml"/>
<param name="styleURL" value="style.xsl"/>
</applet>
</xmp></code>
<p>To run a transformation, all you have to do is to call the getHTMLText() method provided
by the applet, for example</p>
<code><xmp>
<body onLoad="target.innerHTML=document.xslControl.getHTMLText()">
<div id="target"></div>
</body>
</xmp></code>
<p>You can specify the source document and stylesheet dynamically using the methods
<b>xslControl.setDocumentURL(string)</b> or <b>xslControl.setStyleURL(string)</b>. If you don't specify
a stylesheet, Saxon will try to locate one using the <b><?xml-stylesheet?></b> processing
instruction in the source document.</p>
<p>You can set parameters for the transformation (a single parameter only, unfortunately)
by calling <b>xslControl.setStylesheetParam("name", "value")</b>.</p>
<p>There are some <a href="samples.html#applet">sample applications</a> using Saxon as an applet in
the samples/applet folder.</p> -->
<p align="center">Michael H. Kay<br>
<a href="http://www.saxonica.com/">Saxonica Limited</a><br>
22 June 2005</p>
</body>
</html>
|