xml-general mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From dles...@locus.apache.org
Subject cvs commit: xml-site/sources/xalan usagepatterns.xml samples.xml getstarted.xml STATUS resources.xml readme.xml overview.xml dtm.xml commandline.xml
Date Thu, 17 Feb 2000 16:48:46 GMT
dleslie     00/02/17 08:48:46

  Modified:    sources/xalan STATUS resources.xml readme.xml overview.xml
                        dtm.xml commandline.xml
  Added:       sources/xalan usagepatterns.xml samples.xml getstarted.xml
  Major revision of doc towards release 1.0. Still in rough shape
  but major restructuring in place.
  Revision  Changes    Path
  1.3       +3 -0      xml-site/sources/xalan/STATUS
  Index: STATUS
  RCS file: /home/cvs/xml-site/sources/xalan/STATUS,v
  retrieving revision 1.2
  retrieving revision 1.3
  diff -u -r1.2 -r1.3
  --- STATUS	2000/01/20 16:39:04	1.2
  +++ STATUS	2000/02/17 16:48:45	1.3
  @@ -1,3 +1,6 @@
  +<s3 title="Version of Xerces to use">
  +<p>The version of xalan.jar shipped with this release works with the xerces.jar shipped in Xerces-java version 1.0.1.</p>
   <s3 title="Things still to be done">
     <p>We still need to do the following:</p>
  1.6       +10 -7     xml-site/sources/xalan/resources.xml
  Index: resources.xml
  RCS file: /home/cvs/xml-site/sources/xalan/resources.xml,v
  retrieving revision 1.5
  retrieving revision 1.6
  diff -u -r1.5 -r1.6
  --- resources.xml	2000/01/20 16:39:04	1.5
  +++ resources.xml	2000/02/17 16:48:45	1.6
  @@ -1,6 +1,6 @@
   <?xml version="1.0" encoding="UTF-8"?>
   <!DOCTYPE resources [
  -  <!ENTITY apiResources SYSTEM "apiResources.out">
  +  <!ENTITY apiResources SYSTEM "apiResources.xml">
     <!ELEMENT resources (resource|human-resource)+>
     <!ELEMENT resource EMPTY>
     <!ATTLIST resource 		id CDATA #IMPLIED
  @@ -22,8 +22,8 @@
     <resource id="Readme" title="Xalan Repository Release Notes" location="http://www.apache.org/websrc/cvsweb.cgi/xml-xalan/README"/>
  -  <resource id="Installation" title="Installing Xalan" location="install.xml-index.html"/>
  -   <resource id="CommandLineUtility" title="Xalan Command-Line Utility" location="commandline.xml-index.html"/>
  +  <resource id="Installation" title="Installing Xalan" location="install.html"/>
  +   <resource id="CommandLineUtility" title="Xalan Command-Line Utility" location="commandline.html"/>
     <resource id="Demo" title="Xalan Browser Demo" location="http://xml.apache.org/xalan/XMLViewer.htm"/>
  @@ -47,7 +47,7 @@
     <resource id="JDK1.2" title="Sun's JDK-1.2" location="http://java.sun.com/products/jdk/1.2/"/>
     <resource id="JDK1.1" title="Sun's JDK-1.1" location="http://java.sun.com/products/jdk/1.1/"/>
     <resource id="microsoftJava" title="Microsoft's Java VM" location="http://microsoft.com/java/"/>
  -  <resource id="extensionsDoc" title="Xalan Extension Mechanism Doc" location="ltsextensions.xml-index.html"/>
  +  <resource id="extensionsDoc" title="Xalan Extension Mechanism Doc" location="ltsextensions.html"/>
     <resource id="demoPage" title="Demonstration Page" location="XMLViewer.htm"/>
     <resource id="ExamplesDir" title="'examples' directory" location="examples"/>
     <resource id="DominoExamplesDir" title="'domino' directory" location="examples/domino"/>
  @@ -63,11 +63,11 @@
     <resource id="TestWithXML4J2DOMSuiteDir" title="'testSuite\xml4j2dom' directory" location="testSuite\xml4j2dom"/>
     <resource id="TestWithXML4J2TXSuiteDir" title="'testSuite\xml4j2tx' directory" location="testSuite\xml4j2tx"/>
  -  <resource id="APIOverview" title="API Overview" location="api.xml-index.html"/>
  +  <resource id="APIOverview" title="API Overview" location="api.html"/>
   	  <resource id="APIDocumentationDir" title="'apidocs' directory" location="apidocs"/>
  -	  <resource id="Introduction" title="Overview: XSL Transformer for Java" location="overview.xml-index.html"/>
  +	  <resource id="Introduction" title="Overview: XSL Transformer for Java" location="overview.html"/>
     <resource id="APIDocumentation" title="API Documentation" location="apidocs/index.html"/>	
  -  <resource id="ReadmeDocumentation" title="Release Notes" location="readme.xml-index.html"/>
  +  <resource id="ReadmeDocumentation" title="Release Notes" location="readme.html"/>
     <resource id="readme.xml" title="XML version of the Readme file" location="../docs/readme.xml"/>
     <human-resource id="xalandev" name="Xalan Development Mailing List" mailto="xalan-dev@xml.apache.org"/>
     <human-resource id="sboag" name="Scott Boag" mailto="scott_boag@lotus.com"/>
  @@ -98,4 +98,7 @@
   <resource id="XSLTProcessorAppletsetDocumentURLDoc" title="XSLTProcessorApplet setDocumentURL() method" location="apidocs/org/apache/xalan/xslt/client/XSLTProcessorApplet.html#setDocumentURL(java.lang.String)"/>
   <resource id="XSLTProcessorAppletsetStyleURLDoc" title="XSLTProcessorApplet setStyleURL() method" location="apidocs/org/apache/xalan/xslt/client/XSLTProcessorApplet.html#setStyleURL(java.lang.String)"/>
  +<resource id="usagepatterns_fr_jindex" title="Usage Patterns" location="../usagepatterns.html"/>
  +<resource id="dtm_fr_jindex" title="DTM (Document Table Model)" location="../dtm.html"/>
  +<resource id="ext_fr_jindex_o_a_x_x_ext" title="Xalan Extensions" location="../../../../../../extensions.html"/>
  1.9       +94 -156   xml-site/sources/xalan/readme.xml
  Index: readme.xml
  RCS file: /home/cvs/xml-site/sources/xalan/readme.xml,v
  retrieving revision 1.8
  retrieving revision 1.9
  diff -u -r1.8 -r1.9
  --- readme.xml	2000/01/20 16:39:04	1.8
  +++ readme.xml	2000/02/17 16:48:45	1.9
  @@ -1,8 +1,8 @@
   <?xml version="1.0" standalone="no"?>
   <!DOCTYPE s1 SYSTEM "sbk:/style/dtd/document.dtd"[
  -<!ENTITY done-j SYSTEM "sbk:/sources/xalan/DONE">
  -<!ENTITY status-j SYSTEM "sbk:/sources/xalan/STATUS">
  -<!ENTITY bugs-j SYSTEM "sbk:/sources/xalan/BUGS">]>
  +<!ENTITY done-j SYSTEM "DONE">
  +<!ENTITY status-j SYSTEM "STATUS">
  +<!ENTITY bugs-j SYSTEM "BUGS">]>
    * The Apache Software License, Version 1.1
  @@ -61,158 +61,96 @@
    * <http://www.apache.org/>.
   <s1 title="Release Notes">
  -  <s2 title="Disclaimer">
  -    <p>In its current form, &xslt4j; is a Developer Preview, not a product.
  -    It implements a draft standard that is still in design.  APIs will continue to change, 
  -    with no promise of backwards compatibility.  This software contains known and unknown bugs.  
  -    We recommend against using this software for mission critical applications.  
  -    The Apache Software Foundation will not take responsibility for any problems that may ensue
  -    from using this software.</p>
  - 		<p>For a general overview of &xslt4j;, see <resource-ref idref="Introduction"/>. For information about the &xslt4j;
  -     API, see <resource-ref idref="APIOverview"/> and <resource-ref idref="APIDocumentation"/>.</p>    
  -		<p>For the Apacke Software License, see <resource-ref idref="ApacheLicense"/>.</p> 
  -	</s2>
  -	 <s2 title="Performance Notes"> 
  -		<p>We have done a great deal in versions 0.18 and 0.19 to improve performance. However, as these things often go, we
  -    have not yet met our goal for a 10-fold performance increase. We provide his list of what we understand the bottlenecks
  -    to be so that you may understand and, in some cases, work around them. The bottlenecks appear
  -    to be:</p> 
  -		<gloss> 
  -		  <label>Class load and JIT (Just In Time compiler)</label> 
  -		  <item>As we've added architecture to improve raw transform performance, we've 
  -		        also increased the number of classes and class instances that need loading, and 
  -		        the amount of code that needs JIT compiling.  Although we can shrink the code size 
  -		        a bit, the time required to load the processor will continue to be an issue.  The 
  -		        one thing the caller of the API can do is pre-warm the JIT by transforming 
  -		        a dummy document. For an example of this technique, see the init() method in the 
  -		        <link idref="XSLTProcessorAppletDoc"/>. During applet initialization, a dummy document
  -             is transformed, so the response time for performing "real" 
  -            transformations will be reasonable.<br/><br/></item> 
  -		   <label>Stylesheet Compilation</label>
  -		   <item>&xslt4j; now reads the stylesheet from the parser's SAX events (unless you 
  -		         give it a DOM, in which case it produces SAX events from the DOM), and builds
  -		         an internal tree structure. This structure processes the attributes, precompiles 
  -		         the XPath expressions, and does other things that can be done before it knows
  -		         about the input tree. The construction of large stylesheets is not as fast as 
  -		         we would like. We have been focusing on the transformation itself, and will 
  -		         have to concentrate on optimizing the stylesheet compilation down the road a bit.
  -		        <br/><br/></item>
  -		   <label>The DOM</label>
  -		   <item>DOM nodes are big.  Every node, including attribute nodes and whitespace nodes, 
  -		        have a next, previous, parent, first child, last child, ownerDocument, name, value, userData,
  -		        and a few internal flags. So building the input DOM can take a lot of memory 
  -		        management. We are working on ways to get around this when &xslt4j; builds 
  -		        the input tree, while still maintaining our DOM input architecture.<br/><br/></item>
  -		   <label>Union Sorting in Document Order</label>
  -		   <item>XSLT has to return nodes in document order. Determining document order from 
  -		         a pure DOM is difficult. We have developed a method to determine the order
  -		         that is pretty good, but it is not as fast as simply determining document order 
  -		         based on a integer.  Also, the collation method of combining two node lists 
  -		         is not as effecient as it needs to be, simply because we haven't had time to 
  -		         address it yet (the issues are more complex than was first apparent).  The net 
  -		         of this is that union expressions aren't scalable to large node sets.  For instance,
  -		         we have one user who has a large document with 3800 elements right under the 
  -		         root node, and they apply a standard 
  -		         select="*|@*|comment()|processing-instruction()|text()" expression to these 
  -		         nodes. The 3800 elements happen to have 3800 whitespace nodes interleafed 
  -		         between them, and the union selection has to create a nodelist of 3800 elements 
  -		         and 3800 whitespace nodes, and combine them, testing for document order as 
  -		         it goes.  As a result, the processing takes forever.  We're working on ways 
  -		         to fix this, but, the answer for this user was to not do the union selection 
  -		         at the top level (they didn't care about the whitespace nodes anyway).
  -		        <br/><br/></item>
  -		     <label>Selects in Large Documents</label>
  -		     <item>&xslt4j; currently builds no inverted indexes for the input document, and 
  -		           does not take advantage of DTD structures to optimize, and otherwise does 
  -		           no special magic to locate nodes other than try to implement efficient 
  -		           algorithms.  While inverted indexes and taking advantage of DTD structures 
  -		           are on our list for options, users should be aware that patterns such as 
  -		           '//foo' at the top of the tree can be expensive.
  -		        <br/><br/></item>
  -		     <label>xsl:number and xsl:sort</label>
  -		     <item>Both sorting and numbering are not as efficient as they could be.
  -		     <br/><br/></item>
  -    	</gloss>
  -	 </s2> 
  -	 <s2 title="API"> 
  -		<p>Please see the <resource-ref idref="APIOverview"/> for
  -		  information about the &xslt4j; Application Programmer's Interface and the 
  -		  source code.</p> 
  -		<p>The <resource-ref idref="APIDocumentation"/> is in the <resource-ref idref="APIDocumentationDir"/>.</p> 
  -	 </s2> 
  -	 <s2 title="Tips">
  -      <ul>
  -   		     <li>&xslt4j; is thread-safe with an instance per thread.  You can not run 
  -           the same instance in multiple threads.</li>
  -		       <li>&xslt4j; contains a DTD for XSL when used for HTML. (Thanks be to
  -           Henrique M. Holschuh for this). This DTD should not be used for run-time
  -           production when performance is a concern, but is useful during the development
  -           stages. It is used in the readme XSL.<br/><br/></li> 
  -        <li>
  -        The rule for whitespace that can be stripped is as follows:<br/>
  -        If a text node contains whitespace followed by a non-whitespace 
  -        character followed by whitespace, none of the whitespace is ever 
  -        stripped.  If a text node is all whitespace, and does not have 
  -        siblings that are character data, it should be stripped.  A 
  -        CDATA section is interpreted as character data.<br/><br/>
  -        </li>
  -        <li>
  -        Be aware that select arguments for variables, or arguments passed through the 
  -        command line via the -PARAM switch, are expressions, not strings.  So to set 
  -        a variable to a string you need to do:<br/>
  -        <code>
  -        <![CDATA[<xsl:variable name="ExpressionTest" 
  -                               select="'A test for xsl:constant and xsl:value-of'"/>]]>
  -        </code><br/>
  -        Notice the extra single quotes (').<br/><br/>
  -        </li>
  -        <li>
  -        If you're using an XSL stylesheet with a DTD, attributes typed as IDs will 
  -        have a problem when you try and put an attribute template into them.  Just 
  -        something to watch out for.  We don't really have a solution for this, 
  -        except that you probably can't type literal result element attributes as 
  -        IDs for the XSL stylesheet.<br/><br/>
  -        </li>
  -      </ul>
  -    </s2>
  -		  <s2 title="Redirect Extension (Multiple Output Docs)"> 
  -      <p>&xslt4j; has a built in extension to let you produce multiple output documents 
  -      from a single stylesheet.  The extension is limited right now to producing 
  -      files, when the output method is "xml", "html", or "text". See <resource-ref
  -      idref="RedirectDoc"/> for details.</p>
  -    </s2> 
  -	 <s2 title="Version Notes">
  -     &done-j;
  + <ul>
  +  <li><link anchor="status">Status</link></li>
  +  <li><link anchor="build">Build Notes</link></li>
  +  <li><link anchor="contact">Getting in touch</link></li>
  + </ul>
  +  <s2 title="Status">
  +   <ul>
  +    <li><link anchor="status">Version of &xml4j; to use</link></li>
  +    <li><link anchor="done">Bug fixes</link></li>
  +    <li><link anchor="bugs">Outstanding bugs</link></li>
  +   </ul>
  +     <anchor name="status"/>
  +     <anchor name="done"/>
  +     &done-j;
  +     <anchor name="bugs"/>
  -   </s2>
  -	 <s2 title="Contact Info and Bug Reports"> 
  -          <p>Contact information for &xslt4j;: <human-resource-ref idref="xalandev"/></p>
  -	 </s2> 
  -	 <s2 title="Glossary"> 
  -		<gloss> 
  -		  <label>XSL Instruction</label> 
  -		  <item>Any tag with an XSL namespace prefix.<br/><br/></item> 
  -		  <label>XSL Template Instruction</label> 
  -		  <item>Any tag with an XSL namespace prefix that occurs inside an
  -			 xsl:template element.<br/><br/></item> 
  -		  <label>Template Child</label> 
  -		  <item>Any node that is a child of an xsl:template element.<br/><br/></item> 
  -		  <label>Source Tree</label> 
  -		  <item>The tree input to the XSL process.<br/><br/></item> 
  -		  <label>Result Tree</label> 
  -		  <item>The tree that is output by the XSL process.<br/><br/></item> 
  -		  <label>Stylesheet Tree</label> 
  -		  <item>The stylesheet tree produced from the XSL file.<br/><br/></item> 
  -		  <label>Pattern List</label> 
  -		  <item>A parsed query or match pattern.<br/><br/></item> 
  -		</gloss> 
  -	 </s2> 
  +  </s2>
  +  <anchor name="build"/>
  +  <s2 title="Build Notes">
  +<li><link anchor="jar">Rebuilding xalan.jar</link></li>
  +<li><link anchor="samples">Rebuilding sample applications</link></li>
  +<li><link anchor="doc">Rebuilding the &xslt4j; documentation</link></li>
  +<anchor name="jar"/> 
  +   <s3 title="Rebuilding &xslt4j;">
  +     <p>The &xslt4j; build is in xalan.jar. The &xslt4j; source code tree is in the src directory.
  +     If you want to rebuild xalan.jar, you can do the following:</p>
  +     <ol>
  +       <li>Set up GNU or the equivalent build environment on your workstation.<br/><br/>
  +       If you are running Windows 95/98/NT, you can use the Cygwin port of GNU. Be sure to put the
  +       appropriate Cygwin bin directory at the beginning of your system path. For information about
  +       Cygwin, see <jump href="http://www.sourceware.cygnus.com/cygwin/">Cygwin</jump>.<br/><br/></li>
  +       <li>Place <resource-ref idref="xerces-used"/> xerces.jar in the Java classpath.<br/><br/></li>
  +       <li>If you are working in Windows, set MAKE_MODE as follows:<br/><br/>
  +       <code>set MAKE_MODE=UNIX</code><br/><br/></li>
  +       <li>Run the make file in the &xslt4j; root directory:<br/><br/>
  +       <code>make build</code><br/><br/></li>
  +     </ol>
  +     <p>If you want to do the build without the GNU build environment, keep the following in mind:</p>
  +     <ul>
  +     <li>Set the class path to include the src directory, xerces.jar, bsf.jar, and bsfengines.jar.</li>
  +     <li>Use javac to compile all the .java files in the src tree. </li>
  +     <li>Use the Sun jar utility to store the resulting .class files in xalan.jar</li>
  +     </ul>
  +   </s3><anchor name="samples"/>
  +   <s3 title="Rebuilding a sample application">
  +   <p>If you modify a sample and want to recompile it, you can run javac in the directory containing the
  +   example. Be sure xalan.jar and xerces.jar are on the class path. To recompile (and run!) the class files in the
  +   Servlet subdirectory, the javax.servlet and javax.servlet.http packages must also be on the class path. Sun
  +   distributes these packages in the JSWDK 1.0.1 servlet.jar file.</p> 
  +   <p>After recompiling a sample, you can use the Sun jar utility to place your  new .class files in
  +    xalansamples.jar.</p>
  +   </s3><anchor name="doc"/>
  +   <s3 title="Rebuilding the &xslt4j; documentation">
  +     <p>&xslt4j; includes a number of XML source files, XSL stylesheets, document type definition (DTD)
  +      files, entity relationship (ENT) files, graphics, and a JavaScript file that provide the input for the Xalan
  +      HTML User's Guide, and the overview and package-level documents used during the generation of Javadoc.</p>
  +     <p>To generate the Xalan HTML User's Guide, run the Xalan make file in the Xalan xdocs directory:<br/><br/>
  +     <code>make stylebook</code></p>
  +     <p>To generate Xalan API documentation, set up the make file to use the Javadoc tool in the Java JDK 1.2.2 bin 
  +     directory.</p>
  +     <p>Do the following:</p>
  +       <ol>
  +         <li>Put the Java JDK 1.2.2 bin directory on your path (in front of any JDK 1.1.x bin 
  +         directory that appears on the path).<br/><br/></li>
  +         <li>In the Xalan docs directory, run the Xalan make file as follows:<br/><br/>
  +         <code>make javadoc</code><br/><br/></li>
  +      </ol>
  +      <p>If you want to rebuild the documentation without using the GNU build environment, keep the following in
  +       mind:</p>
  +       <ul>
  +       <li>Be sure stylebook-1.0-b1.jar, xalan.jar, bsf.jar, bsfengines.jar, and xerces.jar are on the class
  +       path.<br/><br/></li>
  +       <li>To build doc in a build/docs subdirectory, run StyleBook from the xdocs directory as follows:<br/><br/>
  +<code>java org.apache.stylebook.StyleBook "targetDirectory=../build/docs/" sources/xalanLocal.xml style</code>
  +       <br/><br/></li>
  +       <li>To build the html source files that javadoc needs for top-level and package-level documentation, run
  +        StyleBook from the xdocs directory as follows:<br/><br/>
  +        <code>java org.apache.stylebook.StyleBook "loaderConfig=sbk:/style/loaderjdoc.xml" targetDirectory=../src sources/javadocPackages.xml style</code><br/><br/></li>
  +        <li>Before you run javadoc, make sure the following directory structure exists under the Xalan root
  +         directory: build/docs/apidocs.<br/><br/></li>
  +       <li>To build the API documentation, run the JDK 1.2.2 javadoc tool from the xdocs directory:<br/><br/>
  +<code>javadoc -overview ../src/javadocOverview.html -sourcepath ../src org.apache.xalan.xpath org.apache.xalan.xpath.xdom org.apache.xalan.xpath.dtm org.apache.xalan.xpath.xml org.apache.xalan.xslt org.apache.xalan.xslt.trace org.apache.xalan.xslt.client org.apache.xalan.xslt.extensions  -windowtitle Xalan -d ../build/docs/apidocs</code></li>
  +  </s3>    
  + </s2><anchor name="contact"/>
  + <s2 title="Getting in Touch">
  +  <p>Your feedback is more than welcome. Offers of help are even more so! Perhaps you would like to contribute to the ongoing development, testing, or documentation of &xslt4j;?</p> 
  +<p>Please email your comments, questions, suggestions, bug reports, and offers to help to <human-resource-ref idref="xalandev"/>.</p>
  + </s2>
  \ No newline at end of file
  1.10      +90 -53    xml-site/sources/xalan/overview.xml
  Index: overview.xml
  RCS file: /home/cvs/xml-site/sources/xalan/overview.xml,v
  retrieving revision 1.9
  retrieving revision 1.10
  diff -u -r1.9 -r1.10
  --- overview.xml	2000/01/20 16:39:04	1.9
  +++ overview.xml	2000/02/17 16:48:45	1.10
  @@ -59,77 +59,114 @@
   <s1 title="&xslt4j; Overview">
  +<li><link anchor="intro">Introduction</link></li>
  +<li><link anchor="features">&xslt4j; Features</link></li>
  +<li><link anchor="towork">Getting to work with &xslt4j;</link></li>
  +<li><link anchor="uptospeed">Getting up to speed with XSLT</link></li>
  +<li><link anchor="glossary">Glossary</link></li>
  +</ul><anchor name="intro"/>
     <s2 title="Introduction">
  -    <p>&xslt4j; (named after a rare musical instrument) provides high- 
  -      performance XSL stylesheet processing. &xslt4j; fully implements the W3C 
  -      XSLT recommendation. The stylesheet processor is feature rich and 
  -      robust. 
  -    </p>
  -    <p>XSL is a language for expressing stylesheets and other types of transformations. 
  -		It consists of two parts:</p> 
  -		  <ol> 
  -		    <li>XLST, a language for transforming XML documents into other XML documents,
  -        HTML documents, or other document types. This part of the language includes the XSL
  -        Transformation vocabulary and XPath, a language for addressing parts of an XML document. 
  -        XPath is designed to be used by both XSLT and XPointer.<br/><br/></li>
  -		    <li>An XML vocabulary for specifying formatting semantics (called <ref>Formatting
  -        Objects</ref>).<br/><br/></li> 
  -			</ol> 
  -		  <p>&xslt4j; implements the first part of XSL, the <resource-ref idref="xsl-draft-used"/>.
  -       An XSLT stylesheet specifies the transformation that may be performed with a range of XML 
  -       documents by describing how to transform such a tree of nodes into another XML tree of
  -       nodes.</p>
  -       <note>The XSLT stylesheet may include cascading style sheets (CSS) in the result.</note>
  -       <p>In the following example, the foo.xsl stylesheet is used to transform foo.xml into foo.out:</p>
  -       <p>foo.xml:</p>
  -        <source>
  -&lt;?xml version="1.0"?>
  -        </source>
  +    <p>&xslt4j; (named after a rare musical instrument) fully implements the <resource-ref idref="xsl-draft-used"/>. 
  +    XSLT is the first part of the XSL stylesheet language for XML. It includes the XSL Transformation vocabulary and the
  +    XML Path language (XPath), a language for addressing parts of XML documents. For links to background materials, 
  +    discussion groups, frequently asked questions, and tutorials on XSLT, see <link anchor="uptospeed">Getting up
  +    to speed with XSLT</link>.</p> 
  +    <note>XSL also includes a formatting vocabulary, which is still under design and is not part of &xslt4j;. 
  +    For more information, see <jump href="http://www.w3.org/TR/xsl/">W3C XSL Working Draft</jump> and the <jump
  +    href="http://xml.apache.org/fop">Apache XML FOP (Formatting Objects Project)</jump>.</note>
  +    <p>You use XSLT to compose stylesheets (themselves XML documents) for transforming XML documents into other XML
  +    documents, HTML documents, or other document types. In structural terms, an XSLT stylesheet specifies the transformation
  +    of one tree of nodes (the XML input) into another tree of nodes (the output or transformation result).</p>
  +    <note>The XSLT stylesheet may include cascading style sheets (CSS) in the result.</note> 
  +    <p>In the following example, the foo.xsl stylesheet is used to transform foo.xml into foo.out:</p>
  +    <p>foo.xml:</p>
  +        <source>&lt;?xml version="1.0"?>
  -        <source>
  -&lt;?xml version="1.0"?> 
  +        <source>&lt;?xml version="1.0"?> 
   &lt;xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" version="1.0">
   &lt;xsl:template match="doc">
   &lt;out>&lt;xsl:value-of select="."/>&lt;/out>
  -      <p>foo.out:</p><source>
  -		  <p>By default, &xslt4j; uses &xml4j; 
  -      to parse input XML documents and XSL stylesheets, but it can be adapted to work with 
  -      other DOM-producing mechanisms.</p>
  -      <p>During the course of a transformation, &xslt4j; produces SAX events, 
  -      an output DOM, or an XML result document based on the transformations specified in the 
  -      XSL stylesheet.</p>
  -      </s2>
  +<p>By default, &xslt4j; uses a high-performance <link idref="dtm">Document Table Model (DTM)</link> to parse the input -- XML documents and XSL stylesheets, but it can be set to use the &xml4j; XML parser, and it can be adapted to work with other DOM-producing mechanisms and SAX document handlers. The input may appear in the form of a file, a character stream, a byte stream, a DOM, or a SAX input stream.</p>
  +<p>&xslt4j; performs the transformations specified in the XSL stylesheet and produces a document file, a character
  + stream, a byte stream, a DOM, or a series of SAX events, as you specify when you set up the transformation.</p>
  +      </s2><anchor name="features"/>
      	  <s2 title="&xslt4j; Features">
   		    <li>Implements the <resource-ref idref="xsl-draft-used"/>.</li> 
  -    	  <li>Uses &xml4j;</li>
  -    	  <li>Can interface to any XML parser that produces Java DOM Trees</li>
  +    	  <li>Uses <jump href="http://xml.apache.org/xerces-j/index.html">&xml4j;</jump> 
  +        (and <jump href="http://www.alphaworks.ibm.com/tech/xml4j">the alphaWorks XML Parser for Java</jump>)</li>
  +    	  <li>Can interface to a SAX document handler or to any XML parser that produces Java DOM Trees</li>
       	  <li>Can output to SAX or DOM</li>
  -    	  <li>Includes an applet wrapper</li>
  -        <li>Supports Java and JavaScript extensions</li>
  -        <li>Supports the production in a single operation 
  -        of multiple output documents</li>        
  +        <li>May be run from the <link idref="commandline">command line</link></li>
  +    	  <li>Includes an <link idref="getstarted" anchor="applet">applet wrapper</link></li>
  +        <li>May be used in a <link idref="samples" anchor="servlet">servlet</link> to transform XML documents into HTML
  +         and serve the results to clients.</li>
  +        <li>Supports <link idref="extensions">Java and scripting language extensions</link></li>
  +        <li>Provides <link idref="extensions" anchor="redirect">an extension to support the production of multiple 
  +        output documents in a single operation</link></li>
  -	  </s2>
  +	  </s2><anchor name="towork"/>
  +    <s2 title="Getting to work with &xslt4j;">
  +     <p>For instructions and some suggestions about how to get started using &xslt4j;, see 
  +     <link idref="getstarted">Getting Started</link>.</p>
  +    </s2><anchor name="uptospeed"/>
       <s2 title="Getting up to speed with XSLT">
  -    <p>If you are still working through some of the details of the XSLT spec, you may want to make use of one or more 
  -    of the following:</p>
  +    <p>If you are still working through the details of the XSLT spec (the W3C 1.0 Recommendation), you may want to
  +     consult one or more of the following:</p>
       <li>Elliotte Rusty Harold's <jump href="http://metalab.unc.edu/xml/books/bible/updates/14.html">Chapter 14 of 
       the XML Bible: XSL Transformations</jump><br/><br/></li>
  -    <li>Crane Softwright's <jump href="http://www.CraneSoftwrights.com/training/">Free preview of Practical Transformation Using XSLT
  -    and XPath</jump><br/><br/></li>
  +    <li>Crane Softwright's <jump href="http://www.CraneSoftwrights.com/training/">Free preview of Practical
  +     Transformation Using XSLT and XPath</jump><br/><br/></li>
       <li>The Mulberry <jump href="http://www.mulberrytech.com/xsl/xsl-list/">XSL-List -- Open Forum on XSL</jump> 
       (of interest to XSL users at all levels)<br/><br/></li>
  +    <li>Dave Pawson's <jump href="http://freespace.virgin.net/b.pawson/xsl/index.html#top">XSL Frequently Asked
  +     Questions</jump><br/><br/></li>
  +    <li>Objects by Design's <jump href="http://www.objectsbydesign.com/projects/xmi_to_html.html">Transforming XMI to
  +     HTML</jump><br/><br/></li>
  +     <li>Nic Miloslav's <jump href="http://zvon.vscht.cz/HTMLonly/XSLTutorial/Books/Book1/index.html">XSL Tutorial</jump>
  +     <br/><br/></li>
  +     <li>OASIS (the Organization for the Advancement of Structured Information Standards): 
  +     <jump href="http://www.oasis-open.org/cover/xsl.html">Extensible Stylesheet Language (XSL)</jump> by Robin
  +     Cover</li>
  -    <p>This is a very preliminary list. If you have come across other useful introductionary or background materials,
  -     please email <human-resource-ref idref="dleslie"/>, so he can add them to this list.</p>
  +    <p>When you come across other useful introductionary or background materials, please email <human-resource-ref
  +     idref="dleslie"/>, so he can add them to this list.</p>
  +    </s2><anchor name="glossary"/>
  +       <s2 title="Glossary">
  +      <gloss>
  +        <label>XSL Instruction</label>
  +        <item>Any tag with an XSL namespace prefix.<br/><br/></item>
  +        <label>XSL Template Instruction</label>
  +        <item>Any tag with an XSL namespace prefix
  +            that occurs inside an xsl:template element.<br/><br/></item>
  +        <label>Template Child</label>
  +        <item>Any node that is a child of an xsl:template element.<br/><br/></item>
  +        <label>Source Tree</label>
  +        <item>The tree input to the XSL process.<br/><br/></item>
  +        <label>Result Tree</label>
  +        <item>The tree that is output by the XSL process.<br/><br/></item>
  +        <label>Stylesheet Tree</label>
  +        <item>The stylesheet tree produced from the XSL file.<br/><br/></item>
  +        <label>Pattern List</label>
  +        <item>A parsed query or match pattern.<br/><br/></item>
  +      </gloss>
  +      <p>For more definitions of XSLT terminology, see Dave Lawson's 
  +      <jump href="http://freespace.virgin.net/b.pawson/xsl/xslvocab.html#top">XSLT Terminology
  +      Clarification</jump>.</p>
  1.4       +9 -6      xml-site/sources/xalan/dtm.xml
  Index: dtm.xml
  RCS file: /home/cvs/xml-site/sources/xalan/dtm.xml,v
  retrieving revision 1.3
  retrieving revision 1.4
  diff -u -r1.3 -r1.4
  --- dtm.xml	2000/01/18 22:08:21	1.3
  +++ dtm.xml	2000/02/17 16:48:45	1.4
  @@ -64,12 +64,15 @@
        <p>DOM (Document Object Model) is a standard interface for interacting with XML documents. &xslt4j;
        supports this interface: when you provide a Node as input for an XML source document or XSL 
        stylesheet, &xslt4j; uses an implementation of the DOM interface. For large XML documents, however,
  -     this may involve considerable overhead, since Xalan must create one or more Java objects for each Node
  +     this may involve considerable overhead, since &xslt4j; must create one or more Java objects for each Node
        in the document.</p>
  -     <p>For those cases where you provide a URL or character stream as input and use the default XSML parser
  -     (&xml4j;) &xslt4j; avoids this overhead by implementing what we call a DTM (Document Table Model), a
  -     pseudo-DOM that uses integer arrays in place of the DOM. The performance improvements are very
  -     significant.</p>
  -     <p><ref>More to be written.</ref></p>
  +     <p>For those cases where you provide a URL, file, character stream, SAX input stream, or byte stream as input
  +     and use the  default XML liaison and parser, &xslt4j; avoids this overhead by implementing a DTM, effectively
  +     a "pseudo-DOM" that uses integer arrays in place of the DOM. For larger input trees, the performance
  +      improvements can be very significant.</p>
  +     <p>The XSLTProcessorFactory getProcessor() method sets up an XSLT processor to use the default liaison and
  +     parser. If your input is a DOM, you must use a "standard" DOM parser. In that case, you can use the 
  +     XercesLiaison and Xerces XML parser. For more information, see <link idref="usagepatterns"
  +     anchor="dom-in">Processing DOM input</link>.</p>     
  1.6       +7 -6      xml-site/sources/xalan/commandline.xml
  Index: commandline.xml
  RCS file: /home/cvs/xml-site/sources/xalan/commandline.xml,v
  retrieving revision 1.5
  retrieving revision 1.6
  diff -u -r1.5 -r1.6
  --- commandline.xml	2000/01/20 16:39:04	1.5
  +++ commandline.xml	2000/02/17 16:48:45	1.6
  @@ -63,26 +63,27 @@
      <s2 title="Using the Command-Line Utility">
         <p>To perform a transformation, you can call &xslt4j; from the command line (or script), 
  -      an applet, an application, or a servlet. see <resource-ref idref="APIOverview"/> and <resource-ref idref="APIDocumentation"/>.</p>
  +      an applet, an application, or a servlet (see <link idref="usagepatterns">UsagePatterns</link>).</p>
        <p>The org.apache.xalan.xslt.Process main() method provides a comand-line interface
       for performing XSL transformation. To perform a transformation from the command line or a script,
       do the following:</p>
       <li>Install &xslt4j;. See <resource-ref idref="Installation"/>.<br/><br/></li> 
  -    <li>Set the java Classpath to include xalan.jar and xerces.jar.<br/><br/></li>
  -    <li>Call java and the Process class with the appropriate switches and
  +    <li>Set the java Classpath to include xalan.jar and xerces.jar. See <link idref="getstarted"
  +     anchor="classpath">Setting the class path</link><br/><br/></li>
  +    <li>Call java and the Process class with the appropriate flags and
       arguments (described below). The following command line, for example, includes the -IN, -XSL,
  -    and -OUT switches with their accompanying arguments -- the XML source document, the XSL
  +    and -OUT flags with their accompanying arguments -- the XML source document, the XSL
       stylesheet, and the output file:<br/><br/>
       <code>java org.apache.xalan.xslt.Process -IN foo.xml -XSL foo.xsl -OUT foo.out</code>
  -    <p>The command line utility can take the following switches and arguments:</p> 
  +    <p>The command line utility can take the following flags and arguments:</p> 
           -IN inputXMLURL
           -XSL XSLTransformationURL
           -OUT outputFileName
           -LXCIN compiledStylesheetFileNameIn
  -        -LXCOUT compiledStylesheetFileNameOut (it will be big!)
  +        -LXCOUT compiledStylesheetFileNameOut
           -PARSER fully qualified class name of parser liaison
           -E (Keep--do not expand -- entity refs)
           -V (Version info)
  1.1                  xml-site/sources/xalan/usagepatterns.xml
  Index: usagepatterns.xml
  <?xml version="1.0" standalone="no"?> 
  <!DOCTYPE s1 SYSTEM "sbk:/style/dtd/document.dtd">
   * The Apache Software License, Version 1.1
   * Copyright (c) 1999 The Apache Software Foundation.  All rights 
   * reserved.
   * Redistribution and use in source and binary forms, with or without
   * modification, are permitted provided that the following conditions
   * are met:
   * 1. Redistributions of source code must retain the above copyright
   *    notice, this list of conditions and the following disclaimer. 
   * 2. Redistributions in binary form must reproduce the above copyright
   *    notice, this list of conditions and the following disclaimer in
   *    the documentation and/or other materials provided with the
   *    distribution.
   * 3. The end-user documentation included with the redistribution,
   *    if any, must include the following acknowledgment:  
   *       "This product includes software developed by the
   *        Apache Software Foundation (http://www.apache.org/)."
   *    Alternately, this acknowledgment may appear in the software itself,
   *    if and wherever such third-party acknowledgments normally appear.
   * 4. The names "Xalan" and "Apache Software Foundation" must
   *    not be used to endorse or promote products derived from this
   *    software without prior written permission. For written 
   *    permission, please contact apache@apache.org.
   * 5. Products derived from this software may not be called "Apache",
   *    nor may "Apache" appear in their name, without prior written
   *    permission of the Apache Software Foundation.
   * ====================================================================
   * This software consists of voluntary contributions made by many
   * individuals on behalf of the Apache Software Foundation and was
   * originally based on software copyright (c) 1999, Lotus
   * Development Corporation., http://www.lotus.com.  For more
   * information on the Apache Software Foundation, please see
   * <http://www.apache.org/>.
  <s1 title="Basic usage patterns">
  <li><link anchor="intro">Introduction</link></li>
  <li><link anchor="files">Using a stylesheet file to transform an XML source file into an output file</link></li>
  <li><link anchor="streams">Using data streams in place of files</link></li>
  <li><link anchor="params">Setting stylesheet parameters</link></li>
  <li><link anchor="compiled">Compiling stylesheets</link></li>
  <li><link anchor="dom-in">Processing DOM input</link></li>
  <li><link anchor="dom-out">Producing DOM output</link></li>
  <li><link anchor="sax">Generating and responding to SAX events</link></li>
  <li><link anchor="xpath">Working with XPath expressions</link></li>
  <li><link anchor="applet">Using the &xslt4j; applet wrapper</link></li>
  <li><link anchor="servlet">Using &xslt4j; in a servlet</link></li>
  <li><link anchor="extensions">Creating and using extensions</link></li>
  <li><link anchor="debugging">Debugger interface</link></li>
  </ul><anchor name="intro"/>
    <s2 title="Introduction">  
  <p>&xslt4j; takes as primary input an XML source document and an XSL stylesheet, both represented by instances of the <resource-ref idref="XSLTInputSourceDoc"/>. You can use a URL or file, a character stream, a byte stream, a DOM tree, or a SAX input source to create an XSLTInputSource object. The stylesheet may also take the form of a compiled stylesheet (an instance of the <resource-ref idref="StylesheetRootDoc"/>. If the XML document contains a stylesheet Processing Instruction (PI), a separate stylesheet is not required.</p>
  <p>&xslt4j; uses an implementation of the <resource-ref idref="XMLParserLiaisonDoc"/> to interact with an XML parser and sends the output to <resource-ref idref="XSLTResultTargetDoc"/>. Unless your ar processing a DOM, you probably want to use the default <link idref="dtm">Document Table Model (DTM)</link> liaison and XML parser. When you process DOM input, you can use the <resource-ref idref="XercesLiaisonDoc"/> along with the &xml4j; XML parser.</p>
  <p>The XSLT and XPath engines are independent of any given DOM or XML implementation. All parser-dependent
  calls are funneled through the XMLParserLiaison.</p>
  <p>For detailed API documentation (javadoc), see <resource-ref idref="APIDocumentation"/>. For an overview of the
  command-line utility, see <link idref="commandline">Command-Line Utility</link>.</p>     
  <anchor name="files"/>
  <s2 title="Using XML source, XSL stylesheet, and output files">
  <p>Use an XML file and an XSL file to instantiate XSLTInput objects, create a processor with the default DTM liaison, and send the transformation output to an output file. For example:</p>
  <source>public static void Transform(String xmlSourceURL, String xslURL, String outputURL)
    throws java.io.IOException, 
    // Use XSLTProcessor to instantiate an XSLTProcessor.
    org.apache.xalan.xslt.XSLTProcessor processor =
    // Create the 3 objects the XSLTProcessor needs to perform the transformation.
    org.apache.xalan.xslt.XSLTInputSource xmlSource = 
                          new org.apache.xalan.xslt.XSLTInputSource ("foo.xml");
    org.apache.xalan.xslt.XSLTInputSource xslSheet = 
                         new org.apache.xalan.xslt.XSLTInputSource ("foo.xsl");
    org.apache.xalan.xslt.XSLTResultTarget xmlResult = 
                         new org.apache.xalan.xslt.XSLTResultTarget ("foo.out");
    // Perform the transformation.
    processor.process(xmlSource, xslSheet, xmlResult);
  <p>For an online example, see <link idref="samples" anchor="simpletransform">SimpleTransform</link>.</p>
  <p>You can perform this same operation from the <link idref="commandline">command line</link>. For example:</p>
  <p><code>java org.apache.xalan.xslt.Process -in foo.xml -xsl foo.xsl -out output.xml</code></p>
  </s2><anchor name="streams"/>
  <s2 title="Using data streams in place of files">
  <p>The context in which you perform a transformation may call for input in the form of a character stream, byte stream, or SAX input stream, and output in the form of a character stream, byte stream, or SAX document handler. Suppose, for example, you want to output a stream of bytes for further processing:</p>
  <source>import org.apache.xalan.xslt.*;
  java.io.OutputStream byteStream = new java.io.OutputStream();
  XSLTRegultTarget out = new XSLTResultTarget(byteStream)
  // Do the transformation...
  // Work with the OutputStream...</source>
  </s2><anchor name="params"/>
  <s2 title="Setting stylesheet parameters">
  <p>An XSL stylesheet can include parameters that get set at run time when a transformation takes place. When we generate the HTML documents that make up the Xalan doc set, for example, we send the stylesheet an id parameter along with each XML source document. The id identifies that document and enables the stylesheet to integrate it into the overall doc set.</p>
  <p>To set a stylesheet parameter, use the XSLTProcessor setStylesheetParam(String paramName, String paramExpr) method. paramExpr is an XPath expression, so if the parameter is a String, enclose it in single quotes to make it a String expression.</p>
  <p>You can also use setStylesheetParam(String key, XObject value). This option is useful when you are working with the XPath API. For example, you could use the XObject returned by an Xpath function to set a parameter.</p>
  <p>From the <link idref="commandline">command line</link>, include a -param argument. For example:</p>
  <p><code>java org.apache.xalan.xsltProcess -in foo.xml -xsl foo.xsl -param 'boo'</code></p>
  </s2><anchor name="compiled"/>
  <s2 title="Compiling stylesheets">
  <p>A <resource-ref idref="StylesheetRootDoc"/> object is a binary representation of a stylesheet that adds efficiency to the performance of repeated transformations and supports threadsafe concurrent access by multiple clients. If, for example, you are setting up a servlet to perform transformations, you can improve performance by compiling any stylesheets the servlet repeatedly uses.</p>
  <p>To compile a stylesheet, use one of the the <resource-ref idref="XSLTProcessorDoc"/> processStylesheet methods. This operation also sets the XSLTProcessor Stylesheet property. In the interest of clarity, you may want to explicitly set that property. When you call the process method, include a null for the "uncompiled" stylesheet parameter so XLTProcessor uses the compiled stylesheet. For example:</p>
  <source>import org.apache.xalan.xslt.*;
  XSLTProcessor processor = XSLTProcessorFactory.getProcessor();
  StylesheetRoot style = processor.processStylesheet(new XSLTInputSource("foo.xsl"));
  processor.setStylesheet(style); // Good form!
  processor.process(new XSLTInputSource("foo.xml"),
                    null, // Use the Stylesheet property setting.
                    new XSLTOutputTarget("foo.out"));</source>
  <p>Alternative: For convenience, StylesheetRoot has its own process method, so another way to do the preceding is as follows:</p>
  <source>import org.apache.xalan.xslt.*;
  XSLTProcessor processor = XSLTProcessorFactory.getProcessor();
  StylesheetRoot style = processor.processStylesheet(new XSLTInputSource("foo.xsl"));
  style.process(new XSLTInputSource("foo.xml"), new XSLTOutputTarget("foo.out"));</source>
  <p>If you want to use the XSLTProcessor as a SAX document handler, you must provide the processor a compiled stylesheet. See <link anchor="sax">Generating and Responding to SAX events</link>.</p>
  </s2><anchor name="dom-in"/>
  <s2 title="Processing DOM input">
  <p>The XML source and XSL stylesheet for a transformation may appear in the form of a DOM Node. To perform transformations with DOM input, you cannot use the default high-performance DTM liaison and parser. <link idref="dtm">DTM (Document Table model)</link> uses a table of integers to represent a DOM, thus avoiding much of the overhead of creating and manipulating actual DOM nodes, which often involve a large number of Java objects. If you are processing DOM input, you must use a DOM parser, such as the Xerces DOM parser. When you create the XSLTProcessor for the transformation, you must specify that it is to use the Liaison for such a DOM parser.</p>
  <p>The following code fragments illustrate the procedure for working with DOM input:</p>
  <source>import org.apache.xerces.parsers.DOMParser;
  import org.w3c.dom.Document;
  import org.apache.xalan.xpath.xdom.XercesLiaison;
  import org.apache.xalan.xslt.*;
  // Just in case you want to produce your own DOM input...
  DOMParser parser = new DOMParser();
  Document in = parser.getDocument();
  XSLTInputSource xmlID = new XSLTInputSource(in);
  // Set up the XSLTProcessor to use XercesLiaison.
  XSLTProcessor xsltProc = XSLTProcessorFactory.getProcessor
                   (new org.apache.xalan.xpath.xdom.XercesLiaison())
  // or you can use XSLTProcessorFactory.getProcessorUsingLiaisonName
  //                ("org.apache.xalan.xpath.xdom.XercesLiaison")
  // Perform the transformation.</source>
  </s2><anchor name="dom-out"/>
  <s2 title="Producing DOM output">
  <p>To produce a DOM Node as your transformation output, use a new Node to create the XSLTResultTarget for the transformation. Then when you perform the transformation, the result is output as a DOM Node. For example:</p>
  <source>import org.w3.dom.Document;
  import org.apache.xalan.xslt.*;
  XSLTProcessor xsltProc = XSLTProcessorFactory.getProcessor();
  org.w3c.dom.Document out = new org.apache.xerces.dom.DocumentImpl();
  XSLTResultTarget resultTarget = new XSLTResultTarget(out);
  processor.process(new XSLTInputSource("foo.xml"),
                    new XSLTInputSource("foo.xsl"),
  <p>The XSLTResultTarget object (resultTarget) now contains a Node. For a working example, see <link idref="samples" anchor="transformtodom">TransformToDom</link>.</p>
  </s2><anchor name="sax"/>
  <s2 title="Generating and responding to SAX events">
  <p>To set up a transformation to generate SAX events, set the DocumentHandler property of the XSLTResultTarget object. The transformation consumer can then respond to these events as they occur, rather than waiting (as the consumer of a DOM must) for the complete result tree.</p>
  <p>This example sends the output to System.out.</p>
  <source>import org.apache.xalan.xslt.XSLTProcessor;
  import org.apache.xalan.xslt.XSLTInputSource;
  import org.apache.xalan.xslt.XSLTResultTarget;
  import org.apache.xalan.xslt.XSLTProcessorFactory;
  import org.apache.xalan.xslt.StylesheetRoot;
  public class TransformToSax
  	public static void main(String[] args)
      throws java.io.IOException,
      XSLTProcessor processor = XSLTProcessorFactory.getProcessor();
      // Set the processor to use a compiled stylesheet.
      // The stylesheet provides access to a SAX DocumentHandler,
      // passing it the stylesheet xsl:output settings.
      StylesheetRoot stylesheet = processor.processStylesheet("foo.xsl");
      // This property was just set implicitly, but for good form...
      // In this case, send the output to System.out.
      org.xml.sax.DocumentHandler dh = stylesheet.getSAXSerializer(System.out);
      // Use the DocumentHandler to construct an XSLTResultTarget object.
      XSLTResultTarget saxResult = new XSLTResultTarget(dh);
      // Perform the transformation. The stylesheet parameter is null, so
      // the processor uses the compiled stylesheet identified by its 
      // Stylesheet property setting.
      processor.process(new XSLTInputSource("foo.xml"), null, saxResult);
  <p>XSLTProcessor also has a DocumentHandler property (in fact, XSLTProcessor extends DocumentHandler). By setting this property, you instruct the processor to process a sequence of SAX events. The processor needs a compiled stylesheet to perform this transformation.</p>
  <p>The following example uses the output of one transformation as the input for a second transformation. It does this by using two SAX DocumentHandlers to pipe SAX events from the first transformation to the second.</p>
  <source>import org.apache.xalan.xslt.*;
  public class ChainTransforms
  	public static void main(String[] args)
      throws java.io.IOException,
      // Create processor for 1st transform.
      XSLTProcessor processor1 = XSLTProcessorFactory.getProcessor();
      // Create processor for 2nd transform. Set Stylesheet and
      // DocumentHandler properties so this processor uses the
      // 2nd stylesheet and processes SAX events (output from the
      // 1st transform), sending the final result to System.out.
      XSLTProcessor processor2 = XSLTProcessorFactory.getProcessor();
      StylesheetRoot stylesheet2 = processor2.processStylesheet("foo2.xsl");
      org.xml.sax.DocumentHandler dh = stylesheet2.getSAXSerializer(System.out);
      // Set up the 1st transform to produce a series of SAX events, and
      // to pass these events to the processor for the 2nd transform.
      // To accomplish this, create an XSLTResultTarget object for the
      // 1st transform, and use the processor for the 2nd transform to set
      // the XSLTResultTarget DocumentHandler property.
      XSLTResultTarget intermedResult = new XSLTResultTarget();
      // Perform the 1st transform, which produces a series of
      // SAX events that are in turn processed by the processor2 DocumentHandler
      // in conjunction with stylesheet2, sending the output to System.out.
      processor1.process(new XSLTInputSource("foo.xml"),
                         new XSLTInputSource("foo.xsl"),
  <p>For a more compact (and elegant) form of this example, see the <link idref="samples" anchor="pipe">Pipe</link>.</p>
  </s2><anchor name="xpath"/>
  <s2 title="Working with XPath expressions">
  <p>XSL stylesheets use XPath expressions to select nodes, specify conditions, and generate text for the result tree. XPath provides an API that you can call directly. For example, you may want to select nodes programatically and do your own processing without a stylesheet. For an example that executes individual XPath expressions against XML source files, see <link idref="samples" anchor="xpath">ApplyXPath</link>.</p>
  </s2><anchor name="applet"/>
  <s2 title="Using the &xslt4j; applet wrapper">
  <li>Include <resource-ref idref="XSLTProcessorAppletDoc"/> in an HTML client.<br/><br/></li>
  <li>Specify the XML source document and XSL stylesheet.<br/><br/>
  You can use the DocumentURL and StyleURL PARAM tags or the <resource-ref idref="XSLTProcessorAppletsetDocumentURLDoc"/> and <resource-ref idref="XSLTProcessorAppletsetStyleURLDoc"/>. If the XML document contains a stylesheet Processing Instruction (PI), you do not need to specify an XSL stylesheet.<br/><br/></li>
  <li>Call the <resource-ref idref="XSLTProcessorApplettransformtoHTMLstringstringDoc"/> which performs the transformation and returns the new document as a String.</li></ol>
  <p>For an example, see the <jump href="samples/applet/readme.html">sample applet readme</jump>.</p>
  </s2><anchor name="servlet"/>
  <s2 title="Using &xslt4j; in a servlet">
  <p>You can set up a servlet to use &xslt4j; to respond to requests for XML documents by transforming those documents into HTML and serving them to clients. For a sample of how this might be done, see <link idref="samples" anchor="servlet">sample servlet</link>.</p>
  </s2><anchor name="extensions"/>
  <s2 title="Creating and using extensions">
  <p>For those cases where you want to be able to call procedural code from within a stylesheet, the &xslt4j; Extensions facility supports the creation of extension elements and extension functions. See <link idref="extensions">Extensions</link> and <link idref="samples" anchor="extensions">Extensions samples</link>.</p>
  <anchor name="debugging"/>
  <s2 title="Debugger Interface">
  		<p>&xslt4j; contains a debugger interface in the org.apache.xalan.xslt.trace package:</p> 
  		  <li>The <resource-ref idref="TraceListenerDoc"/> is an interface that debuggers 
  		  can implement. The interface can be set on the 
  		  <resource-ref idref="XSLTProcessorDoc"/> by calling the addTraceListener function.<br/><br/></li>
  		  <li>The <resource-ref idref="PrintTraceListenerDoc"/> is an implementation of 
  		  the TraceListener interface that is used by the <link idref="commandline">command-line utility</link>
        for the -TT, TG, and -TTC. You can examine the utility code (org.apache.xalan.xslt.Process.java)
        for examples of how you might use the trace functionality.<br/><br/></li>
  		  <li>The <resource-ref idref="TracerEventDoc"/> is an event that is 
  		  passed to the TraceListener.trace function. It is called before a node is 'executed' 
  		  in the stylesheet.<br/><br/></li>
  		  <li>The <resource-ref idref="GenerateEventDoc"/> is an event that is 
  		  passed to the TraceListener.generated() function. It is called after an event 
  		  occurs to create something in the result tree.<br/><br/></li>
  import org.apache.xalan.xslt.XSLTProcessor;
  import org.apache.xalan.xslt.trace.PrintTraceListener;
  // Set up a PrintTraceListener object to print to a file.
  java.io.FileWriter fw = new java.io.FileWriter("events.log");
  java.io.PrintWriter pw = new java.io.PrintWriter(fw);
  PrintTraceListener ptl = new PrintTraceListener(pw);
  // Print information as each node is 'executed' in the stylesheet.
  ptl.m_traceElements = true;
  // Print information after each result-tree generation event.
  ptl.m_traceGeneration = true;
  // Print information after each selection event.
  ptl.m_traceSelection = true;
  // Print information whenever a template is invoked.
  ptl.m_traceTemplates = true;
  // Register the PrintTraceListener with the XSLTProcessor.
  XSLTProcessor processor = XSLTProcessorFactory.getProcessor();
  // Perform the transformation -- printing information to 
  // events.log during the process.
  processor.process(new XSLTInputSource("foo.xml"),
                    new XSLTInputSource("foo.xsl"),
                    new XSLTResultTarget("foo.out"));
  // Close the PrintWriter and FileWriter.
  1.1                  xml-site/sources/xalan/samples.xml
  Index: samples.xml
  <?xml version="1.0" standalone="no"?>
   * Copyright (c) 1999 Lotus Development Corporation, Inc. All Rights Reserved.
   *	This software is provided without a warranty of any kind.
  <!DOCTYPE s1 SYSTEM "sbk:/style/dtd/document.dtd">
  <s1 title="Samples">
  <li><link anchor="simpletransform">SimpleTransform</link></li>
  <li><link anchor="transformtodom">TransformToDom</link></li>
  <li><link anchor="usestylesheetparam">UseStylesheetParam</link></li>
  <li><link anchor="xpath">ApplyXPath</link></li>
  <li><link anchor="pipe">Pipe (SAX)</link></li>
  <li><link anchor="extensions">Extensions</link></li>
  <li><link anchor="applet">Applet</link></li>
  <li><link anchor="servlet">Servlet</link></li>
  	  <s2 title="Samples to help you get started">
      <p>Each of the subdirectories in the &xslt4j; samples directory contains the source files for one or more
       sample applications. The class files for all the samples are in xalansamples.jar, so to run the samples, 
       you should place xalansamples.jar on the system class path.</p>
       <p>With most of the samples, you can use the following procedure:</p>
       <li>Be sure xalan.jar, xalansamples.jar, and xerces.jar are on the system class path. For the extension
        examples, bsf.jar, bsfengines.jar, and (for the JavaScript extensions) js.jar must also be on the class
       <li>Be sure java.exe is on your path.</li>
       <li>Go to the samples subdirectory containing the sample (use the DOS shell if you are running Windows).</li>
       <li>Run the sample from the command line (as indicated below)</li>
      <li>Examine the application source files. You may also want to modify the source files. Remember that if you
       modify a java file, you must recompile the class and place it on the class path before you can run the
       modified application.</li>
      <p>The basic command line for running most of the samples is </p> 
      <p><code>java <ref>classname args</ref></code></p>
      <p>where <ref>classname</ref> is the classname and <ref>args</ref> are the arguments, if any. As described in
       the following sections, some samples take no arguments. The samples in UseStylesheetParam and ApplyXPath take
       additional arguments. The samples in extensions use the &xslt4j; <link idref="commandline">command-line
       utility</link>, so they take arguments for the XML source file and the XSL stylesheet.</p>
    	</s2><anchor name="simpletransform"/>
      <s2 title="SimpleTransform">
      <p>What it does: The SimpleTransform class uses the foo.xsl stylesheet to transform foo.xml, and prints the
       output to System.out.</p>
      <p>You can run it from the SimpleTransform subdirectory with</p>
      <p><code>java SimpleTransform</code></p>
      </s2><anchor name="transformtodom"/>
      <s2 title="TransformToDom">
      <p>What it does: The TransformToDom class uses the foo.xsl stylesheet to transform foo.xml, produces an output
       DOM, and traverses the DOM, printing the traversal to System.out. In contrast to SimpleTransform,
        TransformToDom illustrates the procedure for creating an output DOM that is available for further
     <p>You can run it from the TransformToDom subdirectory with</p>
      <p><code>java TransformToDom</code></p>
      </s2><anchor name="usestylesheetparam"/>
      <s2 title="UseStylesheetParam">
        <p>What it does: The UseStyleSheetParam class uses foo.xsl and a stylesheet parameter to transform foo.xml,
         and prints the output to System.out. The stylesheet parameter appears as a text node in the output.</p>
      <p>Run this sample from the UseStylesheetParam subdirectory with</p> 
      <p><code>java UseStylesheetParam <ref>param</ref></code></p>
      <p>where <ref>param</ref> is the stylesheet parameter.</p>  
      </s2><anchor name="xpath"/>
      <s2 title="ApplyXPath">
      <p>What it does: The ApplyXPath class executes an XPath expression against an XML document and returns
       information about the route it takes and the nodes (if any) it finds.</p>
       <note>You can use this sample as an aid when you want to find out what a given XPath expression returns from a
       given XML file. Keep in mind that the context node for the XPath expression is the document root.</note>
      <p>Run this sample from the ApplyXPath subdirectory with</p> 
      <p><code>java ApplyXPath <ref>XMLFile XPathExpression</ref></code></p>
      <p>where <ref>XMLFile</ref> is an XML source file and <ref>XPathExpression</ref> is an XPath expression to
       apply to that file. The ApplyXPath subdirectory contains an XML file named foo.xml, so you can try command
       lines like</p>
      <p><code>java ApplyXPath foo.xml /</code></p>
      <p><code>java ApplyXPath foo.xml /doc/name/@first</code></p>
      </s2><anchor name="pipe"/>
      <s2 title="Pipe">
      <p>What it does: The Pipe class uses the output of the first transformation as input to a second
       <p>The first transformation produces a sequence of SAX events which the second transformation processes with
        its own stylesheet. The consumer of SAX output can respond to these events as they occur, rather than waiting
         for the entire result tree to be constructed (as the DOM consumer must do).</p>
      <p>Run this sample from the Pipe subdirectory with</p> 
      <p><code>java Pipe</code></p>
      <p>For other examples using the SAX document handler, see <link idref="getstarted" anchor="sax">Generating and
       responding to SAX events</link>.</p>
      </s2><anchor name="extensions"/>
      <s2 title="Extensions">
      <p>The extensions subdirectory contains four samples with &xslt4j; extensions. Two of the samples use
       extensions implemented in JavaScript, and two of the samples use extensions implemented in Java. All of
       the samples are documented in <link idref="extensions">Extensions</link>.</p>
       <p>To run these examples, you must place bsf.jar and bsfengines.jar (distributed with &xslt4j;), and js.jar
       (available from http://www.mozilla.org/rhino) on the class path. You do not need js.jar
       on the class path for the samples that use Java extensions. </p>
       <p>Use java.org.apache.xalan.xslt.Process, the &xslt4j; command-line utility, to run these samples from
        the <link idref="commandline">command line</link>. The command line must include an -in flag with the 
        XML source and an -xsl flag with the XSL stylesheet. If you want the output to be printed to a file, rather
        than to the screen, add an -out flag with the output file name.</p>
        <p>Run these samples from the extensions directory as follows (each of the following is a single command
        <p><code>java org.apache.xslt.xalan.Process -in 1basicJscript</code> 
          <br/>&nbsp;&nbsp;<code>-xsl 1basicJscript</code></p>
        <p><code>java org.apache.xslt.xalan.Process -in 2java-namespace.xml</code> 
          <br/>&nbsp;&nbsp;<code>-xsl 2java-namespace.xsl</code></p>
        <p><code> java org.apache.xslt.xalan.Process -in 3numlistJava.xml</code> 
          <br/>&nbsp;&nbsp;<code>-xsl 3numlistJava.xsl</code></p>
        <p><code> java org.apache.xslt.xalan.Process -in 4numlistJcript.xml </code>
          <br/>&nbsp;&nbsp;<code>-xsl 4numlistJscript.xsl</code></p>
      </s2><anchor name="applet"/>
      <s2 title="AppletXMLtoHTML">
      <p>The applet uses a stylesheet to transform an XML document into HTML. It displays the XML document, the
       stylesheet, and the HTML output.</p>
      <p>How to run it: See <jump href="samples/applet/readme.html">sample applet readme</jump>.</p>
      <p>For a brief introduction to using applets to perform transformations, see <link idref="getstarted"
      anchor="applet">Using the &xslt4j; applet wrapper</link></p>  
      </s2><anchor name="servlet"/>
      <s2 title="Servlet">
      <p>What it does: The client (which you must set up) specifies an XML document and a stylesheet. The servlet
       performs the transformation and returns the output to the client. You can use media.properties to specify 
      which stylesheet is to be used depending on the client browser/device.</p>
      <p>How to run it:</p>
        <li>Configure your application server (Websphere or JServ, for example) so it can find the classes (in
         xalansamples.jar) as well as the stylesheets and properties file in the servlet subdirectory.</li>
        <li>Set up an HTML client to call DefaultApplyXSL with arguments as illustrated below.</li>
  <item>...applies the style.xsl stylesheet to the data.xml data.  Both files are
  served from the Web server's HTTP XSLTInputSource root.<br/><br/></item>
  <item>...ensures that XML and XSL processor messages are returned in the event of problems
  applying style.xsl to data.xml<br/><br/></item>
  <item>...applies the style.xsl stylesheet to the data.xml data, just like the first example.
  This is an alternative way of specifying the XML XSLTInputSource by utilizing the HTTP request's path
  <item>...examines data.xml for an <jump href="http://www.w3.org/TR/1999/PR-xml-stylesheet-19990114">associated</jump>
  XSL stylesheet. If multiple XSLs are associated with the data, the stylesheet whose media
  attribute maps to your browser type will be chosen.  If no mapping is
  successful, the primary associated stylesheet is used.<br/><br/></item>
  <item>...provides the same function as the previous example, but this example assumes
  that /servlet/data.xml has been mapped to be executed by this servlet.  The servlet engine may be configured
  to map all or some *.xml files to this servlet through the use of servlet aliases or filters.<br/><br/></item>
  <item>...supplements any servlet-configured XCatalog
  with a catalog of supply chain DTDs residing at the XML.ORG DTD repository.</item>
  <p>For more information, see the comments in DefaultApplyXSL.java.</p>
  1.1                  xml-site/sources/xalan/getstarted.xml
  Index: getstarted.xml
  <?xml version="1.0" standalone="no"?> 
  <!DOCTYPE s1 SYSTEM "sbk:/style/dtd/document.dtd">
  <s1 title="Getting Started">
  <li><link anchor="download">Downloading what you need</link></li>
  <li><link anchor="classpath">Setting up the system class path</link></li>
  <li><link anchor="samples">Trying out the samples</link></li>
  <li><link anchor="commandline">Performing your own transformations from the command line</link></li>
  <li><link anchor="java-apps">Creating your own XSLT applications</link></li>
  <anchor name="download"/>
  <s2 title="Downloading what you need">
  <p>To use Xalan, you need the following:</p>
  <li>The JDK or JRE 1.1.6 or later</li>
  <p>You can get the Sun JDK or JRE from <jump href="http://www.java.sun.com">java.sun.com</jump>. Download the latest release of Xalan and Xerces-java from <jump href="http://xml.apache.org/dist/">xml.apache.org</jump>. Check the <link idref="readme" anchor="status">version release notes</link> to verify that you are using the correct version of Xerces. <em>Important</em> You may experience unpredicable difficulties and anomalies if your &xslt4j; and &xml4j; builds are not in synch. You can use &xslt4j; with some other XML parser, but it is up to you to implement a liaison to that parser. Your liaison class should extend org.apache.xalan.xpath.xml.XMLParserLiaisonDefault and implement org.apache.xalan.xpath.XPathSupport.</p>
  <note>You may also download the latest releases of LotusXSL and the XML Parser for Java from <jump href="http://www.alphaworks.ibm.com/tech/LotusXSL">alphaWorks</jump>. LotusXSL and the XML Parser for Java are Xalan and Xerces-java respectively, along with additional features and with wrappers to support the core API in place on alphaWorks before the first releases of Xalan and Xerces-java on xml.apache.org in November 1999. The alphaWorks LotusXSL release also provides continued support for earlier alphaWorks releases of the XML4J DOM and TXDOM parsers.</note>
  <p>If you plan to run <link idref="extensions">XSLT extensions</link>. you need bsf.jar and bsfengines.jar, both of which are included in the Xalan distribution. If you plan to run XSLT extensions implemented in JavaScript or another scripting language, you will need one or more additional files as indicated in <link idref="extensions" anchor="supported-lang">extensions language requirements</link>.</p>
  </s2><anchor name="classpath"/>
  <s2 title="Setting up the system class path">
  <p>At the very minimum, you must include xalan.jar and xerces.jar on the system class path. To run the sample applications, include xalansamples.jar To run extensions, include bsf.jar and bsfengines.jar. All these JAR files are distributed with &xslt4j;. For extensions implemented in JavaScript or another scripting language, see <link idref="extensions" anchor="supported-lang">extensions language requirements</link> to identify any additional JAR files you must place on the class path and where you can get them.</p>
  <p>If you are using JDK or JRE 1.1.x (at least 1.1.7, please), also include classes.zip on the class path.</p>
  </s2><anchor name="samples"/>
  <s2 title="Trying out the samples">
  <p>The Xalan distribution includes a number of basic sample applications. These samples are easy to run, and you can review the source files -- all of which are brief -- to see just how they work.</p>
  <p>To run the samples, do the following:</p>
  <li>Set up your class path (see above), including xalansamples.jar.</li>
  <li>Be sure java.exe is on your path.</li>
  <li>Go to the samples subdirectory containing the sample (use the DOS shell if you are running Windows).</li>
  <li>Run the sample from the command line.</li>
  <li>Examine the application source files.</li>
  <p>For example, go to the SimpleTransformation subdirectory and issue the following command:</p>
  <p><code>java SimpleTransformation</code></p>
  <p>The sample displays the transformation result on the screen. To see how the example works, examine the source files: foo.xml, foo.xsl, and SimpleTransformation.java.</p>
  <p>The extensions examples require additional JAR files on the class path, and the procedure for running the sample applet and sample servlet is different. For more information about all the samples, see <link idref="samples">&xslt4j; Samples</link>.</p>
  </s2><anchor name="commandline"/>
  <s2 title="Performing your own transformations from the command line">
  <p>java.org.apache.xalan.xslt.Process provides a basic utility for performing transformations from the command line. You use this utility, for example, to run the extensions samples. The command-line for the most standard of
   transformations is as follows:</p>
  <p><code>java org.apache.xalan.xslt.Process -in <ref>xmlSource</ref></code><br/>
  <code>&nbsp;&nbsp;&nbsp;&nbsp;-xsl <ref>stylesheet</ref> -out <ref>outputfile</ref></code></p>
  <p>where <ref>xmlSource</ref> is the XML source file name, <ref>stylesheet</ref> is the XSL stylesheet file name, and <ref>outputfile</ref> is the output file name.</p>
  <p>If you want the output to be displayed on the screen, simply omit the -out flag and argument.</p>
  <p>You can use this utility to try out XSL stylesheets you have written, to make sure they do what you expect with the XML source files they are designed to transform. The utility provides useful messages if the source file or stylesheet is not well-formed. If you include a DOCTYPE statement in your XML source files and include the -validate flag on the command line, the utility will also let you know whether the XML document is valid (conforms to that DOCTYPE). For more information, see <link idref="commandline">Command-Line Utility</link>.</p>
  </s2><anchor name="java-apps"/>
  <s2 title="Setting up your own Java applications">
  <p>You can start by using your own XML source files and XSL stylesheets with the sample applications, which illustrate a number of the <link anchor="usage-patterns">basic usage patterns</link>.</p>
  <p>If you modify a java source file, be sure to compile the class and place it on the system class path. Here are some basic points to keep in mind as you are setting up transformations:</p>
  <li>Use one of the <resource-ref idref="XSLTProcessorFactoryDoc"/> static getProcessor methods to set up an <resource-ref idref="XSLTProcessorDoc"/>. <br/><br/>By default, the XSLTProcessor uses the <resource-ref idref="DTMLiaisonDoc"/> and the high-performance <link idref="dtm"> Document Table Model (DTM)</link>"pseudo" DOM parser to process the input.  If your input is a DOM node (rather than a file, character stream, byte stream, or SAX input stream), you must use a "standard" DOM liaison and parser, such as the <resource-ref idref="XercesLiaisonDoc"/> and the Xerces DOM parser. For an example, see <link anchor="dom-in">Processing DOM input</link>.<br/><br/></li>
  <li>Set up <resource-ref idref="XSLTInputSourceDoc"/> objects for the XML input and XSL stylesheet. You can use a file name or URL, character streams, byte streams, or SAX input stream to instantiate an XSLTInputSource object.<br/><br/>
  If the XML document contains a stylesheet Processing Instruction (PI), you do not need to create a separate
  XSLTInputSource object for an XSL stylesheet.<br/><br/></li>
  <li>For improved performance with a series of transformations, use the XSLTProcessor processStylesheet method to compile the XSL stylesheet (the result is a <resource-ref idref="StylesheetRootDoc"/>.<br/><br/>
  This is also useful when you need to get information from the stylesheet before the tranformation occurs, for
  instance, when you need to find out the output encoding in order to construct the right kind of Writer.
  You must also compile the stylesheet if you are using the XSLTProcessor as a SAX document handler.<br/><br/></li>
  <li>Set up an <resource-ref idref="XSLTResultTargetDoc"/> for the transformation output. You can use a file name or URL, character stream, byte stream, or SAX document handler to instantiate an XSLTOutputTarget object.<br/><br/></li>
  <li>Use the XSLTProcessor (or, in some cases, the <link idref="StylesheetRootDoc"/>) process method to perform the transformation.<br/><br/>
  &xslt4j; is thread-safe for one instance per thread. If you are using the same instance of XSLTProcessor to perform
  more than one transformation, call the reset method between transformations.</li>
  <p>For more information on setting up applications, see <link idref="usagepatterns">Usage Patterns</link>.</p>

View raw message