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="[email protected]"/>
<human-resource id="sboag" name="Scott Boag" mailto="[EMAIL PROTECTED]"/>
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>
