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/06/02 20:40:41 UTC
cvs commit: xml-xalan/c/xdocs/sources/xalan BUGS STATUS commandline.xml extensions.xml faq.xml getstarted.xml index.xml overview.xml readme.xml resources.xml samples.xml usagepatterns.xml
dleslie 00/06/02 11:40:40
Modified: c/xdocs/sources entities.ent xalan.xml xalanLocal.xml
c/xdocs/sources/xalan BUGS STATUS commandline.xml
extensions.xml faq.xml getstarted.xml index.xml
overview.xml readme.xml resources.xml samples.xml
usagepatterns.xml
Log:
Doc for upcoming release of Xalan-C
Revision Changes Path
1.2 +7 -6 xml-xalan/c/xdocs/sources/entities.ent
Index: entities.ent
===================================================================
RCS file: /home/cvs/xml-xalan/c/xdocs/sources/entities.ent,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- entities.ent 2000/05/08 19:23:01 1.1
+++ entities.ent 2000/06/02 18:40:31 1.2
@@ -1,12 +1,13 @@
<?xml encoding="US-ASCII"?>
-<!ENTITY xslt4j "Xalan-J">
-<!ENTITY xml4j "Xerces-J">
-<!ENTITY xslt4c "Xalan-C">
-<!ENTITY xml4c "Xerces-C">
+<!ENTITY xslt4j "Xalan-Java">
+<!ENTITY xml4j "Xerces-Java">
+<!ENTITY xslt4c "Xalan-C++">
+<!ENTITY xslt4c-current "Xalan-C++ version 0.40.0">
+<!ENTITY xml4c "Xerces-C++">
+<!ENTITY xml4c-used "Xerces-C++ version 1.2.0">
+<!ENTITY icu-used "International Components for Unicode(ICU) 1.4.1.2 source files">
<!ENTITY done SYSTEM "sbk:/sources/xalan/DONE">
<!ENTITY status SYSTEM "sbk:/sources/xalan/STATUS">
<!ENTITY bugs SYSTEM "sbk:/sources/xalan/BUGS">
-
-<!ENTITY download "The Xalan download from xml.apache.org includes xerces-c_1_1.dll.">
1.2 +4 -4 xml-xalan/c/xdocs/sources/xalan.xml
Index: xalan.xml
===================================================================
RCS file: /home/cvs/xml-xalan/c/xdocs/sources/xalan.xml,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- xalan.xml 2000/05/08 19:23:01 1.1
+++ xalan.xml 2000/06/02 18:40:31 1.2
@@ -58,7 +58,7 @@
* <http://www.apache.org/>.
-->
-<book title="Xalan-C XSL Transformer User's Guide" copyright="2000 The Apache Software Foundation">
+<book title="Xalan-C++ XSLT User's Guide" copyright="2000 The Apache Software Foundation">
<resources source="sbk:/sources/xalan/resources.xml"/>
@@ -67,7 +67,7 @@
<separator/>
<document id="index"
- label="Xalan-C 1.0.0"
+ label="Xalan-C++ 0.30.0"
source="xalan/index.xml"/>
<separator/>
@@ -76,7 +76,7 @@
<document id="overview"
label="Overview"
- source="xalan/overview.xml"/>
+ source="xalan/overview.xml"/>
<separator/>
@@ -106,7 +106,7 @@
<separator/>
- <external href="apidocs/index.html" label="C++ API"/>
+ <external href="http://xml.apache.org/xalan/c-apidocs/index.html" label="C++ API"/>
<separator/>
1.2 +1 -1 xml-xalan/c/xdocs/sources/xalanLocal.xml
Index: xalanLocal.xml
===================================================================
RCS file: /home/cvs/xml-xalan/c/xdocs/sources/xalanLocal.xml,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- xalanLocal.xml 2000/05/08 19:23:01 1.1
+++ xalanLocal.xml 2000/06/02 18:40:32 1.2
@@ -58,7 +58,7 @@
* <http://www.apache.org/>.
-->
-<book title="Xalan-C XSL Transformer User's Guide" copyright="2000 The Apache Software Foundation">
+<book title="Xalan-C++ XSLT User's Guide" copyright="2000 The Apache Software Foundation">
<resources source="sbk:/sources/xalan/resources.xml"/>
1.2 +4 -3 xml-xalan/c/xdocs/sources/xalan/BUGS
Index: BUGS
===================================================================
RCS file: /home/cvs/xml-xalan/c/xdocs/sources/xalan/BUGS,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- BUGS 2000/04/26 13:05:55 1.1
+++ BUGS 2000/06/02 18:40:33 1.2
@@ -1,5 +1,6 @@
-<s3 title="Outstanding bugs">
+<s3 title="Bug reporting">
<p>Outstanding bugs are recorded in the Apache XML <jump href="http://xml.apache.org/bugs/">Bug Tracking System</jump>.
- If you find a bug, please use this system to report it.</p>
+ If you find a bug, please use this system to report it.</p>
+ <note>If the Apache XML Bug Tracking System is not working, please report the bug to the
+ <human-resource-ref idref="xalandev"/>.</note>
</s3>
-
1.4 +11 -9 xml-xalan/c/xdocs/sources/xalan/STATUS
Index: STATUS
===================================================================
RCS file: /home/cvs/xml-xalan/c/xdocs/sources/xalan/STATUS,v
retrieving revision 1.3
retrieving revision 1.4
diff -u -r1.3 -r1.4
--- STATUS 2000/05/10 16:41:18 1.3
+++ STATUS 2000/06/02 18:40:33 1.4
@@ -1,17 +1,19 @@
<s3 title="Version of Xerces to use">
-<p>Xalan-C version 1.0.0 has been tested with Xerces-C version 1.1.0. The Xalan-C 1.1.0 Windows32 download includes xerces-c_1_1.dll. The Xalan-C 1.1.0 Linux download includes libxerces-c_1_1.so.
+<p>The &xslt4c-current; has been tested with &xml4c-used;. The &xslt4c-current; Windows32 download includes xerces-c_1_1.dll. The &xslt4c-current; Linux download includes libxerces-c_1_1.so.
- For information about including The Xerces-C dynamic link or shared object library on the system class path, see <link idref="getstarted" anchor="classpath">Setting up the system class path</link>.</p>
+For information about including The Xerces-C dynamic link or shared object library on the path, see <link idref="getstarted" anchor="path">Setting up the system path</link>.</p>
<p><em>Important</em> You may experience unpredictable anomalies if your Xalan and Xerces builds are not in synch. If you download an update to Xalan, check the release notes to determine which version of Xerces you should use.</p>
-</s3>
-<s3 title="To-do tasks for future Xalan releases">
- <p>We still need to do the following:</p>
+</s3><anchor name="to-do"/>
+<s3 title="To-do tasks for future &xslt4c; releases">
+ <p>To complete our implementation of the <resource-ref idref="XSLT"/>, we must add support for</p>
<ul>
- <li>Implement a more efficient mechanism for storing and navigating DOM trees, along the lines of the Xalan-J
- Document Table Model )<br/><br/>(DTM)<br/><br/></li>
- <li>Provide a debugging interface to enable the tracing of transformation events<br/><br/></li>
- <li>Add support for extension elements<br/><br/></li>
+ <li>The fallback element<br/><br/></li>
+ <li>The exclude-result-prefixes attribute<br/><br/></li>
+ <li>The output encoding attribute<br/><br/></li>
+ <li>Extension elements<br/><br/></li>
</ul>
+ <p>The XSLT specification makes no such requirement, but we plan to implement a more efficient mechanism for storing and
+ navigating DOM trees, along the lines of the Xalan-J Document Table Model (DTM)</p>
<p>Watch the <human-resource-ref idref="xalandev"/> for more information and for ideas about how you can get involved.</p>
</s3>
1.3 +14 -27 xml-xalan/c/xdocs/sources/xalan/commandline.xml
Index: commandline.xml
===================================================================
RCS file: /home/cvs/xml-xalan/c/xdocs/sources/xalan/commandline.xml,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -r1.2 -r1.3
--- commandline.xml 2000/05/10 16:41:16 1.2
+++ commandline.xml 2000/06/02 18:40:33 1.3
@@ -63,8 +63,8 @@
<s2 title="Using the Command-Line Utility">
<p>To perform a transformation, you can call &xslt4c; from the command line (or script),
- of from within an application (see <link idref="usagepatterns">Usage Patterns</link>).</p>
- <p>Process main() method provides a command-line interface
+ or from within an application (see <link idref="usagepatterns">Usage Patterns</link>).</p>
+ <p>TestXSLT 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>
@@ -77,46 +77,33 @@
stylesheet, and the output file:<br/><br/>
<code>TestXSLT -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>
+ <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
+-E (Do not expand entity refs)
+-ESCAPE chars(Which characters to escape -- default is <>&"'\r\n)
-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)
-VALIDATE (Validate the XML and XSL input -- validation is off by default)
--EDUMP [optional]FileName (Do stackdump on error)
+-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)
-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 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 -TEXT if you want the output to include only text nodes without any escaping.</p>
<p>Use -HTML to write 4.0 transitional HTML (some elements, such as <br>, are
- not well formed.</p>
- <p>To set stylesheet parameters from the command line, use -PARAM name expression. If
- you want to set the parameter to a string value, enclose the string in single quotes (') to
+ 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>TestXSLT -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>TestXSLT -in foo2.xml -lxcin foo.style</code></p>
</s2>
</s1>
1.2 +14 -14 xml-xalan/c/xdocs/sources/xalan/extensions.xml
Index: extensions.xml
===================================================================
RCS file: /home/cvs/xml-xalan/c/xdocs/sources/xalan/extensions.xml,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- extensions.xml 2000/05/08 19:23:03 1.1
+++ extensions.xml 2000/06/02 18:40:34 1.2
@@ -65,15 +65,14 @@
<li><link anchor="use">Using an extension function</link></li>
</ul><anchor name="intro"/>
<s2 title="Introduction">
-<p>For those situations where you would like to augment the functionality of XSLT with calls to C++ functions that you provide, &xslt4c; supports the creation and use of extension functions.</p>
-<note>&xslt4c; does not yet support extension elements. Support for extension elements will be added in the near future.</note>
-
+<p>At times, you may want to call your own custom C++ functions from a stylesheet. For these situations, &xslt4c; supports the creation and use of extension functions.</p>
<p>You can think of extension functions as extending the core library of functions that XPath provides. Like the
XPath functions, an extension function returns an XObject, which may contain a value of any of the five XSLT
data types: node-set, result-tree-fragment, string, boolean, or number.</p>
<p>You can send arguments to an extension function in the form of XPath expressions, literals (for string, boolean, and number), the values returned by other functions, and XSL variables or parameters set to any of the preceding.</p>
<p>For an example that implements, installs, and uses three extension functions, see the
<link idref="samples" anchor="externalfunc">External Functions</link> sample.</p>
+<note>&xslt4c; does not yet support extension elements. Support for extension elements will be added in the near future.</note>
</s2><anchor name="implement"/>
<s2 title="Implementing an extension function">
<p>Like the standard XPath functions, the functions you create derive from the Function base class. Set up your
@@ -81,7 +80,7 @@
<ol>
<li>The body of a function is the execute() method. Use the appropriate XObjectFactory method -- createNumber()
in the example below -- to create an XObject corresponding to the XSLT data type the function returns.<br/><br/></li>
- <li>Implement a clone method() to enable Xalan to create and maintain a copy of the extension
+ <li>Implement a clone() method to enable Xalan to create and maintain a copy of the extension
function.<br/><br/></li>
<li>(Optional) As is the practice for the XPath functions, you may want to prevent the compiler from generating
an assignment or equality operator for this function.</li>
@@ -132,6 +131,8 @@
*
* @return pointer to the new object
*/
+// For compilers that do not support covariant return types,
+// clone() must be declared to return the base type.
#if defined(XALAN_NO_COVARIANT_RETURN_TYPE)
virtual Function*
#else
@@ -155,15 +156,14 @@
methods for installing (and uninstalling) extension functions:</p>
<ul>
<li>installExternalFunctionGlobal() is a static method for making a function available globally</li>
- <li>installExternalFunctionLocal() makes the function available to the current instance of the XSLT processor.</li>
+ <li>installExternalFunctionLocal() makes the function available to the XSLTProcessorEnvSupport instance in which the function is
+ installed.</li>
</ul>
<p>These methods include arguments for the namespace, the function name, and the function implementation.</p>
<note>These XSLTProcessorEnvSupportDefault methods call XPathEnvSupportDefault methods of the same name which provide
the actual implementation.</note>
<p>When you install an extension function, the function inhabits the namespace you designate. For information about XML namespaces, see <jump href="http://www.w3.org/TR/REC-xml-names/">Namespaces in XML</jump>.</p>
-<p>We do not recommend this, but you can also install a function directly into the XPath function table, in which
-case it is not really an extension function. The XPath parser treats it like any other XPath function, and no namespace declaration or prefix is involved.</p>
-<p>The following code fragment installs the square root function defined above as a global function.</p>
+<p>The following code fragment installs the square root function defined above as a global function, and binds it to the extension-function name "square-root" in the namespace "http://ExternalFunction.xalan-c++.xml.apache.org" so it can be accessed from stylesheets. Keep in mind that the function name does not need to be the same as the name of the function class, and that a function name may be used more than once provided that each function with that name is installed in a different namespace.</p>
<source>// You have created a header file for FunctionSquareRoot.
#include <MyFunctions/FunctionSquareRoot.hpp>
// The namespace...
@@ -175,6 +175,8 @@
theNamespace,
"square-root",
FunctionSquareRoot());</source>
+<note>We do not recommend this, but you can also install a function directly into the XPath function table, in which
+case it is not really an extension function. The XPath parser treats it like any other XPath function, and no namespace declaration or prefix is involved.</note>
<p>For an example that installs a global extension function, a local extension function, and adds a function to the
XPath function table, see the <link idref="samples" anchor="externalfunc">External Functions</link> sample.</p>
</s2><anchor name="use"/>
@@ -191,7 +193,7 @@
in the stylesheet element or<br/><br/>
<code>xsl:exclude-result-prefixes="<ref>prefix-1 prefix-2 ...</ref>"</code><br/><br/>
in a literal result element or extension element.<br/><br/></li>
-<li>Call the extension function in the same manner you would call an XPath function.<br/><br/>
+<li>Call the extension function in the same manner you would call an XPath function. The function name you use in the stylesheet is a Qualified Name (QName) made up of the prefix you delcared in step 1 and the function name you specified when you installed the function.<br/><br/>
You can use XPath expressions, literals (for string, boolean, and number), and values returned by other functions to
specify function arguments.</li></ol>
<p>Suppose, for example, you are working with XML documents containing area elements like
@@ -225,13 +227,11 @@
<p>Please keep in mind that <em>all</em> LocationPath expressions return a node-set, even if the expression only
returns a single attribute or a text node (node-sets with one member). You can use the XSLT string() function
to convert a node-set value to string, and the number() function to convert a node-set value to number (a double).</p>
-<p>If you want to pass a node-set to an extension function, set up the function to accept a NodeRefListBase
-(or a MutableNodeRefList if you want to modify the nodes).</p>
+<p>If you want to pass a node-set to an extension function, set up the function to accept a <jump href="apidocs/class_nodereflistbase.html">NodeRefListBase</jump>.</p>
<p>Suppose, for example, you have a ProcessNodes function class that uses<br/><br/>
-<code>const NodeRefListBase& theNodeList = args[0]->nodeset();</code><br/><br/>
+<code>const NodeRefListBase& theNodeList = args[0]->nodeset();</code><br/><br/>
in the execute() method to get a reference to the node-set.</p>
-<p>Assuming you use the node-ext prefix in a stylesheet to refer to this function, any of the following function calls
-are syntactically possible:</p>
+<p>Assuming you install the function as "ProcessNodes" and use the "node-ext" prefix in a stylesheet to refer to the ProcessNodes function namespace, any of the following function calls are syntactically possible:</p>
<p><code><!--Process the current node--></code><br/>
<code><xsl:variable name="success" select="node-ext:ProcessNodes(.)"/></code></p>
<p><code><!--Process all nodes in current context--></code><br/>
1.3 +10 -10 xml-xalan/c/xdocs/sources/xalan/faq.xml
Index: faq.xml
===================================================================
RCS file: /home/cvs/xml-xalan/c/xdocs/sources/xalan/faq.xml,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -r1.2 -r1.3
--- faq.xml 2000/05/10 16:41:16 1.2
+++ faq.xml 2000/06/02 18:40:34 1.3
@@ -9,7 +9,8 @@
<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 &xslt4c;, see Dave Pawson's <jump
- href="http://freespace.virgin.net/b.pawson/xsl/index.html#top">XSL Frequently Asked Questions</jump>.</p>
+ href="http://freespace.virgin.net/b.pawson/xsl/index.html#top">XSL Frequently Asked Questions</jump> and Michael Kay's
+ <jump href="http://www.wrox.com/Consumer/Store/Details.asp?ISBN=1861003129">XSLT Programmer's Reference</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>
@@ -26,9 +27,10 @@
<a>
<p>The XSLTEngineImpl stores running state information, so it is not thread-safe. If you want to use the XSLTEngineImpl
- to perform multiple transformations, create a new instance for each transformations or synchronize the transformations.
+ to perform multiple simultaneous transformations, create a separate instance for each transformation.
If you want to perform multiple serial transformations with a single XSLTEngineImpl object, call the XSLTEngineImpl reset()
- method between each transformation.</p>
+ method after each transformation. You may want to serialize access to this object, so it can't accidently start another
+ transformation while a transformation is in progress.</p>
<p>StylesheetRoot objects, on the other hand, are thread-safe. A single StylesheetRoot object may be called concurrently
from multiple threads. Keep in mind, however, that the StylesheetRoot uses an XSLTEgineImpl to store running state information
for each transformation, so you must call the XSLTEngineImpl reset() method between each transformation.</p>
@@ -40,7 +42,7 @@
<q>What can I do to speed up transformations?</q>
<a><p>To maximize performance, here are some suggestions for you to keep in mind as you set up your applications:</p><ul>
- <li>Use compiled stylesheets for multiple transformations.<br/><br/></li>
+ <li>Use a compiled stylesheet when you expect to use the stylesheet more than once.<br/><br/></li>
<li>Set up your stylesheets to function efficiently.<br/><br/></li>
<ul>
<li>Don't use "//" (descendant axes) patterns near the root of a large document.<br/><br/></li>
@@ -49,20 +51,18 @@
<li>xsl:for-each is fast because it does not require pattern matching.<br/><br/></li>
<li>Keep in mind that xsl:sort prevents incremental processing.<br/><br/></li>
<li>When you create variables, <xsl:variable name="fooElem" select="foo"/> is usually faster than
- >xsl:variable name="fooElem"><xsl:value-of-select="foo"/></xsl:variable>.<br/><br/></li>
+ <xsl:variable name="fooElem"><xsl:value-of-select="foo"/></xsl:variable>.<br/><br/></li>
<li>Be careful using the last() function.<br/><br/></li>
<li>The use of index predicates within match patterns can be expensive.<br/><br/></li>
- <li>Decoding and encoding is expensive.<br/><br/></li>
- <li>The serializer must check each character for escaping; 30% to 60% or processing time is typically spent in
- the serializer.</li>
</ul>
</ul></a>
</faq>
<faq title="Stylesheet validation">
- <q>How do I validate an XSL stylesheet?</q>
+ <q>Can 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>An XSL stylesheet is an XML document, so it can have a DOCTYPE and be subject to validation, but you probably will have
+ to write a custom DTD for the purpose.</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
1.4 +31 -28 xml-xalan/c/xdocs/sources/xalan/getstarted.xml
Index: getstarted.xml
===================================================================
RCS file: /home/cvs/xml-xalan/c/xdocs/sources/xalan/getstarted.xml,v
retrieving revision 1.3
retrieving revision 1.4
diff -u -r1.3 -r1.4
--- getstarted.xml 2000/05/10 16:41:17 1.3
+++ getstarted.xml 2000/06/02 18:40:34 1.4
@@ -1,7 +1,7 @@
<?xml version="1.0" standalone="no"?>
<!DOCTYPE s1 SYSTEM "sbk:/style/dtd/document.dtd">
-<s1 title="Getting Started with Xalan-C">
+<s1 title="Getting Started with Xalan-C++">
<ul>
<li><link anchor="download">Downloading what you need</link></li>
<li><link anchor="path">Setting up the system path</link></li>
@@ -11,61 +11,66 @@
</ul>
<anchor name="download"/>
<s2 title="Downloading what you need">
-<p>For Xalan-C 1.0.0, we are distributing a Windows32 Visual C++ build and a Linux build. In the future, we intend to add builds for other platforms.</p>
-<s3 title="Xalan-C Distributions">
+<p>For &xslt4c-current;, we are distributing a Windows32 Visual C++ build and a Linux build. In the future, we intend to add builds for other platforms.</p>
+<s3 title="&xslt4c; Distributions">
<p><img src="xalan-cdist.gif" alt="xalan-cdist.gif"/></p>
</s3>
-<p>For the Windows32 build, download <jump href="http://xml.apache.org/dist/xalan-c/xalan-c_1_0_0.zip">xalan-c_1_0_1.zip</jump>.</p>
-<p>For the Linux build, download <jump href="http://xml.apache.org/dist/xalan-j/xalan-c_1_0_0.tar.gz">xalan-c_1_0_0.tar.gz</jump>.</p>
-<p>Each distribution contains all you need to run the Xalan command-line utility for performing transformations. To build your own applications, you also need a compatible Xerces-C distribution.</p>
+<p>For the Windows32 build, download <jump href="http://xml.apache.org/dist/Xalan-C_0_30_0-win32.zip">Xalan-C_0_30_0-win32.zip</jump>.</p>
+<p>For the Linux build, download <jump href="http://xml.apache.org/dist/Xalan-C_0_30_0-linux.tar.gz">Xalan-C_0_30_0-linux.tar.gz</jump>.</p>
+<p>Each distribution contains all you need to run the Xalan command-line utility for performing transformations. To build your own applications, you also need a compatible Xerces-C distribution and the <resource-ref idref="icu"/>.</p>
<s3 title="What you need to run the Xalan command-line utility">
<p>To run the Xalan executable for performing transformations, you need the following:</p>
<p><em>Windows32</em></p>
<ul>
<li>The executable: TestXSLT.exe</li>
-<li>The 8 Xalan-C dynamic link libraries: DOMSupport.dll, PlatformSupport.dll, XalanDOM.dll, XercesParserLiaison.dll,
+<li>The Xalan-C dynamic link libraries: DOMSupport.dll, PlatformSupport.dll, XalanDOM.dll, XercesParserLiaison.dll,
XercesPlatformSupport.dll, XMLSupport.dll, XPath.dll, XSLT.dll</li>
<li>The Xerces-C dynamic link library: xerces-c_1_1.dll</li>
+<li>The International Components for Unicode (ICU) dynamic link libraries: icui18n.dll, icuuc.dll</li>
+<li>The ICU locale data files</li>
</ul>
<p><em>Linux</em></p>
<ul>
- <li>The utility: Test.XSLT</li>
- <li>The Xalan-C shared library: libxalan-c_0_1_1.so</li>
- <li>The Xerces-C shared library: libxerces-c1_1.so</li>
+ <li>The utility: TestXSLT</li>
+ <li>The Xalan-C shared library: libxalan-C_0_30_0.so</li>
+ <li>The Xerces-C shared library: libxerces-c1_0.so</li>
+ <li>The International Components for Unicode (ICU) shared library: libicu-1-4-1-2.so</li>
+ <li>The ICU locale data files</li>
</ul>
+<p><em>Important</em> ICU requires you to set the ICU_DATA environment variable to point to the directory containing the ICU locale data files. In the Windows32 distribution, this is xml-xalan\c\Build\Win32\VC6\Release\Data. In the Linux distribution, it is xml-xalan/c/lib/data.</p>
<p>For information about using the command-line utility, see <link idref="commandline">Command-Line Utility</link>.</p>
</s3>
<s3 title="What you need to build applications">
<p>To build your own applications with Xalan and Xerces, you also need need the
Xalan-C and Xerces-C header (.hpp) files and (for Windows) the Xerces-C libraries (.lib files).</p>
-<p>The Xalan-C header files are in the source tree in both distributions.</p>
+<p>The Xalan-C header files are in the src directory tree in both distributions.</p>
<p>In the Windows32 distribution (built with Microsoft® Visual C++® 6.0), the dlls and libraries are in the Build - Win32 -V6 - Release subdirectory.</p>
-<p>In the Linux distribution (built with a make file), the shared object library is in the lib subdirectory.</p>
-<p>To get the Xerces-C header and (for Windows) .lib files, download and expand the Xerces-C 1.1.0 Binary distribution for your platform from the <resource-ref idref="Xerces-c-dist"/>. For information about which Xerces-C distribution has been tested with this Xalan-C release, see <link idref="readme" anchor="status">Version of Xerces to use</link>.</p>
-<note>If you want to rebuild Xalan, you will also need the Xerces-C source distribution (Xalan uses a header file that is not included in the Xerces-C binary distributions). For more information, see <link idref="readme" anchor="build"></link>Build Notes.</note>
+<p>In the Linux distribution (built with a make file and Red Hat Linux 6.1), the shared object library is in the lib subdirectory.</p>
+<p>To get the Xerces-C header and (for Windows) .lib files, download and expand the Xerces-C 1.1.0 Binary distribution for your platform from the <resource-ref idref="xerces-c-dist"/>. For information about which Xerces-C distribution has been tested with this Xalan-C release, see <link idref="readme" anchor="status">Version of Xerces to use</link>.</p>
+<p>For information about rebuilding &xslt4c;, see the <link idref="readme" anchor="build">Build notes</link>.</p>
</s3>
</s2><anchor name="path"/>
-<s2 title="Setting up the system path">
-<p>For the Xalan-C Windows32 distribution, place xml-xalan\c\Build\Win32\VC6\Release on the system path.</p>
-<p>For the Xalan-C Linux distribution, place xml-xalan/c/bin and xml-xalan/c/lib on the system path. </p>
-<p>If you do your own Xalan and Xerces builds, be sure to include the directories that contain the libraries and the TextXSLT executable on your system path.</p>
+<s2 title="Setting up the path">
+<p>For the Xalan-C Windows32 distribution, place xml-xalan\c\Build\Win32\VC6\Release on the path.</p>
+<p>For the Xalan-C Linux distribution, place xml-xalan/c/bin and xml-xalan/c/lib on the shared library path (LD_LIBRARY_PATH for Red Hat Linux 6.1).</p>
+<p>If you do your own Xalan, ICU, and Xerces builds, be sure to include the directories that contain the libraries and the TextXSLT executable on your path.</p>
</s2><anchor name="samples"/>
<s2 title="Trying out the samples">
-<p>The &xslt4c; Windows32 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>
- <note>The Linux distribution includes the sample application source files in the samples subdirectories. You can use these source files to build the executables. </note>
+<p>The &xslt4c; distribution includes a number of basic sample applications. These samples are easy to compile and run,
+ and you can review the source files -- all of which are brief -- to see just how they work. In the Windows32 distribution, we have precompiled these samples for you so they are ready to run. In the Linux distribution, you need to build them first.</p>
<p>To run the samples, do the following:</p>
<ol>
+<li>(Linux only) Compile the sample sources and build an executable for each sample application.</li>
<li>Set up your path (see above). In the Windows32 distribution, the sample executables are in
-xml-xalan\c\Build\Win32\VC6\Release.</li>
+xml-xalan\c\Build\Win32\VC6\Release. For Linux, we suggest you build the executables in xml-xalan/c/bin.</li>
<li>Go to the samples subdirectory containing the sample (use the DOS shell in Windows).</li>
<li>Run the sample from the command line.</li>
<li>Examine the application source files.</li>
</ol>
<p>For example, go to the SimpleTransform subdirectory and issue the following command:</p>
<p><code>SimpleTransform</code></p>
-<p>The sample uses the foo.xsl stylesheet to transform foo.xml, and writes the transformation result to foo.out. To see how the example works, examine the source files: foo.xml, foo.xsl, foo.out, and SimpleTransform.cpp.</p>
+<p>SimpleTransform uses the foo.xsl stylesheet to transform foo.xml, and writes the transformation result to foo.out. To see how the example works, examine the source files: foo.xml, foo.xsl, foo.out, and SimpleTransform.cpp.</p>
<p>For more information about the samples, see <link idref="samples">&xslt4c; Samples</link>.</p>
</s2><anchor name="commandline"/>
<s2 title="Performing your own transformations from the command line">
@@ -73,12 +78,10 @@
most standard transformations is as follows:</p>
<p><code>TestXSLT -in <ref>xmlSource</ref> -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>If you want the output to be displayed on the screen, simply omit the -out flag and outputfile.</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="apps"/>
-<s2 title="Setting up your own C++ 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 idref="usagepatterns">basic usage patterns</link>.</p>
-<p>If you modify a C++ source file, be sure to rebuild the application executable and place it on the system path.</p>
-<p>For more information on setting up applications, see <link idref="usagepatterns">Basic Usage Patterns</link>.</p>
+<s2 title="Setting up your own XSLT applications">
+<p>You can start by using your own XML source files and XSL stylesheets with the sample applications, which illustrate a number of usage patterns. For more information on setting up applications, see <link idref="usagepatterns">Basic Usage Patterns</link>.</p>
</s2>
</s1>
1.3 +6 -6 xml-xalan/c/xdocs/sources/xalan/index.xml
Index: index.xml
===================================================================
RCS file: /home/cvs/xml-xalan/c/xdocs/sources/xalan/index.xml,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -r1.2 -r1.3
--- index.xml 2000/05/10 16:41:17 1.2
+++ index.xml 2000/06/02 18:40:35 1.3
@@ -58,11 +58,11 @@
<!DOCTYPE s1 SYSTEM "sbk:/style/dtd/document.dtd">
-<s1 title="Xalan-C Version 1.0.0">
+<s1 title="Xalan-C++ Version 0.30.0">
<s2 title="What is it?">
- <p>Xalan is an XSL processor for transforming XML documents into HTML, text, or other XML document types. Xalan-C
- version 1.0.0 represents a complete and a robust C++ reference implementation of the W3C Recommendations for XSL
+ <p>Xalan is an XSL processor for transforming XML documents into HTML, text, or other XML document types. Xalan-C++
+ version 0.30.0 represents an almost complete and a robust C++ reference implementation of the W3C Recommendations for XSL
Transformations (XSLT) and the XML Path Language (XPath).</p>
<p>Xalan-C uses the Xerces-C XML parser.</p>
</s2>
@@ -77,11 +77,11 @@
</tr>
<tr>
<td>Windows32</td>
- <td><jump href="http://xml.apache.org/dist/xalan-j/xalan-j_1_0_1.zip">xalan-c_1_0_0.zip</jump></td>
+ <td><jump href="http://xml.apache.org/dist/Xalan-C_0_30_0-win32.zip">Xalan-C_0_30_0-win32.zip</jump></td>
</tr>
<tr>
<td>Linux</td>
- <td><jump href="http://xml.apache.org/dist/xalan-j/xalan-j_1_0_1.tar.gz">xalan-c_1_0_0.tar.gz</jump></td>
+ <td><jump href="http://xml.apache.org/dist/Xalan-C_0_30_0-linux.tar.gz">Xalan-C_0_30_0-linux.tar.gz</jump></td>
</tr>
</table>
<p>We plan to add builds for other platforms as soon as possible. Volunteers are more than welcome!</p>
@@ -89,7 +89,7 @@
<s2 title="Where do I get Xerces?">
<p>Both distributions include the Xerces runtime environment for Xalan -- xerces-c_1_1.dll for Windows,
- and libxerces-c_1_1.so for Linux. To build applications with Xalan and Xerces, you also need the Xerces-C binary
+ and libxerces-c_1_1.so for Linux. To build applications with Xalan and Xerces, you also need the &xml4c;
binary distribution for your platform, which you can download from the
<resource-ref idref="Xerces-c-dist"/>.</p>
<note>Be sure you are using a compatible Xerces-C build. For information about the build with which this release
1.3 +39 -28 xml-xalan/c/xdocs/sources/xalan/overview.xml
Index: overview.xml
===================================================================
RCS file: /home/cvs/xml-xalan/c/xdocs/sources/xalan/overview.xml,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -r1.2 -r1.3
--- overview.xml 2000/05/10 16:41:17 1.2
+++ overview.xml 2000/06/02 18:40:35 1.3
@@ -67,7 +67,7 @@
<li><link anchor="glossary">Glossary</link></li>
</ul><anchor name="intro"/>
<s2 title="Introduction">
- <p>&xslt4c; (named after a rare musical instrument) fully implements the <resource-ref idref="XSLT"/> and the
+ <p>&xslt4c; (named after a rare musical instrument) implements the <resource-ref idref="XSLT"/> and the
<resource-ref idref="XPath"/>. XSLT is the first part of the XSL stylesheet language for XML. It includes the XSL
Transformation vocabulary and 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
@@ -79,13 +79,13 @@
transforming XML documents from one document type to another document type (XML, HTML, or other). In structural
terms, an XSL 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 XSL stylesheet may include cascading style sheets (CSS) in the result.</note>
+ <note>The XSL stylesheet may generate and refer to cascading style sheets (CSS) as part of its output.</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><?xml version="1.0"?>
+<p>foo.xml:</p>
+<source><?xml version="1.0"?>
<doc>Hello</doc></source>
- <p>foo.xsl:</p>
- <source><?xml version="1.0"?>
+<p>foo.xsl:</p>
+<source><?xml version="1.0"?>
<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" version="1.0">
<xsl:template match="doc">
<out><xsl:value-of select="."/></out>
@@ -93,17 +93,22 @@
</xsl:stylesheet></source>
<p>foo.out:</p>
<source><out>Hello</out></source>
-<p>&xslt4c; uses the Xerces XML parser to parse XML documents and XSL stylesheets. The input may appear in the form of a file,
-a stream, or a <resource-ref idref="DOM"/>. &xslt4c; performs the transformations specified in the XSL stylesheet and produces a file, a stream, or a DOM as you specify when you set up the transformation.</p>
+
</s2><anchor name="features"/>
<s2 title="&xslt4c; Features">
<ul>
- <li>Implements the <resource-ref idref="XSLT"/></li>
- <li>Incorporates the <resource-ref idref="XPath"/></li>
- <li>Interfaces directly to the <jump href="http://xml.apache.org/xerces-c/index.html">&xml4c; XML parser</jump></li>
- <li>Outputs to DOM</li>
- <li>May be run from the <link idref="commandline">command line</link></li>
- <li>Supports C++ <link idref="extensions">extension functions</link></li>
+ <li>With a few minor exceptions, &xslt4c; fully implements the <resource-ref idref="XSLT"/>.<br/><br/>
+ For a list of the XSLT features that &xslt4c; does not yet implement, see <link idref="readme" anchor="to-do">&xslt4c;
+ to-do tasks</link>.<br/><br/></li>
+ <li>&xslt4c; incorporates the <resource-ref idref="XPath"/>.<br/><br/></li>
+ <li>&xslt4c; uses <jump href="http://xml.apache.org/xerces-c/index.html">&xml4c;</jump> to parse XML documents and XSL
+ stylesheets.<br/><br/>
+ The input may appear in the form of a file or URL, a stream, or a <resource-ref idref="DOM"/>.
+ &xslt4c; performs the transformations specified in the XSL stylesheet and produces a file, a stream, or a DOM as you
+ specify when you set up the transformation.<br/><br/></li>
+ <li>Along with a complete API for performing transformations in your C++ applications, &xslt4c; provides a <link
+ idref="commandline">command line</link> utility for convenient file-to-file transformations.<br/><br/></li>
+ <li>&xslt4c; supports C++ <link idref="extensions">extension functions</link></li>
</ul>
</s2><anchor name="towork"/>
<s2 title="Getting to work with &xslt4c;">
@@ -116,7 +121,8 @@
to consult one or more of the following:</p>
<ul>
<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>
+ the XML Bible: XSL Transformations</jump> (the online version is more current than the version in the printed
+ book)<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>
@@ -131,10 +137,10 @@
<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<br/><br/></li>
- <li>Donald Ball's <jump href="http://www.webslingerZ.com/balld/xsl/designer_manual.xml">A Guide to XML and XSL for Designers</jump><br/><br/></li>
- <li>XSLT - XSL Transformations in
- <jump href="http://www.brics.dk/~amoeller/XML/">The XML Revolution: Technologies for the future Web</jump> by
- Anders Møller and Michael I. Schwartzbach<br/><br/></li>
+ <li>Donald Ball's <jump href="http://www.webslingerZ.com/balld/xsl/designer_manual.xml">A Guide to XML and XSL for
+ Designers</jump><br/><br/></li>
+ <li>Michael Kay's <jump href="http://www.wrox.com/Consumer/Store/Details.asp?ISBN=1861003129">XSLT Programmer's
+ Reference</jump>, Wrox Press, April 2000</li>
</ul>
<p>When you come across other useful introductory or background materials, please email <human-resource-ref
idref="dleslie"/>, so he can add them to this list.</p>
@@ -142,22 +148,26 @@
</s2><anchor name="glossary"/>
<s2 title="Glossary">
<gloss>
+ <label>XSLT Namespace</label>
+ <item>The <jump href="http://www.w3.org/TR/REC-xml-names/">XML namespace</jump> for XSLT. An XML namespace is a
+ collection of element and attribute names, identified by a Unique Resource Identifier (URI), which often takes the form of
+ a URL, but is really just a unique string, not a pointer to a web page. The XSLT namespace URI is
+ http://www.w3.org/1999/XSL/Transform. In each XSLT stylesheet, you must declare this namespace in the stylesheet element
+ tag and bind it to a local prefix. Like the XSLT specification, we always use xsl as the XSLT namespace prefix in our
+ descriptions and examples, although you are free to bind any prefix to this namespace.<br/><br/></item>
+
<label>XSL Instruction</label>
- <item>Any tag with an XSL namespace prefix.<br/><br/></item>
+ <item>Any tag associated with the XSLT namespace.<br/><br/></item>
<label>Template</label>
<item>An element, usually with child elements, that specifies a "rule" or set of
instructions to perform when a particular kind of node is encountered in the source tree.<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>
-
+ <item>Any tag that occurs inside an xsl:template element and is associated with the XSLT namespace.<br/><br/></item>
+
<label>Source Tree</label>
- <item>The tree input to the XSL process.<br/><br/></item>
+ <item>The XML 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>
@@ -171,6 +181,7 @@
</gloss>
<p>For more definitions of XSLT terminology, see Dave Pawson's
<jump href="http://freespace.virgin.net/b.pawson/xsl/xslvocab.html#top">XSLT Terminology
- Clarification</jump>.</p>
+ Clarification</jump> and the Glossary in Michael Kay's
+ <jump href="http://www.wrox.com/Consumer/Store/Details.asp?ISBN=1861003129">XSLT Programmer's Reference</jump>.</p>
</s2>
</s1>
1.4 +22 -4 xml-xalan/c/xdocs/sources/xalan/readme.xml
Index: readme.xml
===================================================================
RCS file: /home/cvs/xml-xalan/c/xdocs/sources/xalan/readme.xml,v
retrieving revision 1.3
retrieving revision 1.4
diff -u -r1.3 -r1.4
--- readme.xml 2000/05/10 16:41:17 1.3
+++ readme.xml 2000/06/02 18:40:36 1.4
@@ -85,11 +85,29 @@
</ul>
<anchor name="jar"/>
<s3 title="Rebuilding &xslt4c;">
- <p>To rebuild the Windows32 release, use the Microsoft Visual C++ 6.0 project files. To rebuild the Linux release, use the make file in the root of the source directory.</p>
- <p><em>Important</em> We have set up the Visual C++ projects and the Linux make file to look for Xerces in a the directory structure that results from downloading xml-xerces/c from the Apache XML repository and building with the Visual C++ project files or the Linux make file. This structure parallels the Xalan-C source tree and build structure.<br/><br/>
+ <p>If you want to rebuild &xslt4c; (to produce a debug build, for example), you need the following:</p>
+ <ul>
+ <li>The &xslt4c; source files</li>
+ <li>The &xml4c; header and (for Windows) .lib files</li>
+ <li>The ICU header and (for Windows) .lib files</li>
+ </ul>
+ <p>The &xslt4c; source files are in the distribution.</p>
+ <p>The required &xml4c; files are in the &xml4c; binary distributions, with the exception of a header file that is only in the
+ &xml4c; source distributions. Accordingly, you need the binary and the source distributions.</p>
+ <p>To get the ICU, download and unzip the <resource-ref idref="icu-download"/> from the IBM developerWorks open source zone,
+ and do a build -- see the Windows NT or Unix build instructions in the readme.html that accompanies the download.</p>
+ <note> If you are not rebuilding ICUBridge, you do not need the ICU header or .lib files.</note>
+ <p>To rebuild the Windows32 release, use the Microsoft Visual C++ 6.0 project files. To rebuild the Linux release, use the make
+ file in the root of the source directory. Both builds look for &xml4c; and ICU in directories parallel to the xml-xalan
+ directory</p>
+ <p><em>Important</em> We have set up the Visual C++ projects and the Linux make file to look for Xerces in a directory structure that results from downloading xml-xerces/c from the <jump href="http://xml.apache.org/websrc/cvsweb.cgi/">Apache XML CVS repository</jump> and building with the Visual C++ project files or the Linux make file. This structure parallels the Xalan-C source tree and build structure.<br/><br/>
If you are using a Xerces-C binary distribution, you must either modify the Xalan-C project files or makefile, or rearrange the build directory structure, and you must also get the header files from the Xerces-C source distribution, since Xalan-C uses a header file that is not included in the Xerces-C binary distribution.</p>
-<note>Keep in mind that at any given point in time the Xalan-C and Xerces-C source trees in the Apache XML repository may not be consistent. When we release a version of Xerces-C we certify that it is compabible with a given release of Xalan-C. To be safe, stick with distributions that we certify to be compatible. Reminder: Xalan-C 1.0.0 is compatible with Xerces-C 1.1.0.</note>
- </s3><anchor name="samples"/>
+<s4 title="&xml4c; and ICU layout for &xslt4c; build">
+<p><img src="xerces-icu.gif" alt="xerces-icu.gif"/></p>
+</s4>
+<note>Keep in mind that at any given point in time the Xalan-C and Xerces-C source trees in the Apache XML repository may not be consistent. When we release a version of Xerces-C we certify that it is compabible with a given release of Xalan-C. To be safe, stick with distributions that we certify to be compatible. Reminder: &xslt4c-current; is compatible with &xml4c-used;.<br/><br/>
+&xslt4c-current; was built with the &icu-used;. You can probably use newer ICU releases as they appear.</note>
+</s3><anchor name="samples"/>
<s3 title="Rebuilding a sample application">
<p>The Windows32 distribution includes Visual C++ project files for each of the sample applications. The project files are in the samples subdirectories along with the source files. If you modify a sample and want to recompile it, you can recompile the .cpp file(s) and rebuild the executable.</p>
<p>The Linux distribution does not yet include make files for the sample applications, so you must construct your own Linux make files and build the sample executables.</p>
1.2 +10 -7 xml-xalan/c/xdocs/sources/xalan/resources.xml
Index: resources.xml
===================================================================
RCS file: /home/cvs/xml-xalan/c/xdocs/sources/xalan/resources.xml,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- resources.xml 2000/05/08 19:23:04 1.1
+++ resources.xml 2000/06/02 18:40:36 1.2
@@ -13,10 +13,16 @@
]>
<resources>
- <resource id="Xalan-current" title="Xalan-C++ 1.0.0 XSLT Processor" location="http://xml.apache.org/xalan"/>
- <resource id="Xalan-c-dist" title="Xalan-C distribution directory" location="http://xml.apache.org/dist/xalan-c/"/>
- <resource id="LotusXSL-current" title="LotusXSL 1.0.0" location="http://www.alphaworks.ibm.com/tech/LotusXSL"/>
- <resource id="Xerces-c-dist" title="Xerces-C distribution directory" location="http://xml.apache.org/dist/xerces-c/"/>
+ <resource id="xalan-c-current" title="Xalan-C++ Version 0.40.0 XSLT Processor" location="http://xml.apache.org/xalan"/>
+ <resource id="xerces-c-used" title="Xerces-C++ Version 1.2.0" location="http://xml.apache.org/xerces-c/index.html"/>
+
+ <resource id="xalan-c-dist" title="Xalan-C++ distribution directory" location="http://xml.apache.org/dist/"/>
+ <resource id="xerces-c-dist" title="Xerces-C++ distribution directory" location="http://xml.apache.org/dist/xerces-c/"/>
+ <resource id="xalan-c-win32-download" title="Xalan-C_0_40_0-win32.zip" location="http://xml.apache.org/dist/Xalan-C_0_40_0-win32.zip"/>
+ <resource id="xalan-c-linux-download" title="Xalan-C_40_0-linux.tar.gz" location="http://xml.apache.org/dist/Xalan-C_0_40_0-linux.tar.gz"/>
+
+ <resource id="icu" title="International Components for Unicode(ICU)" location="http://oss.software.ibm.com/developerworks/opensource/icu/project/index.html"/>
+<resource id="icu-download" title="International Components for Unicode(ICU) 1.4.1.2 source files" location="http://oss.software.ibm.com/developerworks/opensource/icu/project/download/index.html"/>
<resource id="ApacheLicense" title="The Apache Software License, Version 1.1" location="http://xml.apache.org/dist/LICENSE.txt"/>
@@ -29,9 +35,6 @@
<resource id="DOM" title="DOM" location="http://www.w3.org/DOM"/>
- <resource id="xml4c-used" title="Version 3.0.0EA3 of the XML Parser for C++" location="http://www.alphaworks.ibm.com/tech/xml4j"/>
- <resource id="xerces-used" title="Version 1.0.3 of Xerces-C++" location="http://xml.apache.org/xerces-c/index.html"/>
-
<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"/>
1.3 +41 -10 xml-xalan/c/xdocs/sources/xalan/samples.xml
Index: samples.xml
===================================================================
RCS file: /home/cvs/xml-xalan/c/xdocs/sources/xalan/samples.xml,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -r1.2 -r1.3
--- samples.xml 2000/05/10 16:41:18 1.2
+++ samples.xml 2000/06/02 18:40:36 1.3
@@ -61,7 +61,8 @@
<ul>
<li><link anchor="getstarted">Samples to help you get started</link></li>
<li><link anchor="simpletransform">SimpleTransform</link></li>
- <li><link anchor="usestylesheetparam">Use StylesheetParam</link></li>
+ <li><link anchor="usestylesheetparam">UseStylesheetParam</link></li>
+ <li><link anchor="tracelisten">TraceListen</link></li>
<li><link anchor="compilestylesheet">CompileStylesheet</link></li>
<li><link anchor="xpathwrapper">XPathWrapper</link></li>
<li><link anchor="externalfunctions">ExternalFunctions</link></li>
@@ -82,12 +83,7 @@
<li>Examine the application source files. You may also want to modify the source files. Remember that if you
modify a .cpp file, you must rebuild the executable and place it on the path before you can run the
modified application.</li>
- </ol>
- <p>The basic command line for running samples is </p>
- <p><code><ref>executable</ref></code></p>
- <p>or</p>
- <p><code><ref>executable args</ref></code></p>
- <p>where <ref>executable</ref> is the name of the executable and <ref>args</ref> are the arguments.</p>
+ </ol>
</s2><anchor name="simpletransform"/>
<s2 title="SimpleTransform">
<p>What it does: The SimpleTransform class uses the foo.xsl stylesheet to transform foo.xml, and writes the
@@ -109,6 +105,41 @@
as a single argument. For example:</p>
<p><code>UseStylesheetParam param1 "'hello out there'"</code></p>
<p>See also: <link idref="usagepatterns" anchor="params">Setting stylesheet parameters</link>.</p>
+ </s2><anchor name="tracelisten"/>
+ <s2 title="TraceListen">
+ <p>What it does: Trace events during a transformation; the transformation uses birds.xsl to transform birds.xml and writes the
+ output to birds.out.</p>
+ <p>You can run it from the TraceListen subdirectory with</p>
+ <p><code>TraceListen <ref>traceFlags</ref></code></p>
+ <p>where <ref>traceFlags</ref> is one or more of the following:</p>
+ <p> <code>-TT</code> (Trace the templates as they are being called)</p>
+ <p> <code>-TG</code> (Trace each result tree generation event)</p>
+ <p> <code>-TS</code> (Trace each selection event)</p>
+ <p> <code>-TTC</code> (Trace the template children as they are being processed)</p>
+ <p>These flags are also available in the <link idref="commandline">command-line utility (TestXSLT)</link>.</p>
+ <p>The core of this example is the following fragment:</p>
+ <source>// Set up a diagnostic writer to be used by the TraceListener...
+XercesStdTextOutputStream theStdErr(std::cerr);
+XercesDOMPrintWriter diagnosticsWriter(theStdErr);
+
+// Set up the TraceListener...
+// traceTemplates, traceTemplateChildren, traceGenerationEvent,
+// and TraceSelectionEvent are booleans set by the command line.
+auto_ptr<TraceListener> theTraceListener;
+theTraceListener = auto_ptr<TraceListener>(new TraceListenerDefault(
+ diagnosticsWriter,
+ traceTemplates,
+ traceTemplateChildren,
+ traceGenerationEvent,
+ traceSelectionEvent));
+
+// Add the TraceListener to the XSLT processor...
+theProcessor.setTraceSelects(traceSelectionEvent);
+theProcessor.addTraceListener(theTraceListener.get());
+
+// Perform the transformation
+....</source>
+
</s2><anchor name="compilestylesheet"/>
<s2 title="CompileStylesheet">
<p>What it does: Use a compiled stylesheet to perform a series of transformations.</p>
@@ -120,7 +151,7 @@
<p>This sample uses TestDriver, an executable, and two classes: XPathWrapper and XPathWrapperImp. </p>
<p>What it does: TestDriver passes XPathWrapper an XML file name, a context node location path, and an XPath
expression. XPathWrapper in turn passes these arguments to the XPathWrapperImpl evaluate() method, which executes
- the XPath expression from specified context node in the XML document and returns the nodes (if any) it finds.</p>
+ the XPath expression from specified context node in the XML document and returns the nodes it finds (if any).</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 context node in an XML file.</note>
<p>Run this sample from the XPathWrapper subdirectory with</p>
@@ -135,10 +166,10 @@
...
<name first="Paul" last="Dick"/>
</doc></source>
- <p>You can try command lines like</p>
+ <p>You can try command lines like</p>
<p><code>TestDriver foo.xml /doc name/@last</code></p>
<p>and</p>
- <p><code>TestDriver foo.xml //name[position()="4" ./@first</code></p>
+ <p><code>TestDriver foo.xml //name[position()="4"]./@first</code></p>
<p>See also: <link idref="usagepatterns" anchor="xpath">Working with XPath expressions</link>.</p>
</s2><anchor name="externalfunctions"/>
<s2 title="ExternalFunctions">
1.3 +35 -28 xml-xalan/c/xdocs/sources/xalan/usagepatterns.xml
Index: usagepatterns.xml
===================================================================
RCS file: /home/cvs/xml-xalan/c/xdocs/sources/xalan/usagepatterns.xml,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -r1.2 -r1.3
--- usagepatterns.xml 2000/05/10 16:41:18 1.2
+++ usagepatterns.xml 2000/06/02 18:40:36 1.3
@@ -65,18 +65,18 @@
<li><link anchor="compiled">Compiling stylesheets</link></li>
<li><link anchor="xpath">Working with XPath expressions</link></li>
<li><link anchor="extensions">Creating and using extension functions</link></li>
+<li><link anchor="tracelistener">Using the TraceListener</link></li>
</ul><anchor name="intro"/>
<s2 title="Introduction">
-<p>&xslt4c; takes as primary input an XML source document and an XSL stylesheet, both represented by instances of <jump href="apidocs/class_XSLTInputSource.html">XSLTInputSource</jump>.</p>
-<note>The stylesheet may also take the form of a compiled stylesheet (an instance of <jump href="apidocs/class_stylesheetroot.html">StylesheetRoot</jump>. If the XML document contains a stylesheet Processing Instruction (PI), a separate stylesheet is not required.</note>
-<p>&xslt4c; uses the Xerces DOM parser to parse the input and the Xerces SAX parser to parse the stylesheet, and sends the output to <jump href="apidocs/class_xsltresulttarget.html">XSLTResultTarget</jump>.
-Your input and output objects can each take the form of a URL or file, a stream, or a DOM tree.</p>
+<p>&xslt4c; takes as primary input an XML source document and an XSL stylesheet, both represented by instances of <jump href="apidocs/class_XSLTInputSource.html">XSLTInputSource</jump>. These input objects may each take the form of a file or URL, a stream, or a DOM tree. The stylesheet may also take the form of a compiled stylesheet (an instance of <jump href="apidocs/class_stylesheetroot.html">StylesheetRoot</jump>.</p>
+<note>If the XML source document contains a stylesheet Processing Instruction (PI), &xslt4c; uses the stylesheet this PI points to and a separate stylesheet object is not required. </note>
+<p>&xslt4c; uses &xml4c; to parse text input, performs the transformation, and sends the output to an instance of <jump href="apidocs/class_xsltresulttarget.html">XSLTResultTarget</jump>, which may be configured to write to a file, a stream, or a DOM tree.</p>
<p>For detailed API documentation, see <jump href="apidocs/index.html">Xalan C++ API</jump>. For an overview of the
command-line utility, see <link idref="commandline">Command-Line Utility</link>.</p>
</s2><anchor name="basic"/>
-<s2 title="Basic Procedure for Performing an XSL transformation">
+<s2 title="Basic procedure for performing an XSL transformation">
<p>When you are setting up your application to use XSL stylesheets to transform XML documents, you must do the following:</p>
<s3 title="1. Include the required header files">
<p>Along with any required Xalan-C and other header files, include utils/PlatformUtils.hpp from the Xerces-C distribution.</p>
@@ -105,10 +105,8 @@
theXObjectFactory,
theXPathFactory);
-// Connect the processor to the environment support object,
-// and use the parser liaison as the formatter.
-theXSLTProcessorEnvSupport.setProcessor(&theProcessor);
-theProcessor.setFormatter(&theParserLiaison);</source>
+// Connect the processor to the environment support object.
+theXSLTProcessorEnvSupport.setProcessor(&theProcessor);</source>
</s3>
<s3 title="4. Create context objects for the stylesheet">
<p>Use the processor and support objects to set up stylesheet construction context and execution context objects.</p>
@@ -143,19 +141,19 @@
</source>
<p>For the other constructors you can use to set up input and output objects (with input and output streams, for example), see <jump href="apidocs/class_xsltinputsource.html">XSLTInputSource</jump> and <jump href="apidocs/class_xsltresulttarget.html">XSLTResultTarget</jump>. See also <link anchor="dom">Working with
DOM input and output</link>.</p>
-</s3>
+</s3><anchor name="process"/>
<s3 title="6. Perform the transformation">
<p>Use the XSLTEngineImpl process() method to perform the transformation.</p>
<source>
theProcessor.process(
theInputSource,
- &theStylesheetSource,
+ theStylesheetSource,
theResultTarget,
theConstructionContext,
theExecutionContext);</source>
-<p>The XSLTResultTarget object now contains the transformation output.</p>
-<p>XSLTEngineImpl stores running state information, so it is not thread-safe. To perform multiple transformations, create a new instance for each transformation, synchronize the transformations, or call the XSLTProcessor reset() method between each transformation.</p>
-<p>If you are using the same stylesheet to perform multiple transformations, compile the stylesheet and use the StylesheetRoot process() method. StylesheetRoot objects are thread-safe. A single StylesheetRoot object may be called concurrently from multiple threads. For more information, see <link anchor="compiled">Compiling stylesheets</link>.</p>
+<p>The XSLTResultTarget object receives the transformation output.</p>
+<p>XSLTEngineImpl stores running state information, so it is not thread-safe. To perform multiple transformations, create a new instance for each transformation, or call the XSLTProcessor reset() method between each transformation.</p>
+<p>If you are using the same stylesheet to perform multiple transformations, for efficiency you should compile the stylesheet and use the appropriate XSLTEngineImpl process() method. Compiled stylesheet (StylesheetRoot) objects are also thread-safe. A single StylesheetRoot object may be called concurrently from multiple threads. For more information, see <link anchor="compiled">Compiling stylesheets</link>.</p>
<p>For a sample application that performs a transformation, see <link idref="samples" anchor="simpletransform">SimpleTransform</link>.</p>
</s3>
</s2><anchor name="dom"/>
@@ -193,17 +191,17 @@
DOM_Document domOut = theParserLiaison.mapXercesDocument(docOut)</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>An XSL stylesheet can include parameters that are set at run time before 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 one of the <jump href="apidocs/class_xsltengineimpl.html">XSLTEngineImpl</jump> setStylesheetParam() methods. Both methods take two arguments: the parameter name (a XalanDOMstring) and the expression (a XalanDOMString or an XObject). The XObject 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 stylesheet parameter.</p>
<note>If the expression is a string and you are using XalanDOMString for the input parameter, enclose it in single quotes to make it a string expression.</note>
<p>You can include the -param flag with two arguments when you call the <link idref="commandline">command line utility</link>. The first argument is the parameter name or key, and the second argument is the string expression (in single quotes). For example:</p>
-<p><code>TestXSLT -in foo.xml -xsl foo.xsl -param 'boo'</code></p>
+<p><code>TestXSLT -in foo.xml -xsl foo.xsl -param param1 'boo'</code></p>
<p>If the string expression includes spaces, first enclose the string in single quotes so it is interpreted as a string expression, and then enclose the resulting string in double quotes so it is interpreted as a single argument. For example:</p>
<p><code>TestXSLT -in foo.xml -xsl foo.xsl -param param1 "'hello there'"</code></p>
<p>The <link idref="samples" anchor="usestylesheetparam">UseStylesheetParam</link> sample application also uses a command-line parameter.</p>
</s2><anchor name="compiled"/>
<s2 title="Compiling stylesheets">
-<p>A <jump href="apidocs/class_stylesheetroot.html">StylesheetRoot</jump> object is a binary representation of a stylesheet that adds efficiency to the performance of repeated transformations and supports thread-safe concurrent access by multiple clients. If, for example, you are setting up a server application to perform transformations, you can improve performance by compiling any stylesheets the application repeatedly uses.</p>
+<p>When &xslt4c; performs a transformation with the <link anchor="process">XSLTEngineImpl process() method used above</link>, it starts by compiling the stylesheet into a binary representation. If you intend to use the same stylesheet to perform multiple transformations, you can enhance efficiency by explicitly compiling the stylesheet and using another XSLTEngimeImpl process() method for each transformation. A compiled stylesheet (a <jump href="apidocs/class_stylesheetroot.html">StylesheetRoot</jump> object) thread safe, so it even supports concurrent access by multiple clients. If, for example, you are setting up a server application to perform transformations, you can improve performance by compiling any stylesheets the application repeatedly uses.</p>
<p>A compiled stylesheet requires its own XPath and XObject factory support objects, independent of the support objects for an XSLT processor. So after you have set up the XSLT processor with its support objects, set up other
factory support objects and use them to create a construction context for the stylesheet:</p>
<source>// Set up the XSLT processor with its support objects
@@ -215,8 +213,8 @@
theXPathSupport);
XPathFactoryDefault theXPathFactory;
-// Create the processor, connect it to the environment support
-// object, and use the parser liaison as the formatter.
+// Create the processor and connect to the
+// environment support object.
XSLTEngineImpl theProcessor(
theParserLiaison,
theXPathSupport,
@@ -224,7 +222,6 @@
theXObjectFactory,
theXPathFactory);
theXSLTProcessorEnvSupport.setProcessor(&theProcessor);
-theProcessor.setFormatter(&theParserLiaison);
...
// Create factory support objects for the stylesheet, so it will
// have its own factory-created XObject and XPath instances
@@ -249,40 +246,50 @@
theXSLTProcessorEnvSupport,
theXPathSupport,
theXObjectFactory);</source>
-<p>To compile a stylesheet, use the <jump href="apidocs/class_xsltengineimpl.html">XSLTEngineImpl</jump> processStylesheet() method. This operation also sets the XSLTEngineImpl Stylesheet property. In the interest of clarity, you may want to use the setStylesheet() method to explicitly set that property. Then when you call the process method, include a 0 for the "uncompiled" stylesheet parameter so XSLTEngineImpl uses the compiled stylesheet. For example:</p>
+<p>Compile the stylesheet, add the StylesheetRoot object to the execution context, and start performing transformations. Use the XSLTEngineImpl process() method (see below) that takes advantage of the compiled stylesheet. Be sure to reset the processer and execution context between each transformation. For example:</p>
<source>
// Compile the stylesheet.
StylesheetRoot* const theStylesheetRoot =
theProcessor.processStylesheet(
theStylesheetSource,
theConstructionContext);
-
-theProcessor.setStylesheet(theStylesheetRoot) // Good form!
+
+// Set the execution context object to use the compiled stylesheet.
+theExecutionContext.setStylesheetRoot(theStylesheetRoot)
// Set up an XSLTInputSource object (theInputSource)
// and an XSLTResultTarget object (theResultTarget).
...
-// Do the transformation...
+// Do the transformation. This version of the process() method uses
+// the StylesheetRoot object associated with the execution context.
theProcessor.process(
theInputSource,
- 0, //Use the StylesheetRoot
theResultTarget,
- theConstructionContext,
theExecutionContext);
// Reset the processor and the execution context
// so we can perform the next transformation.
theProcessor.reset();
-theProcessor.setStylesheet(theStylesheetRoot);
theExecutionContext.reset();
+theExecutionContext.setStylesheetRoot(theStylesheetRoot);
// Perform the next transformation.
....</source>
<p>For an example, see the <link idref="samples" anchor="compilestylesheet">CompileStylesheet</link> sample.</p>
-<p>Alternative: StylesheetRoot has its own process method, which you can also use to perform transformations.</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 programmatically and do your own processing without a stylesheet.</p>
<p>For an example that executes XPath expressions against XML source files, see <link idref="samples" anchor="xpath">XPathWrapper</link>.</p>
+</s2><anchor name="tracelistener"/>
+<s2 title="Using TraceListener">
+<p>TraceListener is a debugging abstract base class implemented by TraceListenerDefault. You can use TraceListener to trace any combination of the folllowing:</p>
+<ul>
+ <li>Calls to templates</li>
+ <li>Calls to template children</li>
+ <li>Selection events</li>
+ <li>Result tree generation events</li>
+ </ul>
+<p>To construct a TraceListener with TraceListenerDefault, you need a PrintWriter and a boolean for each of these four tracing options. You can then use the XSLTEngimeImpl setTraceSelects and addTraceListener methods to add the TraceListener to an XSLTProcessor. See the <link idref="samples" anchor="tracelisten">TraceListen</link> sample application.</p>
+<p>The <link idref="commandline">command-line utility (TextXSLT)</link> and TraceListen both use TraceListenerDefault to write events to the screen.</p>
</s2>
</s1>