dleslie 00/05/08 12:23:05
Added: c/xdocs/sources entities.ent xalan.xml xalanLocal.xml
c/xdocs/sources/xalan commandline.xml extensions.xml faq.xml
getstarted.xml index.xml overview.xml readme.xml
resources.xml samples.xml usagepatterns.xml
Removed: c/xdocs/sources/xalan xslt4c.xml
Log:
Preliminary and partial draft for Xalan-C 1.0.0.
Revision Changes Path
1.1 xml-xalan/c/xdocs/sources/entities.ent
Index: entities.ent
===================================================================
<?xml encoding="US-ASCII"?>
<!ENTITY xslt4j "Xalan-J">
<!ENTITY xml4j "Xerces-J">
<!ENTITY xslt4c "Xalan-C">
<!ENTITY xml4c "Xerces-C">
<!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.1 xml-xalan/c/xdocs/sources/xalan.xml
Index: xalan.xml
===================================================================
<?xml version="1.0"?>
<!DOCTYPE book SYSTEM "sbk:/style/dtd/book.dtd">
<!--
* The Apache Software License, Version 1.1
*
*
* Copyright (c) 2000 The Apache Software Foundation. All rights
* reserved.
*
* Redistribution and use in source and binary forms, with or without
* modification, are permitted provided that the following conditions
* are met:
*
* 1. Redistributions of source code must retain the above copyright
* notice, this list of conditions and the following disclaimer.
*
* 2. Redistributions in binary form must reproduce the above copyright
* notice, this list of conditions and the following disclaimer in
* the documentation and/or other materials provided with the
* distribution.
*
* 3. The end-user documentation included with the redistribution,
* if any, must include the following acknowledgment:
* "This product includes software developed by the
* Apache Software Foundation (http://www.apache.org/)."
* Alternately, this acknowledgment may appear in the software itself,
* if and wherever such third-party acknowledgments normally appear.
*
* 4. The names "Xalan" and "Apache Software Foundation" must
* not be used to endorse or promote products derived from this
* software without prior written permission. For written
* permission, please contact [EMAIL PROTECTED]
*
* 5. Products derived from this software may not be called "Apache",
* nor may "Apache" appear in their name, without prior written
* permission of the Apache Software Foundation.
*
* THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED
* WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
* OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
* DISCLAIMED. IN NO EVENT SHALL THE APACHE SOFTWARE FOUNDATION OR
* ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
* SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
* LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
* USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
* ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
* OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
* OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
* SUCH DAMAGE.
* ====================================================================
*
* This software consists of voluntary contributions made by many
* individuals on behalf of the Apache Software Foundation and was
* originally based on software copyright (c) 1999, Lotus
* Development Corporation., http://www.lotus.com. For more
* information on the Apache Software Foundation, please see
* <http://www.apache.org/>.
-->
<book title="Xalan-C XSL Transformer User's Guide" copyright="2000 The Apache
Software Foundation">
<resources source="sbk:/sources/xalan/resources.xml"/>
<external href="../index.html" label="Home"/>
<separator/>
<document id="index"
label="Xalan-C 1.0.0"
source="xalan/index.xml"/>
<separator/>
<external href="getstarted.html#download" label="Downloads"/>
<document id="overview"
label="Overview"
source="xalan/overview.xml"/>
<separator/>
<document id="getstarted"
label="Getting Started"
source="xalan/getstarted.xml"/>
<separator/>
<faqs id="faq"
label="FAQs"
source="xalan/faq.xml" />
<separator/>
<document id="samples"
label="Sample Apps"
source="xalan/samples.xml"/>
<document id="commandline"
label="Command Line"
source="xalan/commandline.xml"/>
<document id="usagepatterns"
label="Usage Patterns"
source="xalan/usagepatterns.xml"/>
<separator/>
<external href="apidocs/index.html" label="C++ API"/>
<separator/>
<document id="extensions"
label="Extensions"
source="xalan/extensions.xml"/>
<separator/>
<document id="readme"
label="Release Notes"
source="xalan/readme.xml"/>
<separator/>
<external href="http://xml.apache.org/bugs/"; label="Bug reporting"/>
<separator/>
</book>
1.1 xml-xalan/c/xdocs/sources/xalanLocal.xml
Index: xalanLocal.xml
===================================================================
<?xml version="1.0"?>
<!DOCTYPE book SYSTEM "sbk:/style/dtd/book.dtd">
<!--
* The Apache Software License, Version 1.1
*
*
* Copyright (c) 2000 The Apache Software Foundation. All rights
* reserved.
*
* Redistribution and use in source and binary forms, with or without
* modification, are permitted provided that the following conditions
* are met:
*
* 1. Redistributions of source code must retain the above copyright
* notice, this list of conditions and the following disclaimer.
*
* 2. Redistributions in binary form must reproduce the above copyright
* notice, this list of conditions and the following disclaimer in
* the documentation and/or other materials provided with the
* distribution.
*
* 3. The end-user documentation included with the redistribution,
* if any, must include the following acknowledgment:
* "This product includes software developed by the
* Apache Software Foundation (http://www.apache.org/)."
* Alternately, this acknowledgment may appear in the software itself,
* if and wherever such third-party acknowledgments normally appear.
*
* 4. The names "Xalan" and "Apache Software Foundation" must
* not be used to endorse or promote products derived from this
* software without prior written permission. For written
* permission, please contact [EMAIL PROTECTED]
*
* 5. Products derived from this software may not be called "Apache",
* nor may "Apache" appear in their name, without prior written
* permission of the Apache Software Foundation.
*
* THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED
* WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
* OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
* DISCLAIMED. IN NO EVENT SHALL THE APACHE SOFTWARE FOUNDATION OR
* ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
* SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
* LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
* USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
* ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
* OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
* OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
* SUCH DAMAGE.
* ====================================================================
*
* This software consists of voluntary contributions made by many
* individuals on behalf of the Apache Software Foundation and was
* originally based on software copyright (c) 1999, Lotus
* Development Corporation., http://www.lotus.com. For more
* information on the Apache Software Foundation, please see
* <http://www.apache.org/>.
-->
<book title="Xalan-C XSL Transformer User's Guide" copyright="2000 The Apache
Software Foundation">
<resources source="sbk:/sources/xalan/resources.xml"/>
<document id="overview"
label="Overview"
source="xalan/overview.xml"/>
<separator/>
<external href="getstarted.html#download" label="Downloads"/>
<document id="getstarted"
label="Getting Started"
source="xalan/getstarted.xml"/>
<separator/>
<faqs id="faq"
label="FAQs"
source="xalan/faq.xml" />
<separator/>
<document id="samples"
label="Sample Apps"
source="xalan/samples.xml"/>
<document id="commandline"
label="Command Line"
source="xalan/commandline.xml"/>
<document id="usagepatterns"
label="Usage Patterns"
source="xalan/usagepatterns.xml"/>
<separator/>
<external href="apidocs/index.html" label="C++ API"/>
<separator/>
<document id="extensions"
label="Extensions"
source="xalan/extensions.xml"/>
<separator/>
<document id="readme"
label="Release Notes"
source="xalan/readme.xml"/>
<separator/>
<external href="http://xml.apache.org/bugs/"; label="Bug reporting"/>
</book>
1.1 xml-xalan/c/xdocs/sources/xalan/commandline.xml
Index: commandline.xml
===================================================================
<?xml version="1.0" standalone="no"?>
<!DOCTYPE s1 SYSTEM "sbk:/style/dtd/document.dtd">
<!--
* The Apache Software License, Version 1.1
*
*
* Copyright (c) 1999 The Apache Software Foundation. All rights
* reserved.
*
* Redistribution and use in source and binary forms, with or without
* modification, are permitted provided that the following conditions
* are met:
*
* 1. Redistributions of source code must retain the above copyright
* notice, this list of conditions and the following disclaimer.
*
* 2. Redistributions in binary form must reproduce the above copyright
* notice, this list of conditions and the following disclaimer in
* the documentation and/or other materials provided with the
* distribution.
*
* 3. The end-user documentation included with the redistribution,
* if any, must include the following acknowledgment:
* "This product includes software developed by the
* Apache Software Foundation (http://www.apache.org/)."
* Alternately, this acknowledgment may appear in the software itself,
* if and wherever such third-party acknowledgments normally appear.
*
* 4. The names "Xalan" and "Apache Software Foundation" must
* not be used to endorse or promote products derived from this
* software without prior written permission. For written
* permission, please contact [EMAIL PROTECTED]
*
* 5. Products derived from this software may not be called "Apache",
* nor may "Apache" appear in their name, without prior written
* permission of the Apache Software Foundation.
*
* THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED
* WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
* OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
* DISCLAIMED. IN NO EVENT SHALL THE APACHE SOFTWARE FOUNDATION OR
* ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
* SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
* LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
* USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
* ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
* OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
* OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
* SUCH DAMAGE.
* ====================================================================
*
* This software consists of voluntary contributions made by many
* individuals on behalf of the Apache Software Foundation and was
* originally based on software copyright (c) 1999, Lotus
* Development Corporation., http://www.lotus.com. For more
* information on the Apache Software Foundation, please see
* <http://www.apache.org/>.
-->
<s1 title="Command-Line Utility">
<s2 title="Using the Command-Line Utility">
<p>To perform a transformation, you can call &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
for performing XSL transformation. To perform a transformation from the
command line or a script,
do the following:</p>
<ol>
<li><link idref="getstarted" anchor="download">Download
&xslt4c;</link>.<br/><br/></li>
<li><link idref="getstarted"
anchor="classpath">Set the path</link> to include the build
directory.<br/><br/></li>
<li>Call the TestXSLT executable with the appropriate flags and
arguments (described below). The following command line, for example,
includes the -IN, -XSL,
and -OUT flags with their accompanying arguments -- the XML source
document, the XSL
stylesheet, and the output file:<br/><br/>
<code>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>
<source>-IN inputXMLURL
-XSL XSLTransformationURL
-OUT outputFileName
-LXCIN compiledStylesheetFileNameIn
-LXCOUT compiledStylesheetFileNameOut
-PARSER fully qualified class name of parser liaison
-V (Version info)
-QC (Quiet Pattern Conflicts Warnings)
-Q (Quiet Mode)
-LF (Use linefeeds only on output -- default is CR/LF)
-CR (Use carriage returns only on output -- default is CR/LF)
-INDENT (Number of spaces to indent each level in output tree --default is 0)
-TT (Trace the templates as they are being called)
-TG (Trace each result tree generation event)
-TS (Trace each selection event)
-TTC (Trace the template children as they are being processed)
-VALIDATE (Validate the XML and XSL input -- validation is off by default)
-EDUMP [optional]FileName (Do stackdump on error)
-XML (Use XML formatter and add XML header)
-TEXT (Use simple Text formatter)
-HTML (Use HTML formatter)
-PARAM name expression (Set a stylesheet parameter)</source>
<p>Use -IN to specify the XML source document.</p>
<p>Use -XSL to specify the XSL stylesheet file.</p>
<p>Use -LXCIN to specify a compiled XSL stylesheet file.</p>
<p>Use -LXCOUT to compile an XSL stylesheet for future use as -LXCIN
input.</p>
<note>You can only use -LXCIN with a compiled stylesheet that you have
already created with the -LXOUT switch. For an
example, see <link anchor="compiledstylesheet">Using a compiled
stylesheet</link></note>
<p>Include -PARSER if you supply your own parser liaison class, which
is required if you do not use the
Xerces parser.</p>
<p>Use -TEXT if you want the output to include only element values (not
element tags with element names and
attributes).</p>
<p>Use -HTML to write 4.0 transitional HTML (some elements, such as
<br>, are
not well formed.</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
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.1 xml-xalan/c/xdocs/sources/xalan/extensions.xml
Index: extensions.xml
===================================================================
<?xml version="1.0" standalone="no"?>
<!--
* The Apache Software License, Version 1.1
*
*
* Copyright (c) 1999 The Apache Software Foundation. All rights
* reserved.
*
* Redistribution and use in source and binary forms, with or without
* modification, are permitted provided that the following conditions
* are met:
*
* 1. Redistributions of source code must retain the above copyright
* notice, this list of conditions and the following disclaimer.
*
* 2. Redistributions in binary form must reproduce the above copyright
* notice, this list of conditions and the following disclaimer in
* the documentation and/or other materials provided with the
* distribution.
*
* 3. The end-user documentation included with the redistribution,
* if any, must include the following acknowledgment:
* "This product includes software developed by the
* Apache Software Foundation (http://www.apache.org/)."
* Alternately, this acknowledgment may appear in the software itself,
* if and wherever such third-party acknowledgments normally appear.
*
* 4. The names "Xalan" and "Apache Software Foundation" must
* not be used to endorse or promote products derived from this
* software without prior written permission. For written
* permission, please contact [EMAIL PROTECTED]
*
* 5. Products derived from this software may not be called "Apache",
* nor may "Apache" appear in their name, without prior written
* permission of the Apache Software Foundation.
*
* THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED
* WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
* OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
* DISCLAIMED. IN NO EVENT SHALL THE APACHE SOFTWARE FOUNDATION OR
* ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
* SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
* LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
* USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
* ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
* OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
* OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
* SUCH DAMAGE.
* ====================================================================
*
* This software consists of voluntary contributions made by many
* individuals on behalf of the Apache Software Foundation and was
* originally based on software copyright (c) 1999, Lotus
* Development Corporation., http://www.lotus.com. For more
* information on the Apache Software Foundation, please see
* <http://www.apache.org/>.
-->
<!DOCTYPE s1 SYSTEM "sbk:/style/dtd/document.dtd">
<s1 title="&xslt4c; Extension Functions">
<ul>
<li><link anchor="intro">Introduction</link></li>
<li><link anchor="implement">Implementing an extension function</link></li>
<li><link anchor="install">Installing an extension function</link></li>
<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>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>
</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
extension function class as follows:</p>
<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
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>
</ol>
<p>These features all appear in the following example.</p>
<source>#include <cmath>
#include <XPath/XObjectFactoryDefault.hpp>
#include <XPath/XPath.hpp>
// This class defines a function that will return the square root
// of its argument.
class FunctionSquareRoot : public Function
{
public:
/**
* Execute an XPath function object. The function must return a valid
* XObject.
*
* @param executionContext executing context
* @param context current context node
* @param opPos current op position
* @param args vector of pointers to XObject arguments
* @return pointer to the result XObject
*/
virtual XObject*
execute(
XPathExecutionContext& executionContext,
XalanNode* context,
int /* opPos */,
const XObjectArgVectorType& args)
{
if (args.size() != 1)
{
executionContext.error("The square-root() function takes one
argument!",
context);
}
assert(args[0] != 0);
// Use the XObjectFactory createNumber() method to create an XObject
// corresponding to the XSLT number data type.
return executionContext.getXObjectFactory().createNumber(
sqrt(args[0]->num()));
}
/**
* Implement clone() so Xalan can copy the square-root function into
* its own function table.
*
* @return pointer to the new object
*/
#if defined(XALAN_NO_COVARIANT_RETURN_TYPE)
virtual Function*
#else
virtual FunctionSquareRoot*
#endif
clone() const
{
return new FunctionSquareRoot(*this);
}
private:
// The assignment and equality operators are not implemented...
FunctionSquareRoot&
operator=(const FunctionSquareRoot&);
bool
operator==(const FunctionSquareRoot&) const;
}</source>
</s2><anchor name="install"/>
<s2 title="Installing an extension function">
<p>When you set up an XSLT processor, you instantiate an
XSLTProcessorEnvSupportDefault object, which provides
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>
</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>
<source>// You have created a header file for FunctionSquareRoot.
#include <MyFunctions/FunctionSquareRoot.hpp>
// The namespace...
const XalanDOMString
theNamespace("http://ExternalFunction.xalan-c++.xml.apache.org";);
// Install the function in the global space so all processor
// instances can use it.
XSLTProcessorEnvSupportDefault::installExternalFunctionGlobal(
theNamespace,
"square-root",
FunctionSquareRoot());</source>
<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"/>
<s2 title="Using an extension function">
<p>To use the extension function in a stylesheet, you must do the
following:</p>
<ol>
<li>Declare the extension function namespace.<br/><br/>
<code>xmlns:<ref>prefix</ref>=<ref>URI</ref></code><br/><br/>
The <ref>prefix</ref> identifies the namespace, and <ref>URI</ref> matches
the namespace specified when the function
is installed.<br/><br/>
By default, namespace declarations are included in the transformation output.
To exclude namespaces from the output,
use<br/><br/>
<code>exclude-result-prefixes="<ref>prefix-1 prefix-2
...</ref>"</code><br/><br/>
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/>
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
<code><area value="397"/></code>, where the value attribute identifies
the area of a square.</p>
<p>The following stylesheet declares the square-root function namespace (the
prefix is up to you), instructs
the processor not to copy the namespace declaration to the result tree, and
uses the square-root function to return
the square root of //area/@value:</p>
<source><?xml version="1.0"?>
<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform";
version="1.0"
xmlns:external="http://ExternalFunction.xalan-c++.xml.apache.org";
exclude-result-prefixes="external">
<xsl:template match="//area">
<out>
The area of the square is
<xsl:value-of select="@value"/> square units.
The length of each side is
<xsl:value-of select="external:square-root(@value)"/> units
</out></source>
<p>This stylesheet converts <code><area value="397"/></code> into the
following output:</p>
<source><out>
The area of the square is
397 square units.
The length of each side is
19.9249 units.
</out></source>
<p>For a slightly more complex variation on this example,
see the <link idref="samples" anchor="externalfunc">External Functions</link>
sample.</p>
<s3 title="Passing Nodes to a function">
<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>Suppose, for example, you have a ProcessNodes function class that
uses<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><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/>
<code><xsl:variable name="success"
select="node-ext:ProcessNodes(*)"/></code></p>
<p><code><!-- Process all nodes --></code><br/>
<code><xsl:variable name="success"
select="node-ext:ProcessNodes(/*)"/></code></p>
<p><code><!--Process the foo/baz nodes in current context --></code><br/>
<code><xsl:variable name="success"
select="node-ext:ProcessNodes(foo/baz)"/></code></p>
<p><code><!--Process the/foo/baz and /bar/saz nodes --></code><br/>
<code><xsl:variable name="success" select="node-ext:ProcessNodes(/foo/baz
| /bar/saz)"/></code></p>
<p>The NodeRefListBase is in fact a list of references into the XML document,
so keep in mind that getNextSibling(),
for example, gets you the next sibling in the document, which may not be the
next Node in the node-set.</p>
</s3>
</s2>
</s1>
1.1 xml-xalan/c/xdocs/sources/xalan/faq.xml
Index: faq.xml
===================================================================
<?xml version="1.0" standalone="no"?>
<!DOCTYPE faqs SYSTEM "sbk:/style/dtd/faqs.dtd">
<faqs title="Frequently asked questions">
<faq title="Where do I go to learn about XSLT">
<q>Where do I go to learn about XSLT?</q>
<a><p>The definitive sources are the W3C XSLT and XPath recommendations:
<resource-ref idref="XSLT"/> and
<resource-ref idref="XPath"/>.</p>
<p>For general questions not specific to &xslt4c;, see Dave Pawson's <jump
href="http://freespace.virgin.net/b.pawson/xsl/index.html#top";>XSL
Frequently Asked Questions</jump>.</p>
<p>For a brief listing of tutorials, discussion forums, and other
materials, see <link idref="overview"
anchor="uptospeed">Getting up to speed with XSLT</link>.</p></a>
</faq>
<faq title="Which version of Xerces should I be using?">
<q>Which version of Xerces should I be using?</q>
<a><p>The &xslt4c; release notes includes information about the Xerces-C
release with which the &xslt4c; release has been coordinated and tested. See
<link idref="readme" anchor="status">Status</link></p></a>
</faq>
<faq title="Are the XSLTEngineImpl (XSLT processor) and StylesheetRoot
(compiled stylesheet) objects thread-safe?">
<q>Are the XSLTEngineImpl (XSLT processor) and StylesheetRoot (compiled
stylesheet) objects thread-safe?</q>
<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.
If you want to perform multiple serial transformations with a single
XSLTEngineImpl object, call the XSLTEngineImpl reset()
method between each transformation.</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>
<p>For more detail, see <link idref="samples"
anchor="compilestylesheet"></link>.</p></a>
</faq>
<faq title="What can I do to speed up transformations?">
<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>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>
<li>Use xsl:key elements and the key() function as an efficient way
to retrieve node sets.<br/><br/></li>
<li>Where possible, use pattern matching rather than xsl:if or
xsl:when statements.<br/><br/></li>
<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>
<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>
<a>
<p>An XSL stylesheet is an XML document, so it can have a DOCTYPE and
be subject to validation, right? </p>
<p>The XSLT Recommendation includes a <jump
href="http://www.w3.org/TR/xslt#dtd";>DTD Fragment
for XSL Stylesheets</jump> with some indications of what you need to do
to create a complete DTD for a given
stylesheet. Keep in mind that stylesheets can include literal result
elements and produce output that is not valid
XML.</p>
<p>You can use the xsl:stylesheet doctype defined in xsl-html40s.dtd
for stylesheets that generate HTML.</p>
</a>
</faq>
</faqs>
1.1 xml-xalan/c/xdocs/sources/xalan/getstarted.xml
Index: getstarted.xml
===================================================================
<?xml version="1.0" standalone="no"?>
<!DOCTYPE s1 SYSTEM "sbk:/style/dtd/document.dtd">
<s1 title="Getting Started">
<ul>
<li><link anchor="download">Downloading what you need</link></li>
<li><link anchor="path">Setting up the system path</link></li>
<li><link anchor="samples">Trying out the samples</link></li>
<li><link anchor="commandline">Performing your own transformations from the
command line</link></li>
<li><link anchor="apps">Setting up your own XSLT applications</link></li>
</ul>
<anchor name="download"/>
<p>For Xalan-C 1.0.0, we are distributing a Windows32 build and a Linux
build. In the future, we intend to add more
builds.</p>
<s2 title="Downloading what you need">
<p>To run the Xalan command-line utility for performing transformations, you
need the following:</p>
<ul>Windows
<li> The utility: TestXSLT.exe (Windows32), TestXSLT (Linux)</li>
<li>The 8 Xalan-C dynamic link libraries Windows32): DOMSupport.dll,
PlatformSupport.dll, XalanDOM.dll, XercesParserLiaison.dll;
XercesPlatformSupport.dll, XMLSupport.dll, XPath.dll, XSLT.dll</li>
<li>The Xerces-C dynamic link library to which the Xalan-C dlls are linked:
xerces-c_1_1.dll</li>
Linux
</ul>
<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>.
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>.
Both of these files contain the Xalan dlls and command-line utility
(TextXSLT.exe), along with the Xerces-C 1.1.0 dynamic link library
(xerces-c_1_1.dll). You can use a zip or tar utility to expand these files into
a full build.</p>
<p>To build your own &xslt4c; applications, you also need need the Xalan-C
and Xerces-C header files and libraries. The Xalan-C header files are in the
source tree in both distributions: xml-xalan/c/src. In the Windows32
distribution (built with Microsoft Visual C++ 6.0), the dlls and libraries are
in xml-xalan/Build/Win32/VC6/Release. In the Linux distribution (built with
make), the shared object libraries are in xml-xalan/c/lib.</p>
<p>To get the Xerces-C source tree, download the Xerces-C 1.1.? Source
distribution from the <resource-ref idref="Xerces-c-dist"/>. </p>
</s2><anchor name="path"/>
<s2 title="Setting up the system path">
<p>The Xalan-C distribution includes a build directory with the Xalan and
Xerces dlls listed above, and the executables for the sample applications.
Include this directory on your system plath. If you do your own Xalan and
Xerces builds, be sure to include the directories that contain these dlls and
executables on your system path.</p>
</s2><anchor name="samples"/>
<s2 title="Trying out the samples">
<p>The &xslt4c; 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>
<p>To run the samples, do the following:</p>
<ol>
<li>Set up your path(see above), including the directory with the sample
executables.</li>
<li>Go to the samples subdirectory containing the sample (use the DOS shell
if you are running Windows).</li>
<li>Run the sample from the command line.</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 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 all the samples, see <link
idref="samples">&xslt4c; Samples</link>.</p>
</s2><anchor name="commandline"/>
<s2 title="Performing your own transformations from the command line">
<p>TestXSLT.exe provides a basic utility for performing transformations from
the command line. The command line for
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>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. Here are some basic points to keep
in mind as you are setting up transformations:</p>
<p>For more information on setting up applications, see <link
idref="usagepatterns">Basic Usage Patterns</link>.</p>
</s2>
</s1>
1.1 xml-xalan/c/xdocs/sources/xalan/index.xml
Index: index.xml
===================================================================
<?xml version="1.0" standalone="no"?>
<!--
* The Apache Software License, Version 1.1
*
*
* Copyright (c) 1999 The Apache Software Foundation. All rights
* reserved.
*
* Redistribution and use in source and binary forms, with or without
* modification, are permitted provided that the following conditions
* are met:
*
* 1. Redistributions of source code must retain the above copyright
* notice, this list of conditions and the following disclaimer.
*
* 2. Redistributions in binary form must reproduce the above copyright
* notice, this list of conditions and the following disclaimer in
* the documentation and/or other materials provided with the
* distribution.
*
* 3. The end-user documentation included with the redistribution,
* if any, must include the following acknowledgment:
* "This product includes software developed by the
* Apache Software Foundation (http://www.apache.org/)."
* Alternately, this acknowledgment may appear in the software itself,
* if and wherever such third-party acknowledgments normally appear.
*
* 4. The names "Xalan" and "Apache Software Foundation" must
* not be used to endorse or promote products derived from this
* software without prior written permission. For written
* permission, please contact [EMAIL PROTECTED]
*
* 5. Products derived from this software may not be called "Apache",
* nor may "Apache" appear in their name, without prior written
* permission of the Apache Software Foundation.
*
* THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED
* WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
* OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
* DISCLAIMED. IN NO EVENT SHALL THE APACHE SOFTWARE FOUNDATION OR
* ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
* SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
* LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
* USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
* ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
* OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
* OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
* SUCH DAMAGE.
* ====================================================================
*
* This software consists of voluntary contributions made by many
* individuals on behalf of the Apache Software Foundation and was
* originally based on software copyright (c) 1999, Lotus
* Development Corporation., http://www.lotus.com. For more
* information on the Apache Software Foundation, please see
* <http://www.apache.org/>.
-->
<!DOCTYPE s1 SYSTEM "sbk:/style/dtd/document.dtd">
<s1 title="Xalan-C Version 1.0.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 Transformations
(XSLT) and the XML Path Language (XPath).</p>
<p>Xalan-C uses the Xerces-C XML parser.</p>
</s2>
<s2 title="How do I get it?">
<p>Download and unzip either of the following:</p>
<ul>
<li><jump
href="http://xml.apache.org/dist/xalan-j/xalan-j_1_0_1.zip";>xalan-j_1_0_0.zip</jump></li>
<li><jump
href="http://xml.apache.org/dist/xalan-j/xalan-j_1_0_1.tar.gz";>xalan-j_1_0_0.tar.gz</jump></li>
</ul>
</s2>
<s2 title="Where do I get Xerces?">
<p>The Xalan-C dowload includes xerces-c_1_1.dll from Xerces-C 1.0.3.
This provides the Xerces runtime environment for
Xalan.To build applications with Xalan and the Xerces XML parser, you
also need the Xerces-C source tree, which you can
obtain by downloading the Xerces-C Source distribution from the
<resource-ref idref="Xeces-c-dist"/>.</p>
</s2>
<s2 title="For more information...">
<p>For more information, go to <link idref="overview">Xalan
Overview</link> and <link idref="getstarted">Getting
Started</link>. All of the Xalan documentation on this website is
included in the Xalan download, as are a number of samples
to help you start using Xalan to transform XML documents.</p>
</s2>
</s1>
1.1 xml-xalan/c/xdocs/sources/xalan/overview.xml
Index: overview.xml
===================================================================
<?xml version="1.0" standalone="no"?>
<!DOCTYPE s1 SYSTEM "sbk:/style/dtd/document.dtd">
<!--
* The Apache Software License, Version 1.1
*
*
* Copyright (c) 1999 The Apache Software Foundation. All rights
* reserved.
*
* Redistribution and use in source and binary forms, with or without
* modification, are permitted provided that the following conditions
* are met:
*
* 1. Redistributions of source code must retain the above copyright
* notice, this list of conditions and the following disclaimer.
*
* 2. Redistributions in binary form must reproduce the above copyright
* notice, this list of conditions and the following disclaimer in
* the documentation and/or other materials provided with the
* distribution.
*
* 3. The end-user documentation included with the redistribution,
* if any, must include the following acknowledgment:
* "This product includes software developed by the
* Apache Software Foundation (http://www.apache.org/)."
* Alternately, this acknowledgment may appear in the software itself,
* if and wherever such third-party acknowledgments normally appear.
*
* 4. The names "Xalan" and "Apache Software Foundation" must
* not be used to endorse or promote products derived from this
* software without prior written permission. For written
* permission, please contact [EMAIL PROTECTED]
*
* 5. Products derived from this software may not be called "Apache",
* nor may "Apache" appear in their name, without prior written
* permission of the Apache Software Foundation.
*
* THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED
* WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
* OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
* DISCLAIMED. IN NO EVENT SHALL THE APACHE SOFTWARE FOUNDATION OR
* ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
* SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
* LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
* USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
* ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
* OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
* OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
* SUCH DAMAGE.
* ====================================================================
*
* This software consists of voluntary contributions made by many
* individuals on behalf of the Apache Software Foundation and was
* originally based on software copyright (c) 1999, Lotus
* Development Corporation., http://www.lotus.com. For more
* information on the Apache Software Foundation, please see
* <http://www.apache.org/>.
-->
<s1 title="&xslt4c; Overview">
<ul>
<li><link anchor="intro">Introduction</link></li>
<li><link anchor="features">&xslt4c; Features</link></li>
<li><link anchor="towork">Getting to work with &xslt4c;</link></li>
<li><link anchor="uptospeed">Getting up to speed with XSLT</link></li>
<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
<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
to speed with XSLT</link>.</p>
<note>XSL also includes a vocabulary for formatting documents, which is
still under design and is not part of &xslt4c;.
For more information, see <jump href="http://www.w3.org/TR/xsl/";>W3C XSL
Working Draft</jump> and the <jump
href="http://xml.apache.org/fop";>Apache XML FOP (Formatting Objects
Project)</jump>.</note>
<p>You use the XSLT language to compose XSL stylesheets. An XSL
stylesheet contains instructions for
transforming XML documents from one document type into 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>
<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"?>
<doc>Hello</doc></source>
<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>
</xsl:template>
</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>
</ul>
</s2><anchor name="towork"/>
<s2 title="Getting to work with &xslt4c;">
<p>For instructions and some suggestions about how to get started using
&xslt4c;, see
<link idref="getstarted">Getting Started</link>.</p>
</s2><anchor name="uptospeed"/>
<s2 title="Getting up to speed with XSLT">
<p>If you are still working through the details of the XSLT spec (the W3C
1.0 Recommendation), you may want
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>
<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>
(of interest to XSL users at all levels)<br/><br/></li>
<li>Dave Pawson's <jump
href="http://freespace.virgin.net/b.pawson/xsl/index.html#top";>XSL Frequently
Asked
Questions</jump><br/><br/></li>
<li>Objects by Design's <jump
href="http://www.objectsbydesign.com/projects/xmi_to_html.html";>Transforming
XMI to
HTML</jump> (oriented towards XMI, "an XML-based, stream representation
of a UML model," but also covers "generic"
XML transformations)<br/><br/></li>
<li>Nic Miloslav's <jump
href="http://zvon.vscht.cz/HTMLonly/XSLTutorial/Books/Book1/index.html";>XSL
Tutorial</jump>
<br/><br/></li>
<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>
</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>
</s2><anchor name="glossary"/>
<s2 title="Glossary">
<gloss>
<label>XSL Instruction</label>
<item>Any tag with an XSL namespace prefix.<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>
<label>Source Tree</label>
<item>The 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>
<label>Stylesheet Tree</label>
<item>The stylesheet tree produced from the XSL file.<br/><br/></item>
<label>Match Pattern</label>
<item>The part of a template that defines the kind(s) of nodes to
which the template applies.<br/><br/></item>
</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>
</s2>
</s1>
1.1 xml-xalan/c/xdocs/sources/xalan/readme.xml
Index: readme.xml
===================================================================
<?xml version="1.0" standalone="no"?>
<!DOCTYPE s1 SYSTEM "sbk:/style/dtd/document.dtd"[
<!ENTITY done-c SYSTEM "DONE">
<!ENTITY status-c SYSTEM "STATUS">
<!ENTITY bugs-c SYSTEM "BUGS">]>
<!--
* The Apache Software License, Version 1.1
*
*
* Copyright (c) 1999 The Apache Software Foundation. All rights
* reserved.
*
* Redistribution and use in source and binary forms, with or without
* modification, are permitted provided that the following conditions
* are met:
*
* 1. Redistributions of source code must retain the above copyright
* notice, this list of conditions and the following disclaimer.
*
* 2. Redistributions in binary form must reproduce the above copyright
* notice, this list of conditions and the following disclaimer in
* the documentation and/or other materials provided with the
* distribution.
*
* 3. The end-user documentation included with the redistribution,
* if any, must include the following acknowledgment:
* "This product includes software developed by the
* Apache Software Foundation (http://www.apache.org/)."
* Alternately, this acknowledgment may appear in the software itself,
* if and wherever such third-party acknowledgments normally appear.
*
* 4. The names "Xalan" and "Apache Software Foundation" must
* not be used to endorse or promote products derived from this
* software without prior written permission. For written
* permission, please contact [EMAIL PROTECTED]
*
* 5. Products derived from this software may not be called "Apache",
* nor may "Apache" appear in their name, without prior written
* permission of the Apache Software Foundation.
*
* THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED
* WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
* OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
* DISCLAIMED. IN NO EVENT SHALL THE APACHE SOFTWARE FOUNDATION OR
* ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
* SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
* LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
* USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
* ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
* OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
* OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
* SUCH DAMAGE.
* ====================================================================
*
* This software consists of voluntary contributions made by many
* individuals on behalf of the Apache Software Foundation and was
* originally based on software copyright (c) 1999, Lotus
* Development Corporation., http://www.lotus.com. For more
* information on the Apache Software Foundation, please see
* <http://www.apache.org/>.
-->
<s1 title="Release Notes">
<ul>
<li><link anchor="status">Status</link></li>
<li><link anchor="build">Build Notes</link></li>
<li><link anchor="contact">Getting in touch</link></li>
</ul>
<s2 title="Status">
<ul>
<li><link anchor="done">Bug fixes</link></li>
<li><link anchor="bugs">Outstanding bugs</link></li>
<li><link anchor="status">Version of Xerces-C to use</link></li>
</ul>
<anchor name="done"/>
&done-c;
<anchor name="bugs"/>
&bugs-c;
<anchor name="status"/>
&status-c;
</s2>
<anchor name="build"/>
<s2 title="Build Notes">
<ul>
<li><link anchor="jar">Rebuilding &xslt4c;</link></li>
<li><link anchor="samples">Rebuilding sample applications</link></li>
</ul>
<anchor name="jar"/>
<s3 title="Rebuilding &xslt4c;">
<p>the Xalan-C dynamic link libraries and command-line executable.</p>
<p>The &xslt4c; build is in xalan.jar. The &xslt4c; source code tree is
in the src directory.
If you want to rebuild xalan.jar, you can do the following:</p>
<ol>
<li>Set up GNU or the equivalent build environment on your
workstation.<br/><br/>
If you are running Windows 95/98/2000/NT, you can use the Cygwin port
of GNU. Be sure to put the
appropriate Cygwin bin directory at the beginning of your system path.
For information about
Cygwin, see <jump
href="http://www.sourceware.cygnus.com/cygwin/";>Cygwin</jump>.<br/><br/></li>
<li>Place <resource-ref idref="xerces-used"/> xerces.jar in the Java
class path.<br/><br/></li>
<li>If you are working in Windows, set MAKE_MODE as follows:<br/><br/>
<code>set MAKE_MODE=UNIX</code><br/><br/></li>
<li>Run the make file in the &xslt4c; root directory:<br/><br/>
<code>make build</code><br/><br/></li>
</ol>
<p>If you want to do the build without the GNU build environment, keep
the following in mind:</p>
<ul>
<li>Set the class path to include the src directory, xerces.jar,
bsf.jar, and bsfengines.jar.</li>
<li>Use a Java compiler (such as the IBM Just-In-Time compiler or the
Sun javac) to compile all the .java files in the src
tree. </li>
<li>Use the Sun jar utility to store the resulting .class files in
xalan.jar</li>
</ul>
</s3><anchor name="samples"/>
<s3 title="Rebuilding a sample application">
<p>If you modify a sample and want to recompile it, you can run the Java
compiler in the directory containing the
example. Be sure xalan.jar and xerces.jar are on the class path. To
recompile (and run!) the class files in the
Servlet subdirectory, the javax.servlet and javax.servlet.http packages
must also be on the class path. Sun
distributes these packages in the JSWDK 1.0.1 servlet.jar file.</p>
<p>After recompiling a sample, you can use the Sun jar utility to place
your new .class files in
xalansamples.jar.</p>
</s3><anchor name="doc"/>
</s2><anchor name="contact"/>
<s2 title="Getting in Touch">
<p>Your feedback is more than welcome. Offers of help are even more so!
Perhaps you would like to contribute to the ongoing development, testing, or
documentation of &xslt4c;?</p>
<p>Please email your comments, questions, suggestions, bug reports, and
offers to help to <human-resource-ref idref="xalandev"/>.</p>
</s2>
</s1>
1.1 xml-xalan/c/xdocs/sources/xalan/resources.xml
Index: resources.xml
===================================================================
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE resources [
<!ENTITY apiResources SYSTEM "apiResources.xml">
<!ELEMENT resources (resource|human-resource)+>
<!ELEMENT resource EMPTY>
<!ATTLIST resource id CDATA #IMPLIED
title CDATA #IMPLIED
location CDATA #IMPLIED>
<!ELEMENT human-resource EMPTY>
<!ATTLIST human-resource id CDATA #IMPLIED
name CDATA #IMPLIED
mailto CDATA #IMPLIED>
]>
<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="ApacheLicense" title="The Apache Software License, Version
1.1" location="http://xml.apache.org/dist/LICENSE.txt"/>
<resource id="Readme" title="Xalan Repository Release Notes"
location="http://www.apache.org/websrc/cvsweb.cgi/xml-xalan/README"/>
<resource id="XSLT" title="W3C Recommendation 16 November 1999 XSL
Transformations (XSLT) Version 1.0" location="http://www.w3.org/TR/xslt"/>
<resource id="XPath" title="XML Path Language (XPath) Version 1.0"
location="http://www.w3.org/TR/xpath"/>
<resource id="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]"/>
<human-resource id="dnbertoni" name="David N. Bertoni"
mailto="[email protected]"/>
<human-resource id="mmidy" name="Myriam Midy" mailto="[EMAIL PROTECTED]"/>
<human-resource id="scurcuru" name="Shane Curcuru" mailto="[EMAIL
PROTECTED]"/>
<human-resource id="dleslie" name="Don Leslie"
mailto="[email protected]"/>
<human-resource id="pdick" name="Paul Dick" mailto="[EMAIL PROTECTED]"/>
<human-resource id="nmendelsohn" name="Noah Mendelsohn" mailto="[EMAIL
PROTECTED]"/>
<human-resource id="sanjiva" name="Sanjiva Weerawarana" mailto="[EMAIL
PROTECTED]"/>
</resources>
1.1 xml-xalan/c/xdocs/sources/xalan/samples.xml
Index: samples.xml
===================================================================
<?xml version="1.0" standalone="no"?>
<!--
* The Apache Software License, Version 1.1
*
*
* Copyright (c) 1999 The Apache Software Foundation. All rights
* reserved.
*
* Redistribution and use in source and binary forms, with or without
* modification, are permitted provided that the following conditions
* are met:
*
* 1. Redistributions of source code must retain the above copyright
* notice, this list of conditions and the following disclaimer.
*
* 2. Redistributions in binary form must reproduce the above copyright
* notice, this list of conditions and the following disclaimer in
* the documentation and/or other materials provided with the
* distribution.
*
* 3. The end-user documentation included with the redistribution,
* if any, must include the following acknowledgment:
* "This product includes software developed by the
* Apache Software Foundation (http://www.apache.org/)."
* Alternately, this acknowledgment may appear in the software itself,
* if and wherever such third-party acknowledgments normally appear.
*
* 4. The names "Xalan" and "Apache Software Foundation" must
* not be used to endorse or promote products derived from this
* software without prior written permission. For written
* permission, please contact [EMAIL PROTECTED]
*
* 5. Products derived from this software may not be called "Apache",
* nor may "Apache" appear in their name, without prior written
* permission of the Apache Software Foundation.
*
* THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED
* WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
* OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
* DISCLAIMED. IN NO EVENT SHALL THE APACHE SOFTWARE FOUNDATION OR
* ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
* SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
* LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
* USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
* ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
* OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
* OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
* SUCH DAMAGE.
* ====================================================================
*
* This software consists of voluntary contributions made by many
* individuals on behalf of the Apache Software Foundation and was
* originally based on software copyright (c) 1999, Lotus
* Development Corporation., http://www.lotus.com. For more
* information on the Apache Software Foundation, please see
* <http://www.apache.org/>.
-->
<!DOCTYPE s1 SYSTEM "sbk:/style/dtd/document.dtd">
<s1 title="Samples">
<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="compilestylesheet">CompileStylesheet</link></li>
<li><link anchor="xpathwrapper">XPathWrapper</link></li>
<li><link anchor="externalfunctions">ExternalFunctions</link></li>
</ul>
<anchor name="getstarted"/>
<s2 title="Samples to help you get started">
<p>Each of the subdirectories in the &xslt4j; samples directory contains
the source files for a
sample application. The executables for all the samples are in the xxx
directory, so to run the samples,
you should place this directory on the system path.</p>
<p>With most of the samples, you can use the following procedure:</p>
<ol>
<li>Go to the samples subdirectory containing the sample (use the DOS
shell if you are running Windows)
<br/><br/></li>
<li>Run the sample from the command line (as indicated
below)<br/><br/></li>
<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>
</s2><anchor name="simpletransform"/>
<s2 title="SimpleTransform">
<p>What it does: The SimpleTransform class uses the foo.xsl stylesheet to
transform foo.xml, and prints the
output to foo.out.</p>
<p>You can run it from the SimpleTransform subdirectory with</p>
<p><code>SimpleTransform</code></p>
<p>See also: <link idref="usagepatterns" anchor="basic">Basic proecedures
for performing XSL
transformations</link>.</p>
</s2><anchor name="usestylesheetparam"/>
<s2 title="UseStylesheetParam">
<p>What it does: Set a stylesheet parameter that the stylesheet uses
during the transformation.</p>
<p>You can run it from the UseStylesheetParam subdirectory with</p>
<p><code>UseStylesheetParam <ref>key expression</ref></code></p>
<p>where <ref>key</ref> is the parameter key (or name) and
<ref>expression</ref> is a string expression enclosed
in single quotes.</p>
<p>The example uses a stylesheet (foo.xsl) with a parameter named param1.
The stylesheet accepts any string
expression. Enclose the string expression in single quotes (so it is
interpreted as an expression); if it
includes more than a single word, enclose the resulting string in double
quotes so the executable interprets it
as a single argument. For example:</p>
<p><code>UseStylesheetParam param1 "'this is a mulit-word string
expression'"</code></p>
<p>See also: <link idref="usagepatterns" anchor="params">Setting
stylesheet params</link>.</p>
</s2><anchor name="compilestylesheet"/>
<s2 title="CompileStylesheet">
<p>What it does: Use a compiled stylesheet to perform a series of
transformations.</p>
<p>You can run it from the CompileStylesheet subdirectory with</p>
<p><code>CompileStylesheet</code></p>
<p>See also: <link idref="usagepatterns" anchor="compiled">Compiling
stylesheets</link>.</p>
</s2><anchor name="xpathwrapper"/>
<s2 title="XPathWrapper">
<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
XPahtWrapperImpl evaluate() method, which executes
the XPath expression from specified context node in the XML document and
returns the nodes (if any) it finds.</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>
<p><code>TestDriver <ref>XMLFile ContextNode
XPathExpression</ref></code></p>
<p>where <ref>XMLFile</ref> is an XML source file, <ref>ContextNode</ref>
is the location path to the context
node, and <ref>XPathExpression</ref> is an XPath expression to apply to
that context node. The XPathWrapper
subdirectory contains an XML file named xml.foo (part of it appears
below).</p>
<source><?xml version="1.0"?>
<doc>
<name first="David" last="Marston"/>
<name first="David" last="Bertoni"/>
...
<name first="Paul" last="Dick"/>
</doc></source>
<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>See also: <link idref="usagepatterns" anchor="xpath">Working with
XPath expressions</link>.</p>
</s2><anchor name="externalfunctions"/>
<s2 title="ExternalFunctions">
<p>What it does: implement, install, and illustratethe usage of three
extension functions. The functions return a
square root, a cube, and a string with the current date and time. The
sample stylesheet (foo.xsl) gets the area
of a cube and units of measurement from an XML document (foo.xml),
computes the length of each side
of a cube and the volume of the cube, and enters the date and time of the
transformation. The output appears in
foo.out.</p>
<p>Run this sample from the ExternalFunctions subdirectory with</p>
<p><code>ExternalFunctions</code></p>
<p>See also: <link idref="extensions">Extension Functions</link>.</p>
</s2>
</s1>
1.1 xml-xalan/c/xdocs/sources/xalan/usagepatterns.xml
Index: usagepatterns.xml
===================================================================
<?xml version="1.0" standalone="no"?>
<!DOCTYPE s1 SYSTEM "sbk:/style/dtd/document.dtd">
<!--
* The Apache Software License, Version 1.1
*
*
* Copyright (c) 1999 The Apache Software Foundation. All rights
* reserved.
*
* Redistribution and use in source and binary forms, with or without
* modification, are permitted provided that the following conditions
* are met:
*
* 1. Redistributions of source code must retain the above copyright
* notice, this list of conditions and the following disclaimer.
*
* 2. Redistributions in binary form must reproduce the above copyright
* notice, this list of conditions and the following disclaimer in
* the documentation and/or other materials provided with the
* distribution.
*
* 3. The end-user documentation included with the redistribution,
* if any, must include the following acknowledgment:
* "This product includes software developed by the
* Apache Software Foundation (http://www.apache.org/)."
* Alternately, this acknowledgment may appear in the software itself,
* if and wherever such third-party acknowledgments normally appear.
*
* 4. The names "Xalan" and "Apache Software Foundation" must
* not be used to endorse or promote products derived from this
* software without prior written permission. For written
* permission, please contact [EMAIL PROTECTED]
*
* 5. Products derived from this software may not be called "Apache",
* nor may "Apache" appear in their name, without prior written
* permission of the Apache Software Foundation.
*
* THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED
* WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
* OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
* DISCLAIMED. IN NO EVENT SHALL THE APACHE SOFTWARE FOUNDATION OR
* ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
* SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
* LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
* USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
* ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
* OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
* OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
* SUCH DAMAGE.
* ====================================================================
*
* This software consists of voluntary contributions made by many
* individuals on behalf of the Apache Software Foundation and was
* originally based on software copyright (c) 1999, Lotus
* Development Corporation., http://www.lotus.com. For more
* information on the Apache Software Foundation, please see
* <http://www.apache.org/>.
-->
<s1 title="Basic usage patterns">
<ul>
<li><link anchor="intro">Introduction</link></li>
<li><link anchor="basic">Basic procedure for performing XSL
transformations</link></li>
<li><link anchor="dom">Working with DOM input and output</link></li>
<li><link anchor="params">Setting stylesheet parameters</link></li>
<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="debugging">Debugger interface</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>. 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.</p>
<p>&xslt4c; uses an implementation of the <jump
href="apidocs/class_xmlparserliaison.html"/> to interact with the Xerces XML
parser 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>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">
<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>
</s3>
<s3 title="2. Initialize Xalan and Xerces">
<p>Use the static initializers to initialize the Xalan-C and Xerces-C
platforms. You only need to do this once per session.</p>
<source>XMLPlatformUtils::Initialize();
XSLTEngineImpl::Initialize();</source>
</s3><anchor name="step3"/>
<s3 title="3. Set up an XSLT processor with its support objects">
<p>The XSLT processor interacts with several support objects that you must
set up before you can perform transformations.</p>
<source>// Create the support objects.
DOMSupportDefault theDOMSupport;
XercesParserLiaison theParserLiaison(theDOMSupport);
XPathSupportDefault theXPathSupport(theDOMSupport);
XSLTProcessorEnvSupportDefault theXSLTProcessorEnvSupport;
XObjectFactoryDefault theXObjectFactory(theXSLTProcessorEnvSupport,
theXPathSupport);
XPathFactoryDefault theXPathFactory;
// Create the processor.
XSLTEngineImpl theProcessor(
theParserLiaison,
theXPathSupport,
theXSLTProcessorEnvSupport,
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>
</s3>
<s3 title="4. Create context objects for the stylesheet">
<p>Use the processor and support objects to set up a stylesheet construction
context object and execution context object.</p>
<source>
StylesheetConstructionContextDefault theConstructionContext(
theProcessor,
theXSLTProcessorEnvSupport,
theXObjectFactory,
theXPathFactory);
StylesheetExecutionContextDefault theExecutionContext(
theProcessor,
theXSLTProcessorEnvSupport,
theXPathSupport,
theXObjectFactory);</source>
</s3>
<s3 title="5. Set up input and output objects for a transformation">
<p>You must set up XSLTInputSource objects for the XML document and XSL
stylesheet, and an XSLTResultTarget object to contain the transformation
output.</p>
<p>Each of these objects may take the form of a file or URL, a stream, or a
DOM tree. In the following fragment, the input and output are files:</p>
<source>// Use XalanDOMString to create a Unicode file name.
// The files are in the same directory as the application executable.
const XalanDOMString theXMLFileName("foo.xml");
const XalanDOMString theXSLFileName("foo.xsl");
// Create XSLTInputSource objects.
XSLTInputSource theInputSource(c_wstr(theXMLFileName));
XSLTInputSource theStylesheetSource(c_wstr(theXSLFileName));
// For the output, create an XSLTResultTarget object.
TextFileOutputStream theOutputStream("foo.out");
XercesDOMPrintWriter theResultWriter(theOutputStream);
XSLTResultTarget theResultTarget(&theResultWriter);
</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 title="6. Perform the transformation">
<p>Use the XSLTEngineImpl process() method to perform the transformation.</p>
<source>
theProcessor.process(
theInputSource,
&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 xxxx.</p>
<p>For a sample application that performs a transformation, see <link
idref="samples" anchor="simpletransform">SimpleTransform</link>.</p>
</s3>
</s2><anchor name="dom"/>
<s2 title="Working with DOM input and output">
<p>You can set up an XSLTResultTarget to produce a DOM when you perform a
transformation. You can also use a DOM as input for a transformation, either
the DOM output of another transformation, or a DOM produced by the Xerces
DOMParser.</p>
<p>The following code fragments illustrate the procedures for working with
DOM input and output:</p>
<source>
// Use the Xerces DOM parser to create a DOM_Document.
#include <parsers/DOMParser.hpp>
#include <dom/DOM_Node.hpp>
DOMParser theParser;
theParser.parse("foo.xml");
const DOM_Document theDOM = theParser.getDocument();
// Set up a XercesParserLiaison and use it to wrap the DOM_Document
// in a XalanDocument.
DOMSupportDefault theDOMSupport;
XercesParserLiaison theParserLiaison(theDOMSupport);
XalanDocument* theDoc = theParserLiaison.createDocument(theDOM);
// Use the XalanDocument to create an XSLTInputSource object, which
// you can then use in a transformation.
XSLTInputSource theInputSource(theDoc);
...
// If you want to produce DOM output, create an empty XalanDocument
// to contain the transformation output.
XalanDocument* docOut = theParserLiaison.createDocument();
XSLTResultTarget theDOMResultTarget(docOut);
...
// After you perform the transformation, the XalanDocument contains
// the output.
// You can also convert the XalanDocument to a Xerces DOM_Document.
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>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>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>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
DOMSupportDefault theDOMSupport;
XercesParserLiaison theParserLiaison(theDOMSupport);
XPathSupportDefault theXPathSupport(theDOMSupport);
XSLTProcessorEnvSupportDefault theXSLTProcessorEnvSupport;
XObjectFactoryDefault theXObjectFactory(theXSLTProcessorEnvSupport,
theXPathSupport);
XPathFactoryDefault theXPathFactory;
// Create the processor, connect it to the environment support
// object, and use the parser liaison as the formatter.
XSLTEngineImpl theProcessor(
theParserLiaison,
theXPathSupport,
theXSLTProcessorEnvSupport,
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
// (separate from the XSLT processor XObject and XPath objects).
XObjectFactoryDefault theStylesheetXObjectFactory(
theXSLTProcessorEnvSupport,
theXPathSupport);
XPathFactoryDefault theStylesheetXPathFactory;
// Use these factory support objects to create a stylesheet
// construction context.
StylesheetConstructionContextDefault theConstructionContext(
theProcessor,
theXSLTProcessorEnvSupport,
theStylesheetXObjectFactory,
theStylesheetXPathFactory);
// The execution context uses the same factory support objects as
// the processor.
StylesheetExecutionContextDefault theExecutionContext(
theProcessor,
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 XXLTEngineImpl
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>
<source>
// Compile the stylesheet.
StylesheetRoot* const theStylesheetRoot =
theProcessor.processStylesheet(
theStylesheetSource,
theConstructionContext);
theProcessor.setStylesheet(theStylesheetRoot) // Good form!
// Set up an XSLTInputSource object (theInputSource)
// and an XSLTResultTarget object (theResultTarget).
...
// Do the tranformation...
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();
// 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>The XPathAPI class, in the samples/ApplyXPath subdirectory, contains
several convenience methods that you can use to return single DOM Nodes,
NodeLists, and XObjects. In the future, we plan to incorporate user feedback
and move these methods into the core API.</p>
<p>If you are interested in the API for executing XPath expressions, we
suggest you take a look at the methods in XPathAPI,
and send us feedback on what best meets your needs.</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="debugging"/>
<s2 title="Debugger Interface">
<p><em>Placeholder</em>. What do we have to say about TraceListener, the
XSLTEngineImplProcessor addTraceListener() method, and TracerEvents? Must also
figure out what to include and what to cut out of the command line document.</p>
</s2>
</s1>
