<?xml version="1.0" encoding="ISO-8859-1"?>
<html>
  <head>
    <title>expr.README</title>
  </head>

  <body>
    <h1>Why is this document named expr.README?</h1>

    <p>Package <tt>com.jclark.xsl.expr</tt> contains the implementation of
    XPath 1.0 used by XT, James Clark's XSLT engine. XMLmind XML Editor uses a
    modified version of this package (renamed
    <tt>com.xmlmind.xmledit.xpath</tt> for easier integration in the
    editor).</p>

    <p>What follows is James Clark's original <tt>xt-old.html</tt>.</p>

    <hr />

    <h1>XT</h1>

    <h2>Version 19991105</h2>

    <p>Copyright (c) 1998, 1999 James Clark</p>

    <p>See the file <a
    href="http://www.jclark.com/xml/copying.txt">copying.txt</a> for copying
    permission.</p>

    <p>XT is an implementation in Java of <a
    href="http://www.w3.org/TR/1999/PR-xslt-19991008">XSL Transformations</a>.
    This version of XT implements the PR-xslt-19991008 version of XSLT.
    Stylesheets written for earlier versions of the XSLT WD must be converted
    before they can be used with this version of XT.</p>

    <p>This should be considered a beta release.</p>

    <h2><a name="changes">Changes from Previous Releases</a></h2>

    <h3>Changes in this release</h3>

    <p>This release of XT adds 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 <a href="#DOM">API</a></li>
    </ul>

    <h3>Changes in version 19991102</h3>

    <p>This release of XT adds support for the following:</p>

    <ul>
      <li><code>doctype-system</code>, <code>doctype-public</code>,
      <code>omit-xml-declaration</code> and <code>standalone</code> attributes
      on <code>xsl:output</code></li>

      <li>the <code>preceding</code> axis</li>

      <li><code>xsl:message</code></li>

      <li><a href="#DOM">DOM Level 1</a></li>
    </ul>

    <h2><a name="usage">Usage</a></h2>

    <p>To use XT, you need:</p>

    <ul>
      <li><a href="ftp://ftp.jclark.com/pub/xml/xt.zip">the XT
      distribution</a></li>

      <li>an XML parser in Java that supports <a
      href="http://www.megginson.com/SAX/">SAX</a>, such as <a
      href="http://www.jclark.com/xml/xp/index.html">XP</a>; 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 <code>sax.jar</code> if that
    isn'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.xsl.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>
    (This subclasses the normal XP SAX driver to provide support for comments;
    it is present only in XP version 0.5 or later; if you have an earlier
    version of XP use
    <code>-Dcom.jclark.xsl.sax.parser=com.jclark.xml.sax.Driver</code>
    instead.)</p>

    <p>Alternatively under Windows you can use <a
    href="ftp://ftp.jclark.com/pub/xml/xt-win32.zip">XT packaged as a Win32
    executable</a>. This includes XP and SAX. To use this, you will need to
    have the <a href="http://www.microsoft.com/java/vm/dl_vm32.htm">Microsoft
    Java VM</a> installed (this is included with IE). Run this with the
    command:</p>

    <pre>xt <var>source</var> <var>stylesheet</var> <var>result</var> <var>name</var>=<var>value</var>...
</pre>

    <h2><a name="servlet">Servlet Usage</a></h2>

    <p>XT can be used as a servlet. This requires a servlet engine that
    implements at least version 2.1 of the Java Servlet API. The servlet class
    is <code>com.jclark.xsl.sax.XSLServlet</code>. The servlet requires an
    init parameter <code>stylesheet</code>; the value is the path of the
    stylesheet in a form suitable to be passed to
    <code>ServletContext.getResource</code>. The translated path gives the XML
    document to be transformed. An extension of <code>.xml</code> will be
    automatically added to the translated path if necessary. (Some browsers
    assume that a URL ending in <code>.xml</code> is an XML document.)
    Parameters from the query part of the URL are passed in as parameters to
    the stylesheet. The stylesheet is cached on initialization.</p>

    <h2>XT API</h2>

    <p>The public interface to XT is
    <code>com.jclark.xsl.sax.XSLProcessor</code> which is implemented by
    <code>com.jclark.xsl.sax.XSLProcessorImpl</code>. This interface is based
    on SAX.</p>

    <p><a name="DOM"></a>There is also a simple API based purely on the DOM.
    This is <code>com.jclark.xsl.dom.TransformEngine</code>, which is
    implemented by <code>com.jclark.xsl.dom.XSLTransformEngine</code>. This is
    significantly less functional and much slower than the SAX API. The file
    <code>DOMDemo.java</code> in the <code>demo</code> directory is a demo of
    this.</p>

    <p>It is also possible to mix SAX and the DOM, using the DOM for input and
    SAX for output; this requires that a class be created that extends
    <code>com.jclark.xsl.dom.XMLProcessorImpl</code> and implements at least
    the <code>load</code> method. The class
    <code>com.jclark.xsl.dom.SunXMLProcessorImpl</code> does this for Sun's
    DOM implementation (in Project X TR2). An object of the class extending
    <code>com.jclark.xsl.dom.XMLProcessorImpl</code> can be passed to the
    <code>setParser(XMLProcessorEx)</code> method of
    <code>com.jclark.xsl.sax.XSLProcessorImpl</code>. XT will be much slower
    when using the DOM than when using SAX directly, so you should not use
    this unless you already have a DOM tree as a result of some other
    processing. For testing purposes, you can use a class extending
    <code>com.jclark.xsl.dom.XMLProcessorImpl</code> with
    <code>com.jclark.xsl.sax.Driver</code> by specifying the name of the class
    as the value of the <code>com.jclark.xsl.sax.parser</code> system
    property.</p>

    <h2>Limitations</h2>

    <p>The following features of the XSLT PR 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, and the
      <code>element-available</code> function)</li>

      <li>keys (the <code>xsl:key</code> element, and the <code>key()</code>
      function)</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>node()</code> node-test does not work in match patterns
      (it does work in expressions).</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 implementation of the <code>xsl:number</code> element is
      slow.</li>

      <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>
    </ul>

    <p>Not much effort has yet been devoted to optimizing performance.</p>

    <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>&lt;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"&gt;

&lt;xsl:template match="/"&gt;
  &lt;html&gt;
    &lt;xsl:if test="function-available('date:to-string') and function-available('date:new')"&gt;
      &lt;p&gt;&lt;xsl:value-of select="date:to-string(date:new())"/&gt;&lt;/p&gt;
    &lt;/xsl:if&gt;
  &lt;/html&gt;
&lt;/xsl:template&gt;

&lt;/xsl:stylesheet&gt;</pre>

    <p>will print out the current date.</p>

    <p>Types are mapped between XSLT and Java as follows:</p>

    <table border="1">
      <tbody>
        <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>
      </tbody>
    </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>&lt;xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
                xmlns:xt="http://www.jclark.com/xt"
                extension-element-prefixes="xt"&gt;
...
&lt;/xsl:stylesheet&gt;</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>&lt;xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
                xmlns:xt="http://www.jclark.com/xt"
                extension-element-prefixes="xt"&gt;

&lt;xsl:variable name="file"&gt;out&lt;/xsl:variable&gt;

&lt;xsl:template match="/"&gt;
  &lt;xt:document method="xml" href="{$file}.xml"&gt;
     &lt;xsl:call-template name="out"/&gt;
  &lt;/xt:document&gt;
  &lt;xt:document method="html" href="{$file}.html"&gt;
     &lt;xsl:call-template name="out"/&gt;
  &lt;/xt:document&gt;
  &lt;xt:document method="text" href="{$file}.txt"&gt;
     &lt;xsl:call-template name="out"/&gt;
  &lt;/xt:document&gt;
&lt;/xsl:template&gt;

&lt;xsl:template name="out"&gt;
  &lt;html&gt;
   &lt;head&gt;&lt;title&gt;Title&lt;/title&gt;&lt;/head&gt;
   &lt;body&gt;
   &lt;p&gt;Line 1&lt;br/&gt;Line 2&lt;/p&gt;
   &lt;/body&gt;
  &lt;/html&gt;
&lt;/xsl:template&gt;

&lt;/xsl:stylesheet&gt;</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>&lt;!ELEMENT nxml (escape*, (control|data)*)&gt;
&lt;!ELEMENT escape (#PCDATA|char)*&gt;
&lt;!ATTLIST escape char CDATA #REQUIRED&gt;
&lt;!ELEMENT control (#PCDATA|char|data|control)*&gt;
&lt;!ELEMENT data (#PCDATA|data|control)*&gt;
&lt;!ELEMENT char EMPTY&gt;
&lt;!ATTLIST char number NMTOKEN #REQUIRED&gt;</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>&lt;xsl:stylesheet
  xmlns:xsl="http://www.w3.org/1999/XSL/Transform"&gt;
&lt;xsl:output method="xt:nxml" xmlns:xt="http://www.jclark.com/xt"/&gt;
&lt;xsl:template match="/"&gt;
&lt;nxml&gt;
&lt;escape char="\"&gt;\\&lt;/escape&gt;
&lt;data&gt;&amp;amp;&amp;lt;&amp;gt;\&lt;/data&gt;
&lt;control&gt;&amp;amp;&amp;lt;&amp;gt;\&lt;/control&gt;
&lt;/nxml&gt;
&lt;/xsl:template&gt;
&lt;/xsl:stylesheet&gt;</pre>

    <p>will output</p>

    <pre>&amp;&lt;&gt;\\&amp;&lt;&gt;\</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>&lt;xsl:output method="xtj:com.jclark.xsl.sax.NXMLOutputHandler"
            xmlns:xtj="http://www.jclark.com/xt/java"/&gt;
</pre>

    <p>is equivalent to</p>

    <pre>&lt;xsl:output method="xt:nxml" xmlns:xt="http://www.jclark.com/xt"/&gt;
</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. <strong>When reporting bugs please be sure to
    include both a complete stylesheet and complete source document that
    illustrate the bug</strong>. Create a zip file containing all the
    necessary files, and attach the zip file to your email.</p>

    <address><a href="mailto:jjc@jclark.com">James Clark</a></address>
  </body>
</html>