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/03/01 19:24:36 UTC
cvs commit: xml-xalan/xdocs/sources/xalan commandline.xml extensions.xml faq.xml javadocOverview.xml overview.xml resources.xml samples.xml usagepatterns.xml
dleslie 00/03/01 10:24:36
Modified: xdocs/sources xalan.xml xalanLocal.xml
xdocs/sources/xalan commandline.xml extensions.xml faq.xml
javadocOverview.xml overview.xml resources.xml
samples.xml usagepatterns.xml
Log:
Editorial fixes per review comments and expanded restrictions (maybe) on DTMLiaison.
Revision Changes Path
1.3 +7 -1 xml-xalan/xdocs/sources/xalan.xml
Index: xalan.xml
===================================================================
RCS file: /home/cvs/xml-xalan/xdocs/sources/xalan.xml,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -r1.2 -r1.3
--- xalan.xml 2000/02/25 19:41:49 1.2
+++ xalan.xml 2000/03/01 18:24:32 1.3
@@ -76,7 +76,13 @@
label="Getting Started"
source="xalan/getstarted.xml"/>
<separator/>
-
+
+ <faqs id="faq"
+ label="FAQs"
+ source="xalan/faq.xml" />
+
+ <separator/>
+
<document id="samples"
label="Sample Apps"
1.5 +6 -0 xml-xalan/xdocs/sources/xalanLocal.xml
Index: xalanLocal.xml
===================================================================
RCS file: /home/cvs/xml-xalan/xdocs/sources/xalanLocal.xml,v
retrieving revision 1.4
retrieving revision 1.5
diff -u -r1.4 -r1.5
--- xalanLocal.xml 2000/02/25 19:41:49 1.4
+++ xalanLocal.xml 2000/03/01 18:24:32 1.5
@@ -71,8 +71,14 @@
<document id="getstarted"
label="Getting Started"
source="xalan/getstarted.xml"/>
+
<separator/>
+ <faqs id="faq"
+ label="FAQs"
+ source="xalan/faq.xml" />
+
+ <separator/>
<document id="samples"
label="Sample Apps"
1.6 +22 -24 xml-xalan/xdocs/sources/xalan/commandline.xml
Index: commandline.xml
===================================================================
RCS file: /home/cvs/xml-xalan/xdocs/sources/xalan/commandline.xml,v
retrieving revision 1.5
retrieving revision 1.6
diff -u -r1.5 -r1.6
--- commandline.xml 2000/02/29 19:55:09 1.5
+++ commandline.xml 2000/03/01 18:24:32 1.6
@@ -78,30 +78,28 @@
<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:</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>
+ <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>
1.5 +3 -2 xml-xalan/xdocs/sources/xalan/extensions.xml
Index: extensions.xml
===================================================================
RCS file: /home/cvs/xml-xalan/xdocs/sources/xalan/extensions.xml,v
retrieving revision 1.4
retrieving revision 1.5
diff -u -r1.4 -r1.5
--- extensions.xml 2000/02/29 19:55:09 1.4
+++ extensions.xml 2000/03/01 18:24:33 1.5
@@ -107,8 +107,9 @@
<lxslt:component prefix="my-ext" elements="timelapse" functions="getdate">
<lxslt:script lang="javascript">
var multiplier=1;
- // The methods or functions that implement extension elements always take two arguments.
- // The first argument is the XSL Processor context; the second argument is the element node.
+ // The methods or functions that implement extension elements always take 2
+ // arguments. The first argument is the XSL Processor context; the second
+ // argument is the element node.
function timelapse(xslProcessorContext, elem)
{
multiplier=parseInt(elem.getAttribute("multiplier"));
1.4 +131 -7 xml-xalan/xdocs/sources/xalan/faq.xml
Index: faq.xml
===================================================================
RCS file: /home/cvs/xml-xalan/xdocs/sources/xalan/faq.xml,v
retrieving revision 1.3
retrieving revision 1.4
diff -u -r1.3 -r1.4
--- faq.xml 2000/02/29 19:55:09 1.3
+++ faq.xml 2000/03/01 18:24:33 1.4
@@ -2,21 +2,145 @@
<!DOCTYPE faqs SYSTEM "sbk:/style/dtd/faqs.dtd">
<faqs title="Frequently asked questions">
+
+ <faq title="Where do I go to learn about XSLT">
+ <q>Where do I go to learn about XSLT?</q>
+
+ <a><p>The definitive sources are the W3C XSLT and XPath recommendations: <resource-ref idref="XSLT"/> and
+ <resource-ref idref="XPath"/>.</p>
+ <p>For general questions not specific to &xslt4j;, see Dave Pawson's <jump
+ href="http://freespace.virgin.net/b.pawson/xsl/index.html#top">XSL Frequently Asked Questions</jump>.</p>
+ <p>For a brief listing of tutorials, discussion forums, and other materials, see <link idref="overview"
+ anchor="uptospeed">Getting up to speed with XSLT</link>.</p></a>
+ </faq>
+
+ <faq title="Which version of Xerces should I be using?">
+ <q>Which version of Xerces should I be using?</q>
+
+ <a><p>The &xslt4j; release notes includes information about the Xerces release with which the &xslt4j; release has
+ been coordinated and tested. See <link idref="readme" anchor="status">Status</link></p></a>
+ </faq>
+
+ <faq title="Are there any shortcuts for using a transformation result as input for another transformation?">
+
+ <q>Are there any shortcuts for using a transformation result as input for another transformation?</q>
+
+ <a><p>You can always get a transformation result from the <resource-ref idref="XSLTOutputTargetDoc"/> object,
+ and use it to set an <resource-ref idref="XSLTInputSourceDoc"/> object for another transformation, but yes, there is a
+ shortcut. Basically, you want to set up the XSLTResultTarget object
+ that receives the output from the first transformation (performed with the XML source, the first stylesheet, and the first
+ <resource-ref idref="XSLTProcessorDoc"/> object) to function as a SAX DocumentHandler in conjunction with a second
+ XSLTProcessor object that uses the second stylesheet and also functions as a DocumentHandler.</p>
+ <p>To walk through a brief example, see <link idref="usagepatterns" anchor="sax">Generating and responding to
+ SAX events</link></p>.</a>
+ </faq>
+
+ <faq title="Why do XSLTProcessor and StylesheetRoot both have process() methods to perform transformations?">
+
+ <q>Why do XSLTProcessor and StylesheetRoot both have process() methods to perform transformations?</q>
+
+ <a><p>To perform a transformation, &xslt4j; uses XML input, an XSL stylesheet, and XSLTProcessor. In one scenario, you use
+ <resource-ref idref="XSLTInputSourceDoc"/> objects as containers for the XML input and the XSL stylesheet. To perform the
+ transformation, the <resource-ref idref="XSLTProcessorDoc"/> object "compiles" the stylesheet, producing a <resource-ref
+ idref="StylesheetRootDoc"/> object, but you the user have no direct interaction with the StylesheetRoot.</p>
+ <p>Example:</p>
+ <source>import org.apache.xalan.xslt.*;
+ ...
+ XSLTProcessor proc = XSLTProcessorFactory.getProcessor();
+ proc.process(new XSLTInputSource("foo.xml"),
+ new XSLTInputSource("foo.xsl"),
+ new XSLTOutputTarget("foo.out");</source>
+ <p>Second scenario: you want to perform a number of transformations with the same stylesheet. To improve performance, you
+ compile the stylesheet once, and use the resulting <resource-ref idref="StylesheetRootDoc"/> object for each
+ transformation.</p>
+ <p>You can use the <jump href="apidocs/org/apache/xalan/xslt/XSLTProcessor.html#process(org.apache.xalan.xslt.XSLTInputSource,org.apache.xalan.xslt.XSLTInputSource,org.apache.xalan.xslt.XSLTOutputTarget)">
+ XSLTProcessor process()</jump> method with a compiled stylesheet. For an example, see <link idref="usagepatterns"
+ anchor="compiled">Compiling stylesheets</link>. But an XSLTProcessor object is not thread-safe and must be
+ reset between transformations. A StylesheetRoot object, on the other hand, is thread-safe and may even be used concurrently
+ (running in a servlet, for example) to perform multiple transformations, so it is more straightforward to use the
+ <jump href="apidocs/org/apache/xalan/xslt/StylesheetRoot.html#process(org.apache.xalan.xslt.XSLTInputSource,org.apache.xalan.xslt.XSLTOutputTarget)">
+ StylesheetRoot process()</jump> method to perform the transformations.</p>
+ <p>Example:</p>
+ <source>import org.apache.xalan.xslt.*;
+ ...
+ // Pass in an array of XML input file names and an
+ // "uncompiled" stylesheet file name.
+ public multiTransform(String[] xmlInputFiles, String xslFile)
+ {
+ XSLTProcessor proc = XSLTProcessor.Factory.getProcessor();
+ StylesheetRoot style = proc.ProcessStylesheet
+ (new XSLTInputSource(xslFile));
+ for (int i = 0; i < xmlInputFiles.length; i++)
+ {
+ style.process(new XSLTInputSource(xmlInputFiles[i],
+ new XSLTResultTarget(xmlInputFiles[i] + ".out"));
+ }
+ }
+ ...</source>
+ </a>
+ </faq>
+
+ <faq title="What can I do to speed up transformations?">
+
+ <q>What can I do to speed up transformations?</q>
+
+ <a><ul>
+ <li>Use the DTM liaison and XML parser.</li>
+ <li>Use compiled stylesheets.</li>
+ <li>Set the XSLTProcessor to function as a SAX DocumnetHandler, and respond to SAX events rather than waiting for
+ the entire transformation to be completed.</li>
+ <li>Set up your stylesheets to function efficiently.See ???</li>
+ </ul></a>
+ </faq>
+
+ <faq title="I'm getting a NoClassDefFound error. What has to be on the class path?">
+
+ <q>I'm getting a NoClassDefFound error. What has to be on the class path?</q>
+
+ <a><ol>
+ <li>xalan.jar must always be on the class path.<br/><br/></li>
+ <li>Unless you have set up an extension of <resource-ref idref=" XMLParserLiaisonDefaultDoc"/> to work with another XML
+ parser, xerces.jar must be on the class path.<br/><br/></li>
+ <li>To run the samples in the samples subdirectories, xalansamples.jar must be on the class path. To run the servlet (in
+ samples/servlet), 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.<br/><br/></li>
+ <li>To run extensions (including the samples in samples/extensions), bsf.jar, and bsfengines.jar must be on the
+ class path. To run extensions implemented in JavaScript, js.jar must also be on the class path. For information on what
+ you need to run extensions implemented in other scripting languages, see <link idref="extensions"
+ anchor="supported-lang">Supported languages</link>.<br/><br/></li>
+ </ol>
+ <p>For more information, see <link idref="getstarted" anchor="classpath">Setting up the system class path</link>.</p></a>
+ </faq>
+
<faq title="Using the right liaison and XML parser">
+
<q>How do I fix "DTMLiaison can not handle nodes of typeclass org.apache.xerces.dom.DocumentImpl"?</q>
- <a><p>Instantiate your processor as follows so that it will use XercesLiaison:</p>
+
+ <a><p>You are using the default DTM liaison and XML parser, but your input or output is a DOM. The high-performance DTM
+ (Document Table Model) provides a "pseudo-DOM" representation of DOM trees and can read and write URLS, files, and streams,
+ but not DOMs.</p>
+ <p>The fix? Instantiate your processor as follows so that it will use XercesLiaison and the Xerces XML parser:</p>
<source>org.apache.xalan.xslt.XSLTProcessor processor =
- org.apache.xalan.xslt.XSLTProcessorFactory.getProcessor(new
- org.apache.xalan.xpath.xdom.XercesLiaison());</source>
+ org.apache.xalan.xslt.XSLTProcessorFactory.getProcessor
+ (new org.apache.xalan.xpath.xdom.XercesLiaison());</source>
</a>
</faq>
+
<faq title="Stylesheet validation">
<q>How do I validate an XSL stylesheet?</q>
<a>
<p>An XSL stylesheet is an XML document, so it can have a DOCTYPE and be subject to validation, right? </p>
- <p>The XSLT Recommendation includes a <jump href="http://www.w3.org/TR/1999/REC-xslt-19991116.html#dtd">DTD Fragment
- for XSL Stylesheets</jump>.</p>
- <p>say something about <!DOCTYPE xsl:stylesheet SYSTEM "xsl-html40s.dtd"></p>
+ <p>The XSLT Recommendation includes a <jump href="http://www.w3.org/TR/xslt#dtd">DTD Fragment
+ for XSL Stylesheets</jump> with some indications of what you need to do to create a complete DTD for a given
+ stylesheet. Keep in mind that stylesheets can include literal result elements and produce output that is not valid
+ XML.</p>
+ <p>Say something (but what?) about <!DOCTYPE xsl:stylesheet SYSTEM "xsl-html40s.dtd"></p>
</a>
- </faq>
+ </faq>
+
+ <faq title="How do I output strings with tags (<xxx/>) to HTML?">
+ <q>How do I publish stings with tags (<, >) to HTML?</q>
+ <a><p>When outputting special characters, such as < , &, and >, use literal result elements, CDATA, or escape
+ sequences.</p></a>
+ </faq>
</faqs>
1.4 +1 -1 xml-xalan/xdocs/sources/xalan/javadocOverview.xml
Index: javadocOverview.xml
===================================================================
RCS file: /home/cvs/xml-xalan/xdocs/sources/xalan/javadocOverview.xml,v
retrieving revision 1.3
retrieving revision 1.4
diff -u -r1.3 -r1.4
--- javadocOverview.xml 2000/02/29 19:55:09 1.3
+++ javadocOverview.xml 2000/03/01 18:24:33 1.4
@@ -60,7 +60,7 @@
<s1 title="API Overview">
<s2 title="API Summary">
- <p>&xslt4j; implements the <resource-ref idref="xsl-draft-used"/>.</p>
+ <p>&xslt4j; implements the <resource-ref idref="XSLT"/>.</p>
</s2>
<s2 title="Description">
<p>XLST is a stylesheet language for transforming XML documents into other XML documents, HTML documents,
1.8 +3 -3 xml-xalan/xdocs/sources/xalan/overview.xml
Index: overview.xml
===================================================================
RCS file: /home/cvs/xml-xalan/xdocs/sources/xalan/overview.xml,v
retrieving revision 1.7
retrieving revision 1.8
diff -u -r1.7 -r1.8
--- overview.xml 2000/02/29 19:55:09 1.7
+++ overview.xml 2000/03/01 18:24:33 1.8
@@ -67,9 +67,9 @@
<li><link anchor="glossary">Glossary</link></li>
</ul><anchor name="intro"/>
<s2 title="Introduction">
- <p>&xslt4j; (named after a rare musical instrument) fully implements the <resource-ref idref="xsl-draft-used"/>.
+ <p>&xslt4j; (named after a rare musical instrument) fully implements the <resource-ref idref="XSLT"/>.
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,
+ <resource-ref idref="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 vocabulary for formatting documents, which is still under design and is not part of &xslt4j;.
@@ -99,7 +99,7 @@
</s2><anchor name="features"/>
<s2 title="&xslt4j; Features">
<ul>
- <li>Implements the <resource-ref idref="xsl-draft-used"/></li>
+ <li>Implements the <resource-ref idref="XSLT"/></li>
<li>Incorporates the <resource-ref idref="XPath"/></li>
<li>Optionally uses the high-performance DTM (Document Table Model) to avoid the object overhead involved in the
construction and manipulation of DOM trees</li>
1.6 +2 -3 xml-xalan/xdocs/sources/xalan/resources.xml
Index: resources.xml
===================================================================
RCS file: /home/cvs/xml-xalan/xdocs/sources/xalan/resources.xml,v
retrieving revision 1.5
retrieving revision 1.6
diff -u -r1.5 -r1.6
--- resources.xml 2000/02/29 19:55:09 1.5
+++ resources.xml 2000/03/01 18:24:33 1.6
@@ -28,11 +28,10 @@
<resource id="Demo" title="Xalan Browser Demo" location="http://xml.apache.org/xalan/XMLViewer.htm"/>
- <resource id="xsl-draft-used" title="W3C Recommendation 16 November 1999 XSL Transformations (XSLT) Version 1.0" location="http://www.w3.org/TR/1999/REC-xslt-19991116"/>
+ <resource id="XSLT" title="W3C Recommendation 16 November 1999 XSL Transformations (XSLT) Version 1.0" location="http://www.w3.org/TR/xslt"/>
<resource id="XPath" title="XML Path Language (XPath) Version 1.0" location="http://www.w3.org/TR/xpath"/>
-
- <resource id="xsl-draft-latest" title="XSLT World Wide Web Consortium (W3C) XSL Transformations (XSLT) Specification" location="http://www.w3.org/TR/WD-xslt"/>
+
<resource id="DOM-draft-august" title="August 18 Document Object Model (DOM) Level 1 Specification" location="http://www.w3.org/TR/1998/PR-DOM-Level-1-19980818/"/>
<resource id="DOM-draft-october" title="October 1 Document Object Model (DOM) Level 1 Specification" location="http://www.w3.org/TR/1998/REC-DOM-Level-1-19981001"/>
<resource id="DOM" title="DOM" location="http://www.w3.org/DOM"/>
1.7 +5 -4 xml-xalan/xdocs/sources/xalan/samples.xml
Index: samples.xml
===================================================================
RCS file: /home/cvs/xml-xalan/xdocs/sources/xalan/samples.xml,v
retrieving revision 1.6
retrieving revision 1.7
diff -u -r1.6 -r1.7
--- samples.xml 2000/02/29 19:55:09 1.6
+++ samples.xml 2000/03/01 18:24:33 1.7
@@ -93,8 +93,8 @@
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 <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>
+ (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 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
@@ -131,9 +131,10 @@
<p>Examples:</p>
<gloss>
<label>http://localhost/servlet/DefaultApplyXSL?URL=/data.xml&xslURL=/style.xsl</label>
-<item>...applies the style.xsl stylesheet to the data.xml data. Both files are
+<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>
-<label>http://localhost/servlet/DefaultApplyXSL?URL=/data.xml&xslURL=/style.xsl&debug=true</label>
+<label>http://localhost/servlet/DefaultApplyXSL?URL=/data.xml&xslURL=
+/style.xsl&debug=true</label>
<item>...ensures that XML and XSL processor messages are returned in the event of problems
applying style.xsl to data.xml<br/><br/></item>
<label>http://localhost/servlet/DefaultApplyXSL/data.xml?xslURL=/style.xsl</label>
1.5 +3 -1 xml-xalan/xdocs/sources/xalan/usagepatterns.xml
Index: usagepatterns.xml
===================================================================
RCS file: /home/cvs/xml-xalan/xdocs/sources/xalan/usagepatterns.xml,v
retrieving revision 1.4
retrieving revision 1.5
diff -u -r1.4 -r1.5
--- usagepatterns.xml 2000/02/29 19:55:09 1.4
+++ usagepatterns.xml 2000/03/01 18:24:34 1.5
@@ -132,7 +132,8 @@
<source>import org.apache.xalan.xslt.*;
...
XSLTProcessor processor = XSLTProcessorFactory.getProcessor();
-StylesheetRoot style = processor.processStylesheet(new XSLTInputSource("foo.xsl"));
+StylesheetRoot style = processor.processStylesheet
+ (new XSLTInputSource("foo.xsl"));
processor.setStylesheet(style); // Good form!
...
processor.process(new XSLTInputSource("foo.xml"),
@@ -145,6 +146,7 @@
StylesheetRoot style = processor.processStylesheet(new XSLTInputSource("foo.xsl"));
...
style.process(new XSLTInputSource("foo.xml"), new XSLTOutputTarget("foo.out"));</source>
+<p>You should use the StylesheetRoot process() method if you are using a StylesheetRoot object to transform multiple XML sources.</p>
<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">