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
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
|
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<!--<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"/var/projects/xhtml/xhtml1-transitional.dtd">-->
<html>
<head>
<!-- $Id: index.html,v 1.7.2.2 2002/05/07 15:11:54 bill Exp $ -->
<title>XT</title>
</head>
<body>
<h1>XT</h1>
<h2>Version 20020426a</h2>
<p>Copyright (c) 2002 Bill Lindsey, with substantial portions
Copyright (c) 1998, 1999 James Clark</p>
<p>See the files <a href="copying.txt">copying.txt</a> and
<a href="copyingjc.txt">copyingjc.txt</a> for copying
permission.</p>
<p>XT is an implementation of
<a href="http://www.w3.org/TR/xslt">XSLT 1.0</a>.
This release is a minor reworking of the code of
<a href="http://www.jclark.com/xml/xt-old.html">XT Version 19991105</a>.</p>
<p>This is a beta release. Any bugs are most likely the
fault of Bill Lindsey, and should be reported to
<a href="mailto:bill@blnz.com">bill@blnz.com</a></p>
<h3><a name="changes">Changes from the previous release</a></h3>
<ul>
<li>support for "keys" element and function</li>
<li>support for "node()" node type test in match patterns</li>
<li>lots more comments in the code</li>
</ul>
<p>XT also has a new home
at <a href="http://www.blnz.com/xt">http://www.blnz.com/xt</a></p>
<p>As was the case with the earlier release, this version has support
for the following:</p>
<ul>
<li>an <a href="#node-set"><code>xt:node-set</code></a> extension
function that converts a result tree fragment to a node-set</li>
<li>an <a href="#intersection"><code>xt:intersection</code></a> extension
function that returns the intersection of two node-sets</li>
<li>an <a href="#difference"><code>xt:difference</code></a> extension
function that returns the difference of two node-sets</li>
<li>a simple, purely DOM API</li>
</ul>
<p>To use XT, you need:</p>
<ul>
<li><a href="http://www.blnz.com/xt/index.html">the XT distribution</a></li>
<li>an XML parser in Java that
supports <a href="http://www.saxproject.org/">SAX 1 API</a>, such
as <a href="http://www.jclark.com/xml/xp/index.html">XP</a> (which is,
for your convenience, included in the distribution); you should
choose a SAX parser that provides <code>Locator</code> information,
otherwise you won't get any line numbers in error messages</li>
</ul>
<p>Put <code>XT.jar</code> in your <code>CLASSPATH</code>, together
with whatever is needed for your XML parser and with
<code>xml-apis.jar</code>
if the SAX API definitions aren't included with your XML parser. Then use the
command:</p>
<pre>java -Dcom.jclark.xsl.sax.parser=<var>your-sax-driver</var> com.jclark.sax.Driver <var>source</var> <var>stylesheet</var> [<var>result</var>] [<var>name</var>=<var>value</var>][...]
</pre>
<p>The <code><var>name</var>=<var>value</var></code> arguments are
optional and specify parameter names and values; they can occur in any
order with respect to the other arguments. They will be ignored
unless the stylesheet contains a corresponding top-level
<code>xsl:param</code> element. The value of the parameter will be of
type string.</p>
<p>To find a SAX parser, XT first uses the value of the system
property <code>com.jclark.xsl.sax.parser</code>; if this is not set it
uses the value of the system property <code>org.xml.sax.parser</code>;
if this is not set it uses the class
<code>com.jclark.xml.sax.CommentDriver</code></p>
<h2>XT API</h2>
<p>Javadocs of the APIs and implementing classes can be found at:
<a href="doc/api/index.html">doc/api/index.html</a></p>
<h2>Limitations</h2>
<p>This release of XT inherits most of the limitations of its predecessor.
The following features of the XSLT 1.0 recommendation are not
yet implemented:</p>
<ul>
<li>the element extension mechanism (the
<code>extension-element-prefixes</code> and
<code>xsl:extension-element-prefixes</code> attributes, the
<code>xsl:fallback</code> element
</li>
<li>the <code>xsl:decimal-format</code> element and the optional third
argument on the <code>format-number()</code> function</li>
<li>the <code>namespace</code> axis</li>
<li>forwards-compatible processing</li>
<li>the <code>xsl:exclude-result-prefixes</code> attribute on literal
result elements (the <code>exclude-result-prefixes</code> attribute
on <code>xsl:stylesheet</code> <em>is</em> implemented)</li>
</ul>
<p>There are also some known bugs, notably:</p>
<ul>
<li>Many errors that the XSLT specification requires to be reported
are silently ignored.</li>
<li>Comments and processing instructions occurring in the DTD are not
excluded from the data model.</li>
<li>The <code>document()</code> function does not pay attention to the
HTTP <code>content-type</code> header.</li>
<li>The <code>xsl:import</code> element does not conform to the
requirement that when <code>xsl:include</code> is used to include a
stylesheet, any <code>xsl:import</code> elements in the included
document are moved up in the including document to after any existing
<code>xsl:import</code> elements in the including document.</li>
<li>The HTML output method may get confused if you embed
namespace-qualfied XML elements with the HTML.</li>
</ul>
<p>Apart from missing features and bugs, the implementation is in need
of improvement in several areas, including:</p>
<ul>
<li>The <code>xml</code> output method ignores the
<code>encoding</code> and <code>cdata-section-elements</code>
attributes on <code>xsl:output</code>.</li>
<li>Error reporting is often not as helpful as it might be.</li>
<li>No error recovery is attempted after an error is reported.</li>
<li>The <code>document()</code> function does not support fragment
identifiers in URIs for any media types.</li>
<li>No support yet for TrAX and SAX 2 APIs.</li>
<li>No support yet for <a href="http://www.exslt.org">EXSLT</a>
common extensions.</li>
</ul>
<h2><a name="extension">Extension Functions</a></h2>
<p>A call to a function <code><var>ns</var>:<var>foo</var></code>
where <code><var>ns</var></code> is bound to a namespace of the form
<code>http://www.jclark.com/xt/java/<var>className</var></code> is
treated as a call of the static method <code><var>foo</var></code> of
the class with fully-qualified name
<code><var>className</var></code>. Hyphens in method names are removed
with the character following the hyphen being upper-cased.
Overloading based on number of parameters is supported; overloading
based on parameter types is not. A non-static method is treated like
a static method with the <code>this</code> object as an additional
first argument. A constructor is treated like a static method named
<code>new</code>. Extension functions can return objects of arbitrary
types which can then be passed as arguments to other extension
functions or stored in variables.</p>
<p>For example, the following</p>
<pre><xsl:stylesheet
version="1.0"
xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
xmlns:date="http://www.jclark.com/xt/java/java.util.Date">
<xsl:template match="/">
<html>
<xsl:if test="function-available('date:to-string') and function-available('date:new')">
<p><xsl:value-of select="date:to-string(date:new())"/></p>
</xsl:if>
</html>
</xsl:template>
</xsl:stylesheet></pre>
<p>will print out the current date.</p>
<p>Types are mapped between XSLT and Java as follows:</p>
<table border="1">
<tr><th>XSLT type</th><th align="left">Java type</th></tr>
<tr><td>string</td><td><code>java.lang.String</code></td></tr>
<tr><td>number</td><td><code>double</code></td></tr>
<tr><td>boolean</td><td><code>boolean</code></td></tr>
<tr><td>node-set</td><td><code>com.jclark.xsl.om.NodeIterator</code></td></tr>
<tr><td>result tree fragment</td>
<td><code>com.jclark.xsl.sax.ResultTreeFragment</code></td></tr>
</table>
<p>On return from an extension function, an object of type
<code>com.jclark.xsl.om.Node</code> is also allowed and will be
treated as a node-set; also any numeric type is allowed and will be
converted to a number.</p>
<p>The <code>demo</code> directory has an examples.</p>
<h2><a name="multiple-output">Multiple Output Documents</a></h2>
<p>XT supports an extension element
<code><var>xt</var>:document</code> for creating output documents in
addition to the main output document. The prefix
<code><var>xt</var></code> must be bound to the namespace URI
<code>http://www.jclark.com/xt</code>.</p>
<p>XT does not yet properly implement the element extension mechanism,
and will recognize the namespace URI
<code>http://www.jclark.com/xt</code> as an extension namespace
regardless of whether it has been declared using an
<code>extension-element-prefixes</code> or
<code>xsl:extension-element-prefixes</code>. You should not rely on
this and should declare the namespace
<code>http://www.jclark.com/xt</code> as an extension namespace in
accordance with the XSLT WD. For example,</p>
<pre><xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
xmlns:xt="http://www.jclark.com/xt"
extension-element-prefixes="xt">
...
</xsl:stylesheet></pre>
<p>The <code><var>xt</var>:document</code> element has a required
<code>href</code> attribute, which must be a relative URL. The value
of the <code>href</code> attribute is interpreted as an attribute
value template. The content of the
<code><var>xt</var>:document</code> element is a template for the
result tree to be stored in the location specified by the
<code>href</code> attribute. The base URL for resolving the
<code>href</code> relative URL is the URL of the parent output
document: either the URL of the main output document or the URL in
which the parent <code><var>xt</var>:document</code> element was
stored. Thus, the same relative URL specifed by the <code>href</code>
attribute can be used in the parent document to reference the document
created by the <code><var>xt</var>:document</code> element.</p>
<p>The <code><var>xt</var>:document</code> element can also have all
the same attributes as the <code>xsl:output</code> element. These
attributes are merged with attributes specified on top-level
<code>xsl:output</code> elements to determine the output method for
this document. The attributes on the
<code><var>xt</var>:document</code> element take precedence over the
attributes specified on top-level <code>xsl:output</code>
elements.</p>
<p>For example,</p>
<pre><xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
xmlns:xt="http://www.jclark.com/xt"
extension-element-prefixes="xt">
<xsl:variable name="file">out</xsl:variable>
<xsl:template match="/">
<xt:document method="xml" href="{$file}.xml">
<xsl:call-template name="out"/>
</xt:document>
<xt:document method="html" href="{$file}.html">
<xsl:call-template name="out"/>
</xt:document>
<xt:document method="text" href="{$file}.txt">
<xsl:call-template name="out"/>
</xt:document>
</xsl:template>
<xsl:template name="out">
<html>
<head><title>Title</title></head>
<body>
<p>Line 1<br/>Line 2</p>
</body>
</html>
</xsl:template>
</xsl:stylesheet></pre>
<p>The <code>demo</code> directory has a couple more examples.</p>
<h2><a name="nonxml">Non-XML output</a></h2>
<p>XT supports an additional output method of
<code><var>xt</var>:nxml</code> where the prefix
<code><var>xt</var></code> is bound to the namespace URI
<code>http://www.jclark.com/xt</code>. This produces non-XML output
from a result document that conforms to the following DTD:</p>
<pre><!ELEMENT nxml (escape*, (control|data)*)>
<!ELEMENT escape (#PCDATA|char)*>
<!ATTLIST escape char CDATA #REQUIRED>
<!ELEMENT control (#PCDATA|char|data|control)*>
<!ELEMENT data (#PCDATA|data|control)*>
<!ELEMENT char EMPTY>
<!ATTLIST char number NMTOKEN #REQUIRED></pre>
<p>The <code>data</code> element contains data. Within a
<code>data</code> element control characters get escaped. The
<code>escape</code> element specifies how a particular control
character gets escaped.</p>
<p>The <code>control</code> element contains control information.
Within a <code>control</code> element, all characters are output
directly without escaping.</p>
<p>The <code>char</code> element allows the output of a character that
is not allowed by XML (such as control-L).</p>
<p>For example, the following stylesheet</p>
<pre><xsl:stylesheet
xmlns:xsl="http://www.w3.org/1999/XSL/Transform">
<xsl:output method="xt:nxml" xmlns:xt="http://www.jclark.com/xt"/>
<xsl:template match="/">
<nxml>
<escape char="\">\\</escape>
<data>&amp;&lt;&gt;\</data>
<control>&amp;&lt;&gt;\</control>
</nxml>
</xsl:template>
</xsl:stylesheet></pre>
<p>will output</p>
<pre>&<>\\&<>\</pre>
<p>The <code>encoding</code> attribute on <code>xsl:output</code>
applies to the <code>xt:nxml</code> output method.</p>
<p>A result method can also have the form
<code><var>java</var>:<var>class</var></code> where
<code><var>java</var></code> is bound to the namespace URI
<code>http://www.jclark.com/xt/java</code> and <code>class</code> is
the name of a Java class that implements the
<code>com.jclark.xsl.sax.OutputDocumentHandler</code> interface (which
extends <code>org.xml.sax.DocumentHandler</code>). For example,</p>
<pre>
<xsl:output method="java:com.jclark.xsl.sax.NXMLOutputHandler"
xmlns:java="http://www.jclark.com/xt/java"/>
</pre>
<p>is equivalent to</p>
<pre>
<xsl:output method="xt:nxml" xmlns:xt="http://www.jclark.com/xt"/>
</pre>
<h2>Built-in Extension Functions</h2>
<p>XT provides the following built-in extension functions. The
namespace URI for these is <code>http://www.jclark.com/xt</code>.</p>
<dl>
<dt><a name="node-set"></a><code>xt:node-set</code></dt>
<dd>Converts a result tree fragment to the equivalent node-set. The
argument must be a node-set or a result tree fragment; the result will
be a node-set. See the <code>sort-uniq</code> example in the
<code>demo</code> directory.</dd>
<dt><a name="intersection"></a><code>xt:intersection</code></dt>
<dd>Returns the intersection of two node-sets.</dd>
<dt><a name="difference"></a><code>xt:difference</code></dt>
<dd>Returns the difference of two node-sets (the nodes in the first
node-set that are not in the second node-set).</dd>
</dl>
<h2><a name="bug">Reporting Bugs</a></h2>
<p>Please report bugs to me, Bill Lindsey. When reporting bugs please be
sure to include both a complete stylesheet and complete source
document that illustrate the bug.</p>
<address>
<a href="mailto:bill@blnz.com">Bill Lindsey</a>
</address>
</body>
</html>
|
