dleslie 00/08/28 14:01:47
Modified: java/xdocs/sources xalan-jlocal.xml
java/xdocs/sources/xalan whatsnew.xml
Added: java/xdocs/sources/xalan commandline.xml samples.xml
Log:
partial 1st drafts
Revision Changes Path
1.2 +5 -1 xml-xalan/java/xdocs/sources/xalan-jlocal.xml
Index: xalan-jlocal.xml
===================================================================
RCS file: /home/cvs/xml-xalan/java/xdocs/sources/xalan-jlocal.xml,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- xalan-jlocal.xml 2000/08/28 18:16:14 1.1
+++ xalan-jlocal.xml 2000/08/28 21:01:37 1.2
@@ -68,11 +68,15 @@
label="Sample Apps"
source="xalan/samples.xml"/>
+ <document id="commandline"
+ label="Command Line"
+ source="xalan/commandline.xml"/>
+
<separator/>
<external href="apidocs/index.html" label="API (Javadoc)"/>
<separator/>
- <external href="http://xml.apache.org/bugs/"; label="Bug reporting"/>
+<external href="http://xml.apache.org/xalan/design/design2_0_0.html";
label="Xalan 2 Design"/>
</book>
1.2 +12 -10 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.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- whatsnew.xml 2000/08/28 18:15:35 1.1
+++ whatsnew.xml 2000/08/28 21:01:44 1.2
@@ -58,16 +58,18 @@
-->
<s1 title="What's new in &xslt4j2;">
<ul>
-<li><link anchor="design">New Design</link></li>
-<li><link anchor="basic">Basic 4 steps</link></li>
-<li><link anchor="processor">1. Instantiate stylesheet Processor</link></li>
-<li><link anchor="process">2. Process stylesheet</link></li>
-<li><link anchor="transformer">3. Instantiate Transformer</link></li>
-<li><link anchor="transformation">4. Perform transformation</link></li>
-<li><link anchor="modules">Modularity</link></li>
-<li><link anchor="sax">SAX</link></li>
-<li><link anchor="params">Setting stylesheet parameters</link></li>
-<li><link anchor="dom">DOM</link></li>
+ <li><link anchor="design">New Design</link></li>
+ <li><link anchor="basic">Basic 4 steps</link></li>
+ <ol>
+ <li><link anchor="processor">Instantiate stylesheet Processor</link></li>
+ <li><link anchor="process">Process stylesheet</link></li>
+ <li><link anchor="transformer">Instantiate Transformer</link></li>
+ <li><link anchor="transformation">Perform transformation</link></li>
+ </ol>
+ <li><link anchor="modules">Modularity</link></li>
+ <li><link anchor="sax">SAX</link></li>
+ <li><link anchor="params">Setting stylesheet parameters</link></li>
+ <li><link anchor="dom">DOM</link></li>
</ul><anchor name="design"/>
<s2 title="New Design">
<p>&xslt4j2; represents a fundamental redesign of Xalan. It differs from
&xslt4j; 1 in the following basic ways:</p>
1.1 xml-xalan/java/xdocs/sources/xalan/commandline.xml
Index: commandline.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 [EMAIL PROTECTED]
*
* 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 IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED
* WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
* OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
* DISCLAIMED. IN NO EVENT SHALL THE APACHE SOFTWARE FOUNDATION OR
* ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
* SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
* LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
* USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
* ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
* OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
* OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
* SUCH DAMAGE.
* ====================================================================
*
* 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="Command-Line Utility">
<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 <link
idref="usagepatterns">Usage Patterns</link>).</p>
<p>The org.apache.xalan.xslt.Process main() method provides a
command-line interface
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>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
stylesheet, and the output file:<br/><br/>
<code>java org.apache.xalan.xslt.Process -IN foo.xml -XSL foo.xsl -OUT
foo.out</code>
</li></ol>
<p>The command line utility can take the following flags and arguments
(the flags are case insensitive):</p>
<source>-IN inputXMLURL
-XSL XSLTransformationURL
-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)
-LF (Use linefeeds only on output -- default is CR/LF)
-CR (Use carriage returns only on output -- default is CR/LF)
-INDENT (Number of spaces to indent each level in output tree --default is 0)
-TT (Trace the templates as they are being called)
-TG (Trace each result tree generation event)
-TS (Trace each selection event)
-TTC (Trace the template children as they are being processed)
-VALIDATE (Validate the XML and XSL input -- validation is off by default)
-EDUMP [optional]FileName (Do stackdump on error)
-XML (Use XML formatter and add XML header)
-TEXT (Use simple Text formatter)
-HTML (Use HTML formatter)
-PARAM name expression (Set a stylesheet parameter)</source>
<p>Use -IN to specify the XML source document.</p>
<p>Use -XSL to specify the XSL stylesheet file.</p>
<p>Use -LXCIN to specify a compiled XSL stylesheet file.</p>
<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
not well formed XML.</p>
<p>To set stylesheet parameters from the command line, use <br/>
<code>TestXSLT -PARAM <ref>name expression</ref></code><br/>
To set the parameter to a string value, enclose the string in single
quotes (') to
make it an expression.</p>
<p><anchor name="compiledstylesheet"/><em>Using a compiled
stylesheet</em></p>
<p>If you are using a stylesheet repeatedly, you can improve
performance by compiling the stylesheet the first time
you use it and using the compiled stylesheet for subsequent
transformations.</p>
<p>For example, the following command line performs a transformation
and compiles the stylesheet:"<br/><br/>
<code>java org.apache.xalan.xslt.Process -in foo.xml -xsl foo.xsl
-lxcout foo.style</code><br/><br/>
The following command line uses the compiled stylesheet for the next
transformation:<br/><br/>
<code>java org.apache.xalan.xslt.Process -in foo2.xml -lxcin
foo.style</code></p>
</s2>
</s1>
1.1 xml-xalan/java/xdocs/sources/xalan/samples.xml
Index: samples.xml
===================================================================
<?xml version="1.0" standalone="no"?>
<!--
* 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 [EMAIL PROTECTED]
*
* 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 IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED
* WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
* OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
* DISCLAIMED. IN NO EVENT SHALL THE APACHE SOFTWARE FOUNDATION OR
* ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
* SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
* LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
* USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
* ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
* OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
* OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
* SUCH DAMAGE.
* ====================================================================
*
* 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/>.
-->
<!DOCTYPE s1 SYSTEM "sbk:/style/dtd/document.dtd">
<s1 title="&xslt4j2; Samples">
<ul>
<li><link anchor="simpletransform">SimpleTransform</link></li>
<li><link anchor="transformtodom">TransformToDom</link></li>
<li><link anchor="usestylesheetparam">UseStylesheetParam</link></li>
<li><link anchor="sax2sax">SAX2SAX</link></li>
<li><link anchor="pipe">Pipe</link></li>
<li><link anchor="appletxmltohtml">AppletXMLtoHTML</link></li>
<li><link anchor="servlet">Servlet</link></li>
<li><link anchor="extensions">Extensions</link></li>
</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>
<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
path. For the extension examples, bsf.jar, bsfengines.jar, and (for the
JavaScript extensions) js.jar must also be on the class
path.</li>
<li>Be sure the java executable 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>
</ol>
<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 xxx 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
processing.</p>
<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 (a string of your
choice).</p>
</s2><anchor name="sax2sax"/>
<s2 title="SAX2SAX">
<p>What it does: Explicitly set the SAX XMLReader and SAX ContentHandler
for processing the stylesheet, processing the XML input, and producing the
output.</p>
<p>Run this sample from the Pipe subdirectory with</p>
<p><code>java SAX2SAX</code></p>
</s2><anchor name="pipe"/>
<s2 title="Pipe">
<p>What it does: Chains together a series of 3 transformations by piping
SAX events from one Transformer to
another. Each Transformer operates as a SAX2 XMLFilter/XMLReader.</p>
<p>Run this sample from the Pipe subdirectory with</p>
<p><code>java Pipe</code></p>
</s2><anchor name="appletxmltohtml"/>
<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/appletXMLtoHTML/readme.html">sample applet readme</jump>.</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>
<ol>
<li>Configure your application server (Websphere or JServ, for example)
so it can find the classes (in
xalanservlet.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>
</ol>
</s2><anchor name="extensions"/>
<s2 title="Extensions">
<ul>
<li><link anchor="ext1">SimpleRedirect</link></li>
<li><link anchor="ext2">2-basicJscript</link></li>
<li><link anchor="ext3">3-java-namespace</link></li>
<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>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.
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 most of 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 written 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
line):</p>
<anchor name="ext1"/>
<s3 title="SimpleRedirect">
<p>What it does: Uses the Redirect extension elements shipped with
&xslt4j; to direct output to two output
files.</p>
<p>Run this sample from the extensions subdirectory with</p>
<p><code>java SimpleRedirect</code></p>
</s3><anchor name="ext2"/>
<s3 title="2-basicJscript">
<p>What it does: Uses an extension element and extension function
implemented in Javascript.</p>
<p>Run this sample from the extensions subdirectory with</p>
<p><code>java org.apache.xalan.xslt.Process -in
2-basicJscript.xml</code>
<br/> <code>-xsl 2-jbasicJscript.xsl</code></p>
</s3><anchor name="ext3"/>
<s3 title="3-java-namespace">
<p>What it does: Uses extension functions to format dates. This sample
illustrates use of the predefined java
extension namespace to provide ready access to extensions implemented
in Java.</p>
<p>Run this sample from the extensions subdirectory with</p>
<p><code>java org.apache.xalan.xslt.Process -in
3-java-namespace.xml</code>
<br/> <code>3-java-namespace.xsl</code></p>
</s3><anchor name="ext4"/>
<s3 title="4-numlistJava">
<p>What it does: Uses a Java extension to transform a set of name
elements into an alphabetical and numbered
list.</p>
<p>Run this sample from the extensions subdirectory with</p>
<p><code>java org.apache.xalan.xslt.Process -in
4-numlistJava.xml</code>
<br/> <code>-xsl 4-numlistJava.xsl</code></p>
</s3><anchor name="ext5"/>
<s3 title="5-numlistJscript">
<p>What it does: Uses a Javascript extension to transform a set of
name elements into an alphabetical and
numbered list. This sample performs the same operations as the
preceding Java extension.</p>
<p>Run this sample from the extensions subdirectory with</p>
<p><code> java org.apache.xalan.xslt.Process -in 5-numlistJscript.xml
</code>
<br/> <code>-xsl 5-numlistJscript.xsl</code></p>
</s3>
</s2>
</s1>
