You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@xalan.apache.org by dl...@locus.apache.org on 2000/09/12 23:41:10 UTC
cvs commit: xml-xalan/java/xdocs/sources/xalan commandline.xml samples.xml whatsnew.xml
dleslie 00/09/12 14:41:10
Modified: java/xdocs/sources/xalan commandline.xml samples.xml
whatsnew.xml
Log:
Editorial updates
Revision Changes Path
1.2 +3 -6 xml-xalan/java/xdocs/sources/xalan/commandline.xml
Index: commandline.xml
===================================================================
RCS file: /home/cvs/xml-xalan/java/xdocs/sources/xalan/commandline.xml,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- commandline.xml 2000/08/28 21:01:44 1.1
+++ commandline.xml 2000/09/12 21:41:09 1.2
@@ -68,9 +68,9 @@
for performing XSL transformation. To perform a transformation from the command line or a script,
do the following:</p>
<ol>
- <li><link idref="getstarted" anchor="download">Download &xslt4j;</link>.<br/><br/></li>
- <li><link idref="getstarted"
- anchor="classpath">Set the java class path</link> to include xalan.jar and xerces.jar<br/><br/></li>
+ <li>Download &xslt4j;.<br/><br/></li>
+ <li><link idref="getstarted" anchor="classpath">Set the java class path</link> to include xalan.jar and
+ xerces.jar<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 flags with their accompanying arguments -- the XML source document, the XSL
@@ -83,7 +83,6 @@
-OUT outputFileName
-LXCIN compiledStylesheetFileNameIn
-LXCOUT compiledStylesheetFileNameOut
--PARSER fully qualified class name of parser liaison
-V (Version info)
-QC (Quiet Pattern Conflicts Warnings)
-Q (Quiet Mode)
@@ -106,8 +105,6 @@
<p>Use -LXCOUT to compile an XSL stylesheet for future use as -LXCIN input.</p>
<note>You can only use -LXCIN with a compiled stylesheet that you have already created with the -LXOUT switch. For an
example, see <link anchor="compiledstylesheet">Using a compiled stylesheet</link></note>
- <p>Include -PARSER if you supply your own parser liaison class, which is required if you do not use DTM or the
- Xerces parser.</p>
<p>Use -TEXT if you want the output to include only element values (not element tags with element names and
attributes).</p>
<p>Use -HTML to write 4.0 transitional HTML (some elements, such as <br>, are
1.2 +3 -3 xml-xalan/java/xdocs/sources/xalan/samples.xml
Index: samples.xml
===================================================================
RCS file: /home/cvs/xml-xalan/java/xdocs/sources/xalan/samples.xml,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- samples.xml 2000/08/28 21:01:44 1.1
+++ samples.xml 2000/09/12 21:41:09 1.2
@@ -70,7 +70,7 @@
</ul>
<s2 title="Samples to help you get started">
<p>Each of the subdirectories in the &xslt4j; java/samples directory contains the source files for one or more
- sample applications. The class files for the samples are in xalansamples.jar (everything except the servlet) and xalanservlet.jar, so to run the samples, you should place these JAR files on the system class path.</p>
+ sample applications. The class files for the samples are in xalansamples.jar (everything except the servlet) and xalanservlet.jar, so to run the samples, you should place these JAR files on the system classpath.</p>
<p>With most of the samples, you can use the following procedure:</p>
<ol>
<li>Be sure xalan.jar, xalansamples.jar (xalanservlet.jar for the servlet), and xerces.jar are on the system class
@@ -146,8 +146,8 @@
<li><link anchor="ext4">4-numlistJava</link></li>
<li><link anchor="ext5">5-numlistJScript</link></li>
</ul>
- <p>The extensions subdirectory contains 5 samples with &xslt4j; extensions. Two of the samples use
- extensions implemented in JavaScript, and thre of the samples use extensions implemented in Java.</p>
+ <p>The extensions subdirectory contains five samples with &xslt4j; extensions. Two of the samples use
+ extensions implemented in JavaScript, and three of the samples use extensions implemented in Java.</p>
<p>To run these examples, you must place bsf.jar and bsfengines.jar (distributed with &xslt4j;), and js.jar
(version 1.4 release 3, available from
<jump href="http://www.mozilla.org/rhino">http://www.mozilla.org/rhino</jump>) on the class path.
1.5 +28 -22 xml-xalan/java/xdocs/sources/xalan/whatsnew.xml
Index: whatsnew.xml
===================================================================
RCS file: /home/cvs/xml-xalan/java/xdocs/sources/xalan/whatsnew.xml,v
retrieving revision 1.4
retrieving revision 1.5
diff -u -r1.4 -r1.5
--- whatsnew.xml 2000/09/06 21:22:04 1.4
+++ whatsnew.xml 2000/09/12 21:41:09 1.5
@@ -74,18 +74,18 @@
<s2 title="New Design">
<p>&xslt4j2; represents a fundamental redesign of Xalan. It differs from &xslt4j; 1 in the following basic ways:</p>
<ul>
- <li>It is more modular<br/><br/>
- As the new package structure highlights, the production of runtime stylsheets, assembling efficient source tree representations, the application of stylesheets to source trees, the evaluation of XPath expressions and XSLT matching patterns, support for extension elements and extension functions, the processing of output, and cross-functional utilities have been much more clearly segmented and segregated than in &xslt4j; version 1.<br/><br/></li>
- <li>It implements the <jump href="http://trax.openxml.org/">TrAX (Transformations for XML)</jump> interfaces.
- <br/><br/>A number of developers in the vanguard of the open-source development of XML tools have collaborated on the TrAX design. TrAX represents a standard and vendor neutral API for performing an open-ended range of XML transformations. You can see the basic organization of TrAX in the example below.<br/><br/></li>
+ <li>It is more <link anchor="modules">modular</link>.<br/><br/>
+ As the new package structure highlights, the processing of stylesheets and production of stylesheet templates, the application of stylesheet templates to source trees and production of output trees, the evaluation of XPath expressions and XSLT matching patterns, and subsidiary operations and utilities are more clearly segmented and segregated than in &xslt4j; version 1.<br/><br/></li>
+ <li>It implements the <jump href="http://trax.openxml.org/">TRaX (Transformations for XML)</jump> interfaces.
+ <br/><br/>A number of open-source XML tool developers have collaborated on TRaX, a vendor-neutral API for performing an open-ended range of XML transformations. You can see the basic organization of TRaX in the example below.<br/><br/></li>
<li>It builds on the <jump href="http://www.megginson.com/SAX/Java/index.html">SAX 2</jump> and <jump href="http://www.w3.org/TR/DOM-Level-2/">DOM level 2</jump> interfaces.
-<br/><br/>For example, &xslt4j2; incorporates the SAX parsing event model in its support for the incremental streaming of transformation output, rather than waiting for the completion of the source tree to begin the transformation.<br/><br/></li>
- <li>TrAX and &xslt4j; gather critical configuration and implementation information from system property settings.<br/><br/>
+<br/><br/>For example, &xslt4j2; incorporates the SAX parsing event model in its support for the incremental production of transformation output.<br/><br/></li>
+ <li>TRaX and &xslt4j; gather critical operational information from system property settings.<br/><br/>
System properties, for example, identify the stylesheet processor and SAX parser to use, and the serializers that are available for various output methods.<br/><br/></li>
</ul>
</s2><anchor name="basic"/>
<s2 title="Basic steps">
- <p>The following simple example highlights the four basic steps involved in performing a transformation.</p>
+ <p>The following example highlights the four basic steps involved in performing a transformation.</p>
<source>// 1. Instantiate a stylesheet Processor.
trax.Processor processor = trax.Processor.newInstance("xslt");
@@ -94,17 +94,19 @@
(new org.xml.sax.InputSource("foo.xsl"));
// 3. Use the Templates object to instantiate a Transformer.
-trax.Transformer = templates.newTransformer();
+trax.Transformer transformer = templates.newTransformer();
-// 4. Use the Transformer to apply the Templates object to an XML source
-// and send the output to a Result object.
+// 4. Use the Transformer to apply the Templates object to an XML
+// source and send the output to a Result object.
transformer.transform
(new org.xml.sax.InputSource("foo.xml"),
new trax.Result(new java.io.FileWriter("foo.out")));</source>
- <note>For a working example of this simple model, see SimpleTransform.java in the java/samples/SimpleTransform subdirectory.</note>
+ <note>For a working example of this model at its simplest, see SimpleTransform.java in the java/samples/SimpleTransform subdirectory.</note>
</s2><anchor name="processor"/>
<s2 title="1. Instantiate a stylesheet Processor">
- <p>The trax.Processor static newInstance() method with "xslt" as its argument instantiates the processor designated by the trax.processor.xslt system property. If this system property has not already been set, trax.Processor sets it from a file. For &xslt4j;, this system property should be set to org.apache.xalan.processor.StylesheetProcessor.</p>
+ <p>The trax.Processor static newInstance() method with "xslt" as its argument instantiates the processor designated by the trax.processor.xslt system property.</p>
+ <p>If this system property has not already been set, trax.Processor sets it from a file.</p>
+ <p>For &xslt4j;, this system property should be set to org.apache.xalan.processor.StylesheetProcessor.</p>
</s2><anchor name="process"/>
<s2 title="2. Process the stylesheet, producing a Templates object">
<p>The Templates object is an immutable runtime representation of the structure and content of a stylesheet (which may include
@@ -112,18 +114,20 @@
<p>A given Templates object may be used repeatedly and by multiple concurrent threads for the transformation of XML input. Each Templates object also incorporates XSLTSchema, which encapsulates the underlying XSLT stylesheet schema.</p>
<p>You may provide the stylesheet as a SAX input source (from a file or stream) or as a DOM tree.</p>
<p>Use the Processor process() method with a SAX input source (as in the example above), or the processFromNode() method with a DOM tree to generate a Templates object.</p>
-<p>To perform this operation with a SAX input source, the processor uses a trax.TemplatesBuilder (extending the SAX ContentHandler interface) and a SAX XMLReader. The XMLReader parses the input, and the TemplatesBuilder builds the Templates object in response to SAX events from the XMLReader.</p>
-<note>Templates and TemplatesBuilder are TrAX interfaces, and XMLReader is a SAX interface. &xslt4j; uses org.apache.xalan.templates.StylesheetRoot to implement Templates, and org.apache.xalan.processor.StylesheetHandler to implement TemplatesBuilder. XMLReader is a SAX interface. The &xslt4j; StylesheetProcessor uses org.xml.sax.XMLReaderFactory to instantiate an XMLReader as designated by the org.xml.sax.driver system property. If you are using &xml4j;, this system property should be set to org.apache.xerces.parsers.SAXParser</note>
+<p>To perform this operation with a SAX input source, the processor uses a trax.TemplatesBuilder (extending the SAX ContentHandler interface) and a SAX XMLReader.</p>
+<p>The XMLReader parses the input, sending parse events to the TemplatesBuilder, which responds by building the Templates object.</p>
+<note>Templates and TemplatesBuilder are TRaX interfaces, and XMLReader is a SAX interface. &xslt4j; uses org.apache.xalan.templates.StylesheetRoot to implement Templates, and org.apache.xalan.processor.StylesheetHandler to implement TemplatesBuilder. XMLReader is a SAX interface. The &xslt4j; StylesheetProcessor uses org.xml.sax.XMLReaderFactory to instantiate an XMLReader as designated by the org.xml.sax.driver system property. If you are using &xml4j;, this system property should be set to org.apache.xerces.parsers.SAXParser</note>
<p>If you use the processFromNode() method with a DOM representation of the stylesheet, the processor uses org.apache.xalan.utils.TreeWalker to traverse the DOM, sending SAX events to the TemplatesBuilder.</p>
</s2><anchor name="transformer"/>
<s2 title="3. Instantiate a Transformer">
-<p>To transform an XML document, you need an implementation of the trax.Transformer interface. &xslt4j; implements the Transformer interface with org.apache.xalan.transformer.TransformerImpl.</p>
+<p>To transform an XML document, you need an implementation of the trax.Transformer interface.</p>
+<p>&xslt4j; implements the Transformer interface with org.apache.xalan.transformer.TransformerImpl.</p>
<p>You can use a Templates object for multiple transformations (even performed concurrently), but you should use the Templates object to instantiate a separate Transformer for each transformation you perform. The Templates object contains the stylesheet structure and data and XSLT schema, which are immutable, whereas the Transformer tracks state information as it performs the transformation.</p>
</s2><anchor name="transformation"/>
<s2 title="4. Perform a transformation">
<p>Supply the XML input, a target or "holder" for the transformation output, and instruct the Transformer to perform the transformation.</p>
<p>Just as with the stylesheet, you can supply the XML input in the form of a SAX input source (from a URL or stream) or a DOM tree.</p>
-<p>TrAX provides the holder for the output: trax.Result. You can set up a Result object to send the transformation result to a file or stream or to build a DOM tree.</p>
+<p>TRaX provides the holder for the output: trax.Result. You can set up a Result object to send the transformation result to a file or stream or to build a DOM tree.</p>
<p>The Transformer uses the SAX XMLParser to parse the XML input and sends parse events to an input SAX ContentHandler, org.apache.xalan.stree.SourceTreeHandler, which in turn uses org.apache.xalan.utils.DOMBuilder to assemble the input into a DOM tree. Of course this operation is unnecessary if the XML input is submitted as a DOM.</p>
<p>For each node in the XML source, the Transformer uses the Templates object and underlying XSLT schema to determine which template to apply: one of the templates in the Templates object, a default template rule as specified in the XSLT spec, or none.</p>
<p>The Transformer works with org.apache.xalan.transformer.ResultTreeHandler to forward the SAX events produced by this process to the appropriate output ContentHandler, a serializer if the Result object has been set up to write to a stream or file, a DOMBuilder utility if the output is to be a DOM tree.</p>
@@ -141,7 +145,7 @@
</gloss>
<gloss>
<label><jump href="apidocs/org/apache/xalan/transformer/package-summary.html">org.apache.xalan.transformer</jump></label>
- <item>The module that applies the Templates object to the XML source and produces the result tree.</item>
+ <item>Applies the Templates object to the XML source and produces the result tree.</item>
</gloss>
<gloss>
<label><jump href="apidocs/org/apache/xpath/package-summary.html">org.apache.xpath</jump></label>
@@ -154,7 +158,7 @@
</gloss>
<gloss>
<label><jump href="apidocs/org/apache/xalan/lib/package-summary.html">org.apache.xalan.lib</jump></label>
- <item>The &xslt4j; extensions library. To date this libary includes a Redirect extension, which allows a stylesheet to produce multiple output files, and a preliminary version of an SQL extension with which you can connect to and submit queries to a JDBC data source, and incrementally "stream" the result set into an XML target.</item>
+ <item>The &xslt4j; extensions library. To date this library includes a Redirect extension, which allows a stylesheet to produce multiple output files, and a preliminary version of an SQL extension with which you can connect to and submit queries to a JDBC data source, and incrementally "stream" the result set into an XML target.</item>
</gloss>
<gloss>
<label><jump href="apidocs/org/apache/xalan/trace/package-summary.html">org.apache.xalan.trace</jump></label>
@@ -170,7 +174,7 @@
</gloss>
<gloss>
<label><jump href="apidocs/org/apache/xalan/xslt/package-summary.html">org.apache.xalan.xslt</jump> and <jump href="apidocs/org/apache/xalan/xpath/package-summary.html">org.apache.xalan.xpath</jump></label>
- <item>For compatability, these packages provide an &xslt4j; 1 interface to &xslt4j2;</item>
+ <item>For compatibility, these packages provide an &xslt4j; 1 interface to &xslt4j2;</item>
</gloss>
</s2><anchor name="params"/>
<s2 title="Setting stylesheet parameters">
@@ -179,10 +183,12 @@
<p><code>java org.apache.xalan.xslt.Process -in foo.xml -xsl foo.xsl -param param1 boo</code></p>
<p>or</p>
<p><code>java org.apache.xalan.xslt.Process -in foo.xml -xsl foo.xsl -param param1 org/myorg/xyz boo</code></p>
-<p>where <code>org/myorg/xyz</code> is the paramater namespace. [not yet working]</p>
+<p>where <code>org/myorg/xyz</code> is the parameter namespace. [not yet working]</p>
</s2><anchor name="sax"/>
<s2 title="SAX">
- <p>&xslt4j; uses the SAX event model to process stylesheets, to parse XML input documents, and to produce output. For each of these operations, an XMLReader reads input, firing parse events, and a ContentHandler listens to the XMLReader and performs parse event methods. When you use the "basic" procedure for performing transformations illustrated above, &xslt4j; takes care of many of the SAX details under the covers. You are free to make these details explicit, which simply means that you can intervene in the procedure to accommodate the specific conditions in which your application operates. Suppose, for example, you are using a custom XMLReader (perhaps doing something beyond simply parsing existing static XML documents) to feed &xslt4j; SAX parse events. You can instruct the Transformer to provide the ContentHandler for this XMLReader. You might even have a custom reader for producing/processing stylesheets, in which case you simply set the trax.TemplatesBuilder (implemented by the org.apache.xalan.p
rocessor.StylesheetHandler) as the ContentHandler for this reader.</p>
+ <p>&xslt4j; uses the SAX event model to process stylesheets, to parse XML input documents, and to produce output. For each of these operations, an XMLReader reads input, firing parse events, and a ContentHandler listens to the XMLReader and performs parse event methods.</p>
+<p>When you use the "basic" procedure for performing transformations illustrated above, &xslt4j; takes care of many of the SAX details under the covers. You are free to make these details explicit, which simply means that you can intervene in the procedure to accommodate the specific conditions in which your application operates.</p>
+<p>Suppose, for example, you are using a custom XMLReader (perhaps doing something beyond simply parsing existing static XML documents) to feed &xslt4j; SAX parse events. You can instruct the Transformer to provide the ContentHandler for this XMLReader. You might even have a custom reader for producing/processing stylesheets, in which case you simply set the trax.TemplatesBuilder (implemented by the org.apache.xalan.processor.StylesheetHandler) as the ContentHandler for this reader.</p>
<p>The following example replicates the <link anchor="basic">Basic 4 steps</link> described above</p>
<source>// 1. Instantiate stylesheet processor.
trax.Processor processor = trax.Processor.newInstance("xslt");
@@ -231,7 +237,7 @@
</s2><anchor name="dom"/>
<s2 title="DOM">
<p>In some cases, the input and/or desired output for a transformation may be a DOM tree object, rather than a file or stream.</p>
-<p>To process DOM input, use one of the trax.Transformer <jump href="apidocs/trax/Transformer.html#transformNode(org.w3c.dom.Node, trax.Result)">transformNode()</jump> methods. [What are the restrictions (hopefully none) on which implementation of the DOM interface can be used.]</p>
+<p>To process DOM input, use one of the trax.Transformer <jump href="apidocs/trax/Transformer.html#transformNode(org.w3c.dom.Node, trax.Result)">transformNode()</jump> methods.</p>
<p>To produce a transformation result in the form of a DOM tree, use the <jump href="http://java.sun.com/xml/docs/api/index.html">Java API for XML Parsing</jump> as indicated below to instantiate an empty DOM Document to hold the result tree.</p>
<ol>
<li>The javax.xml.parsers.DocumentBuilderFactory abstract class contains a static newInstance() method for instantiating a factory designated by the javax.xml.parsers.DocumentBuilderFactory system property.<br/><br/></li>