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>
