dleslie 01/08/15 10:32:41
Modified: c/xdocs/sources/xalan extensions.xml readme.xml
usagepatterns.xml
Log:
Updates for 1.2 per Dave Bertoni's review.
Revision Changes Path
1.15 +3 -3 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.14
retrieving revision 1.15
diff -u -r1.14 -r1.15
--- extensions.xml 2001/08/10 19:16:43 1.14
+++ extensions.xml 2001/08/15 17:32:40 1.15
@@ -158,10 +158,10 @@
}</source>
</s2><anchor name="install"/>
<s2 title="Installing an extension function">
-<p><jump href="apdidocs/class_xalantransformer.html">XalanTransformer</jump>
provides methods for installing and unistalling external functions:</p>
+<p><jump href="apidocs/class_xalantransformer.html">XalanTransformer</jump>
provides methods for installing and unistalling external functions:</p>
<ul>
<li>installExternalFunction() makes the function available in the current
instance of XalanTransformer. Use uninstallExternalFunction() to remove the
function.<br/><br/></li>
-<li>installExternalFunctionGlobal() makes the function available globally.
Use uninstallExternalFunctionGlobal() to remove the function. The global
functions are static.</li>
+<li>installExternalFunctionGlobal() makes the function available globally.
Use uninstallExternalFunctionGlobal() to remove the function. The global
functions are static; they are not thread-safe!</li>
</ul>
<p>These methods include arguments for the namespace, the function name, and
the function implementation.</p>
<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>
@@ -227,7 +227,7 @@
<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 <jump
href="apidocs/class_xnodeset.html">XNodeSet</jump>.</p>
+<p>If you pass a node-set to an extension function, be sure to set up the
function to process a node-set.</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>
1.29 +10 -7 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.28
retrieving revision 1.29
diff -u -r1.28 -r1.29
--- readme.xml 2001/08/10 19:16:43 1.28
+++ readme.xml 2001/08/15 17:32:40 1.29
@@ -81,9 +81,12 @@
<p>Major updates since version 1.1 include:</p>
<ul>
<li><link idref="extensionslib">Introduction of a library of extension
functions</link></li>
- <li></li>
- <li></li>
- <li></li>
+ <li>Support for pre-parsed source documents and pre-compiled
stylesheets in
+ <jump
href="apidocs/class_xalantransformer.html">XalanTransformer</jump> and the C
API.</li>
+ <li>Support for stylesheet params in <jump
href="apidocs/class_xalantransformer.html">XalanTransformer</jump>
+ and the C API</li>
+ <li>Support for extension functions in <jump
href="apidocs/class_xalantransformer.html">XalanTransformer</jump></li>
+ <li>Performance enhancements</li>
</ul>
</s3>
<anchor name="bugs"/>
@@ -173,7 +176,7 @@
<code>chmod +x
conf*</code><br/><br/></li>
<li>Run the runConfigure utility with at least the platform flag
(Linux) or the platform, C compilier, and C++ compiler flags (AIX) as indicated
below.<br/><br/>
<ref>Linux:</ref> <code>runConfigure -p linux</code><br/>
- <ref>AIX:</ref> <code>runConfigure -p aix -c
xlc_r -x xlC_r</code><br/><br/>
+ <ref>AIX:</ref> <code>runConfigure -p aix -c
xlc -x xlC</code><br/><br/>
<ref>HP-UX 11:</ref> <code>runConfigure -p hp-11 -c cc -x
aCC</code><br/><br/>
<ref>Solaris:</ref> <code>runConfigure -p solaris -c cc -x
CC</code><br/><br/>
To see the other runConfigure flags you may include, use the help
flag:<br/><br/>
@@ -185,13 +188,13 @@
or<br/>
<code>make
<ref>targ</ref></code><br/><br/>
where <ref>targ</ref> is ommitted or is <code>all</code> (rebuild
all), <code>lib</code> (the XSLT libary), or
- <code>TestXSLT</code> (the TestSXSLT executable). ICUBridge is
included in the build of TestXSLT if XALAN_USE_ICU is
+ <code>testXSLT</code> (the testSXSLT executable). ICUBridge is
included in the build of TestXSLT if XALAN_USE_ICU is
defined.<br/><br/></li>
</ol>
<note>The command you use for setting environment variables depends on
the shell you are
using.<br/>
- For Bourne Shell, K Shell, or Bash use <em>export</em> ENVAR "val"<br/>
- For C Shell, use <em>setenv</em> ENVAR="val"<br/>
+ For Bourne Shell, K Shell, or Bash use <em>export</em> ENVAR="val"<br/>
+ For C Shell, use <em>setenv</em> ENVAR "val"<br/>
where ENVAR is the environment variable name and val is the environment
variable
setting. You can check the setting of an environment variable with
<em>echo</em> $ENVAR</note>
</s3><anchor name="samples"/>
1.29 +22 -13 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.28
retrieving revision 1.29
diff -u -r1.28 -r1.29
--- usagepatterns.xml 2001/08/09 20:10:36 1.28
+++ usagepatterns.xml 2001/08/15 17:32:40 1.29
@@ -74,15 +74,15 @@
</ul><anchor name="intro"/>
<s2 title="Introduction">
-<p>To perform a transformation, use one of the <jump
href="apdidocs/class_xalantransformer.html">XalanTransformer</jump> transform()
methods. The transformation requires an XML source document and an XSL
stylesheet. Both of these objects may be represented by instances of <jump
href="apidocs/class_xsltinputsource.html">XSLTInputSource</jump>. You can
construct an XSLTInputSource with a string (the system ID for a file or URI),
an input stream, or a DOM.</p>
+<p>To perform a transformation, use one of the <jump
href="apidocs/class_xalantransformer.html">XalanTransformer</jump> transform()
methods. The transformation requires an XML source document and an XSL
stylesheet. Both of these objects may be represented by instances of <jump
href="apidocs/class_xsltinputsource.html">XSLTInputSource</jump>. You can
construct an XSLTInputSource with a string (the system ID for a file or URI),
an input stream, or a DOM.</p>
<p>If you are using an XSL stylesheet to perform a series of
transformations, you can improve performance by calling transform() with a
compiled stylesheet, an instance of <jump
href="apidocs/class_xalancompiledstylesheet.html">XalanCompiledStylesheet</jump>.
If you are transforming an XML source more than once, you should call
transform() with a parsed XML source, an instance of <jump
href="apidocs/class_xalanparsedsource">XalanParsedSource</jump>. See <link
anchor="compiled">Performing a series of transformations</link>.</p>
<p>If you XML source document contains a stylesheet Processing Instruction
(PI), you do not need to include a stylesheet object when you call
transform().</p>
-<p>The transformation output is represented by an <jump
href="apdidocs/class_xsltresulttarget.html">XSLTResultTarget</jump>, which you
can set up to refer to an output stream, the system ID for a file or URI, or a
DOM.</p>
+<p>The transformation output is represented by an <jump
href="apidocs/class_xsltresulttarget.html">XSLTResultTarget</jump>, which you
can set up to refer to an output stream, the system ID for a file or URI, or a
DOM.</p>
<p>For detailed API documentation, see <jump
href="apidocs/index.html">&xslt4c; API</jump>. For an overview of the
command-line utility, see <link idref="commandline">Command-Line
Utility</link>.</p>
</s2><anchor name="cpp"/>
<s2 title="Basic usage patten with the XalanTransformer C++ API">
-<p>Using <jump
href="apdidocs/class_xalantransformer.html">XalanTransformer</jump> and the C++
API, you can perform one or more transformations as described in the following
steps.</p>
+<p>Using <jump
href="apidocs/class_xalantransformer.html">XalanTransformer</jump> and the C++
API, you can perform one or more transformations as described in the following
steps.</p>
<note>For a working sample that illustrates these steps, see the <link
idref="samples" anchor="xalantransform">XalanTransform</link> sample.</note>
<s3 title="1. Include the required header files.">
<p>Always start with Include/PlatformDefinitions.hpp, the &xslt4c; base
header file. Also include util/PlatformUtils.hpp,
XalanTransformer/XalanTransformer.hpp, and any other header files your
particular application requires.</p>
@@ -100,7 +100,7 @@
<source>XalanTransformer theXalanTransformer;</source>
</s3>
<s3 title="4. Perform each transformation">
- <p>You can explicitly instantiate <jump
href="apidocs/class_xsltinputsource.html">XSLTInputSource</jump> objects for
the XML source document and XSL stylesheet, and an <jump
href="apidocs/class_xsltresulttarget.html">XSLTResultTarget</jump> object for
the output, and then call <jump
href="apdidocs/class_xalantransformer.html">XalanTransformer</jump> transform()
with those objects as parameters. For example:</p>
+ <p>You can explicitly instantiate <jump
href="apidocs/class_xsltinputsource.html">XSLTInputSource</jump> objects for
the XML source document and XSL stylesheet, and an <jump
href="apidocs/class_xsltresulttarget.html">XSLTResultTarget</jump> object for
the output, and then call <jump
href="apidocs/class_xalantransformer.html">XalanTransformer</jump> transform()
with those objects as parameters. For example:</p>
<source>XSLTInputSource xmlIn("foo.xml");
XSLTInputSource xslIn("foo.xsl");
XSLTResultTarget xmlOut("foo-out.xml");
@@ -145,7 +145,7 @@
</s2><anchor name="params"/>
<s2 title="Setting stylesheet parameters">
<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 the <jump
href="apdidocs/class_xalantransformer.html">XalanTransformer</jump>
setStylesheetParam() method. The setStytlesheetParam() method takes two
arguments: the parameter name and the expression. For example:</p>
+<p>To set a stylesheet parameter, use the <jump
href="apidocs/class_xalantransformer.html">XalanTransformer</jump>
setStylesheetParam() method. The setStytlesheetParam() method takes two
arguments: the parameter name and the expression. For example:</p>
<source>const XalanDOMString& key="param1";
const XalanDOMString& expression="'Hello World'";
theXalanTransformer.setStylesheetParam(key, expression);
@@ -159,7 +159,7 @@
<p>The <link idref="samples"
anchor="usestylesheetparam">UseStylesheetParam</link> sample application also
uses a command-line parameter.</p>
</s2><anchor name="incremental"/>
<s2 title="Processing output incrementally">
-<p><jump href="apdidocs/class_xalantransformer.html">XalanTransformer</jump>
provides a transform() method that sends the output in blocks to a callback
function, which enables you to begin processing the output while the
transformation is still in process:</p>
+<p><jump href="apidocs/class_xalantransformer.html">XalanTransformer</jump>
provides a transform() method that sends the output in blocks to a callback
function, which enables you to begin processing the output while the
transformation is still in process:</p>
<source>int
transform(const XSLTInputSource& xmlIn,
const XSLTInputSource& xslIn,
@@ -169,8 +169,8 @@
<p>For an example, see <link idref="samples"
anchor="xalantransformercallback">XalanTransformerCallback</link>.</p>
</s2><anchor name="compiled"/>
<s2 title="Performing a series of transformations">
-<p>Before Xalan performs a standard transformation, it must parse the XML
document and compile the XSL stylesheet into binary representations. If you
plan to use the same XML document or stylesheet in a series of transformations,
you can improve performance by parsing the XML document or compiling the
styleheet once and using the binary representation when you call
transform().</p>
-<p><jump href="apdidocs/class_xalantransformer.html">XalanTransformer</jump>
includes methods for creating compiled stylesheets and parsed XML documents:
the compileStylesheet() method returns a pointer to a <jump
href="apdidocs/class_xalancompiledstylesheet.html">XalanCompiledStylesheet</jump>;
the parseSource() method returns a pointer to a <jump
href="apdidocs/class_xalanparsedsource.html">XalanParsedSource</jump>.</p>
+<p>Before Xalan performs a standard transformation, it must parse the XML
document and compile the XSL stylesheet into binary representations. If you
plan to use the same XML document or stylesheet in a series of transformations,
you can improve performance by parsing the XML document or compiling the
stylesheet once and using the binary representation when you call
transform().</p>
+<p><jump href="apidocs/class_xalantransformer.html">XalanTransformer</jump>
includes methods for creating compiled stylesheets and parsed XML documents:
the compileStylesheet() method returns a pointer to a <jump
href="apidocs/class_xalancompiledstylesheet.html">XalanCompiledStylesheet</jump>;
the parseSource() method returns a pointer to a <jump
href="apidocs/class_xalanparsedsource.html">XalanParsedSource</jump>.</p>
<note>In the case of failure, both methods return 0.</note>
<p>Example using a XalanCompiledStylesheet to perform multiple
transformations:</p>
<source>XalanCompiledStylesheet* compiledStylesheet = 0;
@@ -199,12 +199,15 @@
#include <dom/DOM_Node.hpp>
DOMParser theParser;
+// You MUST instruct the Xerces DOMParser NOT to create a DOM_XMLDecNode
+// in the DOM to represent the XML declaration. See "Limitations" below.
+DOMParser::setToCreateXMLDeclTypeNode(false);
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;
+XercesDOMSupport theDOMSupport;
XercesParserLiaison theParserLiaison(theDOMSupport);
XalanDocument* theDoc = theParserLiaison.createDocument(theDOM);
@@ -221,6 +224,12 @@
// the output.
// You can also convert the XalanDocument to a Xerces DOM_Document.
DOM_Document domOut = theParserLiaison.mapXercesDocument(docOut)</source>
+<s3 title="Limitations">
+<p>Performance is much better when &xslt4c; uses native source tree handling
rather than interacting with the Xerces DOMParser.</p>
+<p>By default, the Xerces DOMParser creates a DOM_XMLDecNode in the DOM tree
to represent the XML declaration. The
+Xalan bridge for the Xerces DOM does not support this non-standard node
type. Accordingly, you must call DOMParser::setToCreateXMLDeclTypeNode(false)
<em>before</em> you parse the XML file. If not, the behavior is undefined, and
+your application may crash.</p>
+</s3>
</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.
@@ -239,7 +248,7 @@
<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>
+<p>The <link idref="commandline">command-line utility (testXSLT)</link> and
TraceListen both use TraceListenerDefault to write events to the screen.</p>
</s2><anchor name="icu"/>
<s2 title="Using the ICU">
<p>You can use the <resource-ref idref="icu"/> to extend support for
encoding, number
@@ -349,10 +358,10 @@
<p>The <jump href="apidocs/XalanCAPI.h.html">Xalan C API</jump> supports
approximately the same set of options as the C++ API. In particular, you can</p>
<ul>
<li>Use stylesheet processing instructions (PI) to supply the stylesheet.
Simply supply an empty string ("") for the XSL file name.<br/><br/></li>
-<li>Set stylesheet parameters. Use the SetStylesheetParam()
method.<br/><br/></li>
-<li>Compile stylesheets. Use the CompileStylesheet() method to compile a
stylesheet, and the TransformToFileCSS() or TransformToDataCSS() method to use
the compiled stylesheet in a transformation.<br/><br/></li>
+<li>Set stylesheet parameters. Use the SetStylesheetParam()
function.<br/><br/></li>
+<li>Compile stylesheets. Use the CompileStylesheet() method to compile a
stylesheet, and the TransformToFileCSS() or TransformToDataCSS() function to
use the compiled stylesheet in a transformation.<br/><br/></li>
<li>Parse XML sources. Use the XalanParseSource() or
XalanParseSouceUseXalan() method.<br/><br/></li>
-<li>Place the transformation output in a character array. Use the
TransformToData() or TransformToDataCSS() method. After you perform the
transformation, use the XalanFreeData() method to free memory allocated for the
output data.<br/><br/></li>
+<li>Place the transformation output in a character array. Use the
TransformToData() or TransformToDataCSS() function. After you perform the
transformation, use the XalanFreeData() function to free memory allocated for
the output data.<br/><br/></li>
<li>Send the output to a callback function to process blocks of output data
as they arrive.</li>
</ul>
<p>For a sample that sends output in blocks to a callback function, see
<link idref="samples" anchor="apachemodulexslt">ApacheModuleXSLT</link>.</p>
---------------------------------------------------------------------
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
