[prev in list] [next in list] [prev in thread] [next in thread]
List: xalan-cvs
Subject: [xalan-c] branch gh-pages updated: Update content to latest in XALANC-792
From: rleigh () apache ! org
Date: 2020-05-12 12:58:32
Message-ID: 158928831227.32451.8297642877982054514 () gitbox ! apache ! org
[Download RAW message or body]
This is an automated email from the ASF dual-hosted git repository.
rleigh pushed a commit to branch gh-pages
in repository https://gitbox.apache.org/repos/asf/xalan-c.git
The following commit(s) were added to refs/heads/gh-pages by this push:
new bb5e6fe Update content to latest in XALANC-792
bb5e6fe is described below
commit bb5e6fe2f59a243458545d35e1d0982d702e22b0
Author: Roger Leigh <rleigh@codelibre.net>
AuthorDate: Tue May 12 13:58:18 2020 +0100
Update content to latest in XALANC-792
---
commandline.md | 36 +++---
download.md | 4 +-
extensions.md | 72 +++++------
extensionslib.md | 42 ++++---
faq.md | 214 +++++++++++++++++---------------
images/Xalan-Trademark.txt | 2 +-
index.md | 2 +-
overview.md | 37 +++---
programming.md | 6 +-
releases.md | 2 +
samples.md | 216 +++++++++++++++++----------------
secureweb.md | 26 ++--
usagepatterns.md | 295 +++++++++++++++++++++++++++------------------
13 files changed, 524 insertions(+), 430 deletions(-)
diff --git a/commandline.md b/commandline.md
index cf7650a..88f53d9 100644
--- a/commandline.md
+++ b/commandline.md
@@ -10,34 +10,34 @@ To perform a transformation from the command line or a script, do \
the following:
1. [Download](download.md) and [build](build.md) Xalan-C++, or
[install](install.md) Xalan-C++ from a third-party distributor.
-2. Set the path/library path to include the Xalan executable
- and the Xalan and Xerces libraries.
+2. Set the path and/or library path to include the Xalan executable
+ and the Xalan-C++ and Xerces-C++ libraries, respectively.
3. Call the Xalan executable with the appropriate flags and arguments
(described below).
## Using the `Xalan` executable
-Call the `Xalan` executable as follows:
+Call the `Xalan` executable as follows:
```sh
Xalan [options] xmlSource xslStylesheet
```
-where `xmlSource` is the XML source document, `xslStylesheet` is the stylesheet to \
apply, and
-`[options]` are any (or none) of the following:
-
-| Option | Description \
|
-|--------------|------------------------------------------------------------------------|
-| -a | Use stylesheet processing instruction, not the stylesheet argument. \
|
-| -e encoding | Force the specified encoding for the output. \
|
-| -i integer | Indent the specified amount. \
|
-| -m | Omit the META tag in HTML output. \
|
-| -o filename | Write transformation result to this file (rather than to the \
console). |
-| -p name expr | Set a stylesheet parameter with this expression. \
|
-| -t name expr | Display timing information. \
|
-| -u name expr | Disable escaping of URLs in HTML output. \
|
-| -v | Validate the XML source document. \
|
-| - | A dash as the 'source' argument reads from stdin.<br/>A dash as the \
'stylesheet' argument reads from stdin.<br/>(`-` cannot be used for both arguments.) \
| +where *xmlSource* is the XML source document, *xslStylesheet* is the
+stylesheet to apply, and *options* are any (or none) of the following:
+
+| Option | Description \
| +|----------------|------------------------------------------------------------------------|
+| *-a* | Use stylesheet processing instruction, not the stylesheet \
argument. | +| *-e encoding* | Force the specified encoding for the output. \
| +| *-i integer* | Indent the specified amount. \
| +| *-m* | Omit the META tag in HTML output. \
| +| *-o filename* | Write transformation result to this file (rather than to the \
console). | +| *-p name expr* | Set a stylesheet parameter with this expression. \
| +| *-t name expr* | Display timing information. \
| +| *-u name expr* | Disable escaping of URLs in HTML output. \
| +| *-v* | Validate the XML source document. \
| +| *-* | A dash as the *xmlSource* argument reads from stdin.<br>A dash \
as the *xmlStylesheet* argument reads from stdin.<br/>("-" cannot be used for both \
arguments.) |
To display a list of the options call the Xalan executable as follows:
diff --git a/download.md b/download.md
index 3e6a582..c297909 100644
--- a/download.md
+++ b/download.md
@@ -28,7 +28,7 @@ Note: You must [verify the \
integrity](#verify-the-integrity-of-the-files) of the downloaded files using \
signatures downloaded from the Apache master distribution directory.
-Note: To access previous releases of Xalan-C++, visit the
+Note: To access previous releases of Xalan-C++, visit the
[Apache Xalan-C++ archives](http://archive.apache.org/dist/xml/xalan-c/).
To access previous releases of Xerces-C++, visit the
[Apache Xerces-C++ archives](http://archive.apache.org/dist/xerces/c/)
@@ -71,4 +71,4 @@ signatures using:
% gpg --verify <archive-name>.tar.gz.asc
```
-Alternatively, you can verify the MD5 signature on the files.
+Alternatively, you can verify the MD5 signature on the files.
diff --git a/extensions.md b/extensions.md
index cec5282..c540304 100644
--- a/extensions.md
+++ b/extensions.md
@@ -12,12 +12,12 @@ 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`.
+`boolean` or `number`.
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.
+expressions, literals (for `string`, `boolean`, and `number`), the
+values returned by other functions, and XSL variables or parameters set
+to any of the preceding.
For an example that implements, installs, and uses three extension
functions, see the [External Functions](samples.md#externalfunctions)
@@ -36,7 +36,7 @@ follows:
in the example below -- to create an `XObject` corresponding to the
XSLT data type the function returns.
2. Implement a `clone()` method to enable Xalan to create and maintain
- a copy of the extension function.
+ a copy of the extension function.
3. (Optional) As Xalan does for the XPath functions, you may want to
prevent the compiler from generating an assignment or equality
operator for this function.
@@ -81,11 +81,11 @@ public:
{
if (args.size() != 1)
{
- executionContext.error("The square-root() function takes one argument!",
+ executionContext.error("The square-root() function takes one argument!",
context);
}
assert(args[0] != 0);
- // Use the XObjectFactory createNumber() method to create an XObject
+ // Use the XObjectFactory createNumber() method to create an XObject
// corresponding to the XSLT number data type.
return executionContext.getXObjectFactory().createNumber(
sqrt(args[0]->num()));
@@ -114,18 +114,21 @@ private:
## Installing an extension function
-`XalanTransformer` provides methods for installing and uninstalling
-external functions:
-
-* `installExternalFunction()` makes the function available in the
- current instance of `XalanTransformer`. Use
- `uninstallExternalFunction()` to remove the function.
-* `installExternalFunctionGlobal()` makes the function available
- globally. `Use uninstallExternalFunctionGlobal()` to remove the
- function. The global install and uninstall operations are not
- thread-safe. However, all global functions should be thread-safe,
- because multiple threads could call a particular function instance at
- the same time.
+[`XalanTransformer`](https://apache.github.io/xalan-c/api/classxalanc_1_1XalanTransformer.html)
+provides methods for installing and uninstalling external functions:
+
+* [`installExternalFunction()`](https://apache.github.io/xalan-c/api/classxalanc_1_1XalanTransformer.html#a7d932d74897e12629afd62bba2735456)
+ makes the function available in the current instance of `XalanTransformer`. Use
+ [`uninstallExternalFunction()`](https://apache.github.io/xalan-c/api/classxalanc_1_1XalanTransformer.html#a8dbb4538357ab2909925dd16a449dbac)
+ to remove the function.
+* [`installExternalFunctionGlobal()`](https://apache.github.io/xalan-c/api/classxalanc_1_1XalanTransformer.html#a7d4f49b03739feaa01cdbffd5668e736)
+ makes the function available globally.
+ Use
+ [`uninstallExternalFunctionGlobal()`](https://apache.github.io/xalan-c/api/classxalanc_1_1XalanTransformer.html#ab5c8f39bcf0bf84b6bbe0607bbe4afde)
+ to remove the function. The global install and uninstall operations
+ are not thread-safe. However, all global functions should be
+ thread-safe, because multiple threads could call a particular
+ function instance at the same time.
These methods include arguments for the namespace, the function name,
and the function implementation.
@@ -151,7 +154,7 @@ is installed in a different namespace.
// The namespace…
const XalanDOMString
theNamespace("http://MyExternalFunction.mycompany.org");
-
+
theXalanTransformer.installExternalFunction(theNamespace,
XalanDOMString("square-root"),
FunctionSquareRoot());
@@ -172,7 +175,7 @@ To use the extension function in a stylesheet, you must do the \
following: namespace specified when the function is installed.
<br>
By default, namespace declarations are included in the
- transformation output. To exclude namespaces from the output,
+ transformation output. To exclude namespaces from the output,
use
<br>
`exclude-result-prefixes="prefix-1 prefix-2 …"`
@@ -187,9 +190,9 @@ To use the extension function in a stylesheet, you must do the \
following: Qualified Name (QName) made up of the prefix you declared in step 1
and the function name you specified when you installed the function.
<br>
- You can use XPath expressions, literals (for string, boolean, and
- number), and values returned by other functions to specify function
- arguments.
+ You can use XPath expressions, literals (for `string`, `boolean`,
+ and `number`), and values returned by other functions to specify
+ function arguments.
Suppose, for example, you are working with XML documents containing
area elements like `<area value="397"/>`, where the value attribute
@@ -201,17 +204,17 @@ namespace declaration to the result tree, and uses the \
square-root function to return the square root of `//area/@value:`
```xml
-<?xml version="1.0"?>
-<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
+<?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
+ The length of each side is
<xsl:value-of select="external:square-root(@value)"/> units
</out>
</xsl:template>
@@ -223,15 +226,15 @@ output:
```xml
<out>
- The area of the square is
+ The area of the square is
397 square units.
- The length of each side is
+ The length of each side is
19.9249 units.
</out>
```
For a slightly more complex variation on this example, see the
-[External Functions](samples.md#externalfunctions) sample
+[External Functions](samples.md#externalfunctions) sample
### Passing Nodes to a function
@@ -277,6 +280,7 @@ syntactically possible:
```
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`.
+document, so keep in mind that
+[`getNextSibling()`](https://apache.github.io/xalan-c/api/classxalanc_1_1XalanNode.html#a9b4a7333371ffee9a6fd851203f4c98a),
+for example, gets you the next sibling in the document, which may not
+be the next `Node` in the `node-set`.
diff --git a/extensionslib.md b/extensionslib.md
index 0e86e2b..5e2c719 100644
--- a/extensionslib.md
+++ b/extensionslib.md
@@ -15,17 +15,17 @@ Development Mailing List.
Xalan-C++ supports the [EXSLT](http://exslt.org/) initiative to provide
a set of standard extension functions to XSLT users. Xalan-C++ includes
beta implementations for functions in four of the EXSLT namespaces
-(some are calls to extension already in the Xalan namespace).
+(some are calls to extension already in the Xalan namespace).
The source files for the implementations are in the XalanEXSLT
subdirectory of the source tree. See
-* XalanEXSLTCommonImpl
-* XalanEXSLTMathImpl
-* XalanEXSLTSetImpl
-* XalanEXSLTStringImpl
-* XalanEXSLTDynamicImpl
-* XalanEXSLTDateTimeImpl
+* [*XalanEXSLTCommonImpl.hpp*](https://github.com/apache/xalan-c/blob/master/src/xalanc/XalanEXSLT/XalanEXSLTCommonImpl.hpp)
+* [*XalanEXSLTMathImpl.hpp*](https://github.com/apache/xalan-c/blob/master/src/xalanc/XalanEXSLT/XalanEXSLTMathImpl.hpp)
+* [*XalanEXSLTSetImpl.hpp*](https://github.com/apache/xalan-c/blob/master/src/xalanc/XalanEXSLT/XalanEXSLTSetImpl.hpp)
+* [*XalanEXSLTStringImpl.hpp*](https://github.com/apache/xalan-c/blob/master/src/xalanc/XalanEXSLT/XalanEXSLTStringImpl.hpp)
+* [*XalanEXSLTDynamicImpl.hpp*](https://github.com/apache/xalan-c/blob/master/src/xalanc/XalanEXSLT/XalanEXSLTDynamicImpl.hpp)
+* [*XalanEXSLTDateTimeImpl.hpp*](https://github.com/apache/xalan-c/blob/master/src/xalanc/XalanEXSLT/XalanEXSLTDateTimeImpl.hpp)
For the function specifications, see:
@@ -57,7 +57,7 @@ For an example that uses this namespace, see
## nodeset
-Implemented in `FunctionNodeSet`, `nodeset (result-tree-fragment)`
+Implemented in `FunctionNodeSet`, `nodeset (result-tree-fragment)`
casts a result tree fragment into a `node-set`.
Note: When you bind a variable to a template, rather than to the value
@@ -75,7 +75,7 @@ namespace to provide access to the `nodeset()` method in
```xml
<?xml version="1.0"?>
-<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
+<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
version="1.0"
xmlns:xalan="http://xml.apache.org/xalan"
exclude-result-prefixes="xalan">
@@ -91,12 +91,12 @@ namespace to provide access to the `nodeset()` method in
<elem2a>ELEMENT2A</elem2a>
</elem2>
</docelem>
- </xsl:variable>
+ </xsl:variable>
<xsl:for-each select="xalan:nodeset($rtf)/docelem//*">
<xsl:value-of select="name(.)"/><xsl:text>,</xsl:text>
</xsl:for-each>
</out>
-</xsl:template>
+</xsl:template>
</xsl:stylesheet>
```
@@ -108,32 +108,34 @@ comma-delimited list of the element names in the `node-set`
```
Note: For illustration purposes, the preceding stylesheet pays no
-attention to the structure and content of the XML input document.
+attention to the structure and content of the XML input document.
Instead, it processes the template (in the stylesheet) bound to the
-variable named `rtf`.
+variable named *rtf*.
## intersection
-Implemented in `FunctionIntersection`, `intersection (node-set1, node-set2)`
-returns a `node-set` with all nodes that are in `ns1` and in `ns2`.
+Implemented in `FunctionIntersection`,
+`intersection (node-set1, node-set2)`
+returns a `node-set` with all nodes that are in *node-set1* and in
+*node-set2*.
## difference
Implemented in `FunctionDifference`, `difference(node-set1, node-set2)`
-returns a `node-set` with the nodes in `node-set1` and not in
-`node-set2`.
+returns a `node-set` with the nodes in *node-set1* and not in
+*node-set2*.
## distinct
Implemented in `FunctionDistinct`, `distinct (node-set)` returns a
`node-set` containing nodes with distinct string values. If more than
-one node in the `node-set` contains the same text node value, distinct
+one node in the *node-set* contains the same text node value, distinct
only returns the first of these nodes that it finds.
## evaluate
Implemented in `FunctionEvaluate`, `evaluate (xpath-expression)`
-returns the result of evaluating the xpath-expression in the current
+returns the result of evaluating the *xpath-expression* in the current
XPath expression context (automatically passed in by the extension
mechanism).
@@ -143,5 +145,5 @@ is not known until run time.
## hasSameNodes
Implemented in `FunctionHasSameNodes`, `hasSameNodes(node-set1, node-set2)`
-returns true if both `node-set1` and `node-set2` contain exactly the
+returns true if both *node-set1* and *node-set2* contain exactly the
same set of nodes.
diff --git a/faq.md b/faq.md
index 258583a..14d8039 100644
--- a/faq.md
+++ b/faq.md
@@ -13,12 +13,12 @@ For a brief listing of tutorials, discussion forums, and other
materials, see
[Getting up to speed with XSLT](overview.md#getting-up-to-speed-with-xslt).
-
+
## Asking questions about Xalan-C++
*Where can I ask a question?*
-For specific questions on Xalan-C++, see list archives:
+For specific questions on Xalan-C++, see list archives:
[xalan-c-users](http://marc.info/?l=xalan-c-users) and
[xalan-dev](http://marc.info/?l=xalan-dev).
You must subscribe to these Apache mailing lists before posting your
@@ -41,7 +41,7 @@ Again, please review the archives before posting a new question.
*What is Xerces-C++ and why do I need it?*
Xerces-C++ is a validating XML parser written in a portable subset of
-C++. Xerces-C++ makes it easy to give your application the ability to
+C++. Xerces-C++ makes it easy to give your application the ability to
read and write XML data. Like Xalan-C++, Xerces-C++ is available from
the Apache XML site:
[http://xerces.apache.org](http://xerces.apache.org).
@@ -70,76 +70,59 @@ using the internal DOM implementation is the best approach.
In cases where you want to modify the DOM document on the fly, you
should use the Xerces DOM as the base document. You can wrap the
Xerces DOM in a wrapper (see
-[Passing in a Xerces \
DOM](usagepatterns.md#passing-in-a-xerces-dom-to-a-transformation)) +[Passing in a \
Xerces DOM](usagepatterns.md#passing-in-a-xerces-dom-to-a-transformation)) to then \
use as an input to a Xalan transformation. Alternatively you can output the result \
of a transformation to a Xerces DOM document (see [Working with DOM input and \
output](usagepatterns.md#working-with-dom-input-and-output)). In either case, the \
Xerces document can be freely modified. However, after you modify the document, you \
need to re-build the wrapper so that any changes are replicated in the Xalan \
wrappers.
-
+
## Problems with samples in Windows
*I have encountered problem executing the Xalan-C++ sample applications
after rebuilding them under Win32 Environment (Windows NT 4.0, SP3).
-When I tried to execute the sample, I receive the error message
+When I tried to execute the sample, I receive the error message
`Debug Assertion Failed! … Expression: _BLOCK_TYPE_IS_VALID(pHead->nBlockUse)`.*
You may be mixing debug and release versions of executables and
-libraries. In other words, if you are compiling the sample for debug,
+libraries. In other words, if you are compiling the sample for debug,
then you should link with the debug version of the Xalan-C++ and
Xerces-C++ libraries and run with the debug version of the dynamic link
libraries.
-You must also make sure your application is linking with the Debug
-multithreaded DLL run-time library or the Multithreaded DLL run-time
+You must also make sure your application is linking with the "Debug
+Multithreaded DLL" run-time library or the "Multithreaded DLL" run-time
library. To check this setting do the following in Visual C++:
-1. Select Settings from the Project menu.
-2. Click the C/C++ tab.
-3. In the Category drop-down list, select Code Generation.
-4. In the Use run-time library drop-down list, select Multithreaded DLL
- for the Win32 Release configuration, or select Debug Multithreaded
- DLL for the Win32 Debug configuration.
+1. Select "Settings" from the "Project" menu.
+2. Click the "C/C++" tab.
+3. In the Category drop-down list, select "Code Generation".
+4. In the "Use run-time library" drop-down list, select "Multithreaded
+ DLL" for the "Win32 Release" configuration, or select "Debug
+ Multithreaded DLL" for the "Win32 Debug" configuration.
Once you have changed this setting, you must rebuild your project.
+Note: This FAQ entry is largely historical. While mixing Release and
+Debug builds and different runtimes is still inadvisable, the CMake
+build system should link the correct versions of the libraries and
+prevent this happening by accident.
+
## Building on Windows
*What do I need to rebuild Xalan-C++ on Windows?*
-In order to build Xalan-C++ on Windows, you will need the following:
-
-* The Xalan-C/C++ source distribution package.
-* The Xerces-C/C++ source distribution package or a compatible binary
- distribution package.
-* A compatible Microsoft Visual Studio version (e.g. VS2019)
-
-The Xalan-C/C++ source code for all versions is available from the Git
-repository at
-[https://github.com/apache/xalan-c](https://github.com/apache/xalan-c).
-
-Xalan-C++ releases may be downloaded from:
-[Xalan Distributions](http://www.apache.org/dyn/closer.cgi/xalan/xalan-c).
-
-Xerces-C++ may be downloaded from:
-[Xerces Distributions](http://www.apache.org/dyn/closer.cgi/xerces/c/3).
-
-If you are building with the
-[IBM-ICU](http://www.ibm.com/software/globalization/icu/)
-International Components for Unicode library, you will need to rebuild
-both the Xerces and Xalan libraries.
-
For more details, see
+[Downloading Xalan-C++](download.md) and
[Building Xalan-C++](build.md).
## Building on UNIX
*What do I need to rebuild Xalan-C++ on UNIX?*
-To build Xalan-C++ on supported UNIX platforms, you need Xerces-C++,
-CMake, a build tool such as `make` or `ninja`, and a supported C++
-compiler. For more details, see
+For more details, see
+[Downloading Xalan-C++](download.md) and
[Building Xalan-C++](build.md).
## What is ICU
@@ -150,7 +133,7 @@ The
[International Components for Unicode (ICU)](http://icu-project.org/)
is a C and C++ library that provides robust and full-featured Unicode
support on a wide variety of platforms. Xalan-C++ uses the ICU to
-extend support for encoding, number formatting, and sorting.
+extend support for encoding, number formatting, and sorting.
Xalan should work with any release of ICU from the past decade.
@@ -172,7 +155,7 @@ For additional background information on this problem, see the \
online manual
[GNU tar and POSIX tar](http://www.gnu.org/manual/tar/html_chapter/tar_8.html#SEC112)
for the utility.
-
+
## Xalan-C++ in Apache
*Is it possible to run Xalan-C++ from an Apache server?*
@@ -181,30 +164,33 @@ A simple Apache module called
[ApacheModuleXSLT](samples.md#apachemodulexslt)
is provided as a sample. It demonstrates how to integrate Xalan-C++
with Apache.
-
+
## Is Xalan-C++ thread-safe?
*Is Xalan-C++ thread-safe?*
-Instances of `XalanTransformer` are not thread-safe; each thread should
-use its own instance.
+Instances of
+[`XalanTransformer`](https://apache.github.io/xalan-c/api/classxalanc_1_1XalanTransformer.html)
+are not thread-safe; each thread should use its own instance.
In order to support very efficient use in multi-threaded applications,
Xalan-C++ is designed to avoid synchronization as much as possible.
Each thread of execution is required to have its own set of "support"
objects that contain the state of the transformation. Accordingly, no
-synchronization is required when multiple threads are executing.
+synchronization is required when multiple threads are executing.
Parsed ("compiled") stylesheets (see
[Performing a series of \
transformations](usagepatterns.md#performing-a-series-of-transformations)) and \
parsed source documents may be freely shared by multiple threads of execution \
without worrying about providing synchronized access to them.
-The *only* exception to this rule: You use `XercesParserLiaison` to
-parse a document after calling
-`XercesParserLiaison::setBuildBridgeNodes(false)` or
-`XercesParserLiaison::setThreadSafe(false)`. In this case, the
-document *cannot* be shared by multiple threads of execution. For
-reasons of performance, we do not recommend the use of
+The *only* exception to this rule: You use
+[`XercesParserLiaison`](https://apache.github.io/xalan-c/api/classxalanc_1_1XercesParserLiaison.html)
+to parse a document after calling
+[`XercesParserLiaison::setBuildBridgeNodes(false)`](https://apache.github.io/xalan-c/api/classxalanc_1_1XercesParserLiaison.html#a01a4d6c3abaeb09738d555814ef7194c)
+or
+[`XercesParserLiaison::setThreadSafe(false)`](https://apache.github.io/xalan-c/api/classxalanc_1_1XercesParserLiaison.html#af8dc3b5cfae5dd9a1cbdf446e369b9c9).
+In this case, the document *cannot* be shared by multiple threads of
+execution. For reasons of performance, we do not recommend the use of
`XercesParserLiaison`, so this should not be an issue for most
applications.
@@ -222,7 +208,7 @@ To maximize performance, here are some suggestions for you to \
keep in mind as you set up your applications:
* Use a compiled stylesheet when you expect to use the stylesheet more
- than once.
+ than once.
* Set up your stylesheets to function efficiently.
* Don't use `//` (descendant axes) patterns near the root of a large
document.
@@ -257,10 +243,13 @@ literal result elements and produce output that is not valid \
XML.
You can use the `xsl:stylesheet` doctype defined in `xsl-html40s.dtd`
for stylesheets that generate HTML.
-
+
## What does the XalanDOMException HIERARCHY_REQUEST_ERR mean?
-*What does the `XalanDOMException` `HIERARCHY_REQUEST_ERR` mean?*
+*What does the
+[`XalanDOMException`](https://apache.github.io/xalan-c/api/classxalanc_1_1XalanDOMException.html)
+[`HIERARCHY_REQUEST_ERR`](https://apache.github.io/xalan-c/api/classxalanc_1_1XalanD \
OMException.html#a7ace065fde4b86526306d2c9ca3ab074a1333e25db8de187d2caee6513cc9dcc4) \
+mean?*
It means that an attempt was made to add a node to a DOM that would
create an invalid structure. For example, text nodes are not allowed
@@ -272,15 +261,16 @@ might not produce a valid DOM. The usual suspect is text nodes \
being generated before the document element is generated.
If you think you have seen this error because of a bug in Xalan-C++'s
-source tree implementation, please post a bug report on Jira, and
+source tree implementation, please post a bug report on
+[Jira](https://issues.apache.org/jira/browse/XALANC), and
attach a minimal source document and stylesheet that produce the
problem to the bug report.
-
+
## Submitting Patches
*Who do I submit patches to?*
-Your contributions are much appreciated! You can e-mail your patches to
+Your contributions are much appreciated! You can e-mail your patches to
the Xalan Development Mailing List or raise an issue on the
[Jira issue tracking system](https://issues.apache.org/jira/browse/XALANC).
@@ -301,18 +291,23 @@ manual intervention or may be dropped.
## Transformation Output Methods
*How do I output a transformation to a DOM, a file, an in-memory
-buffer, or as input to another transformation? Since the C++
-language can automatically construct an `XSLTResultTarget` from any
-of its constructor's argument types, you usually don't need to create
-one explicitly.*
+buffer, or as input to another transformation?*
+
+Since the C++ language can automatically construct an
+[`XSLTResultTarget`](https://apache.github.io/xalan-c/api/classxalanc_1_1XSLTResultTarget.html)
+from any of its constructor's argument types, you usually don't need to
+create one explicitly.
-The output parameter of `XalanTransformer::transform()` is an
-`XSLTResultTarget` which has many constructors.
+The output parameter of
+[`XalanTransformer::transform()`](https://apache.github.io/xalan-c/api/classxalanc_1_1XalanTransformer.html#a3162d8129224a1a6ed67d8752f3447b4)
+is an
+[`XSLTResultTarget`](https://apache.github.io/xalan-c/api/classxalanc_1_1XSLTResultTarget.html)
+which has many constructors.
Output to a file:
* The easiest way is to use a null-terminated string containing the
- file name to create an XSLTResultTarget. Or, use an instance of
+ file name to create an `XSLTResultTarget`. Or, use an instance of
`std::ofstream`. The command line executables, and many of the
sample applications use file names, so take a look through the
source code for more information.
@@ -326,9 +321,10 @@ Output to an in-memory buffer:
Input to another transformation:
* Any of the previous output targets could be used as the input to
- another transformation, but the `FormatterToSourceTree` is probably
- the best for efficiency reasons. See the source code for the
- `TestXSLT` command line program for more information.
+ another transformation, but the
+ [`FormatterToSourceTree`](https://apache.github.io/xalan-c/api/classxalanc_1_1FormatterToSourceTree.html)
+ is probably the best for efficiency reasons. See the source code for
+ the `TestXSLT` command line program for more information.
## Problems Using Sun's Forte/Workshop Compiler with code containing std::istrstream
@@ -344,13 +340,17 @@ development. The Solaris SunStudio is now available from \
Oracle.
## Modifying an instance of XalanDocument
-*My transformation outputs to a `XalanDocument` (actually
-`XalanSourceTreeDocument` underneath) but W3C DOM functions like
+*My transformation outputs to a
+[`XalanDocument`](https://apache.github.io/xalan-c/api/classxalanc_1_1XalanDocument.html)
+(actually
+[`XalanSourceTreeDocument`](https://apache.github.io/xalan-c/api/classxalanc_1_1XalanSourceTreeDocument.html)
+underneath) but W3C DOM functions like
`DOMElement::setAttribute` don't work! Am I going crazy or what?*
No, you aren't going crazy. Xalan's default source tree is read-only
for efficiency. If you need a DOM that supports modifications, use the
-Xerces DOM instead. See the `TransformToXercesDOM` sample for more
+Xerces DOM instead. See the
+[TransformToXercesDOM](samples.md#transformtoxercesdom) sample for more
information.
## Changing Where Error Output is Sent
@@ -358,22 +358,32 @@ information.
*XalanTransformer outputs errors to the console. How do I, for example,
output error to a file?*
-By default, `XalanTransformer` creates a
-`XalanTransformerProblemListener` (a subclass of `ProblemListener`)
+By default,
+[`XalanTransformer`](https://apache.github.io/xalan-c/api/classxalanc_1_1XalanTransformer.html)
+creates a
+[`XalanTransformerProblemListener`](https://apache.github.io/xalan-c/api/classxalanc_1_1XalanTransformerProblemListener.html)
+(a subclass of
+[`ProblemListener`](https://apache.github.io/xalan-c/api/classxalanc_1_1ProblemListener.html))
that writes output to `std::cerr`. To change this you can:
* Redirect `std::cerr` from the command line.
-* Call `XalanTranformer::setWarningStream` with a different
- `std::ostream` before calling `XalanTransformer::transform`.
-* Instantiate your own `XalanTransformerProblemListener` with a
- different output stream and call
- `XalanTransformer::setProblemListener()` before calling
- `XalanTransformer::transform()`.
-* Subclass some `ProblemListener` type and do custom handling of errors
- (you still then need to tell `XalanTransformer` instances to use your
- ProblemListener).
-
-In most case you probably want to do one of the first two.
+* Call
+ [`XalanTranformer::setWarningStream`](https://apache.github.io/xalan-c/api/classxalanc_1_1XalanTransformer.html#a1c7826710c68a6311329ef7be65253e6)
+ with a different `std::ostream` before calling
+ [`XalanTransformer::transform`](https://apache.github.io/xalan-c/api/classxalanc_1_1XalanTransformer.html#a3162d8129224a1a6ed67d8752f3447b4).
+* Instantiate your own
+ [`XalanTransformerProblemListener`](https://apache.github.io/xalan-c/api/classxalanc_1_1XalanTransformerProblemListener.html)
+ with a different output stream and call
+ [`XalanTransformer::setProblemListener()`](https://apache.github.io/xalan-c/api/classxalanc_1_1XalanTransformer.html#a3dda165f568b89e02bcbf2f56508ec7a)
+ before calling
+ [`XalanTransformer::transform`](https://apache.github.io/xalan-c/api/classxalanc_1_1XalanTransformer.html#a3162d8129224a1a6ed67d8752f3447b4).
+* Subclass some
+ [`ProblemListener`](https://apache.github.io/xalan-c/api/classxalanc_1_1ProblemListener.html)
+ type and do custom handling of errors (you still then need to tell
+ [`XalanTransformer`](https://apache.github.io/xalan-c/api/classxalanc_1_1XalanTransformer.html)
+ instances to use your `ProblemListener`).
+
+In most cases you probably want to do one of the first two.
## Programmatic Error Information
@@ -381,16 +391,21 @@ In most case you probably want to do one of the first two.
number for an error in an XML file?*
Create a custom `ErrorHandler` (a Xerces-C++ class) and call
-`XalanTransformer::setErrorHandler` before parsing any sources.
+[`XalanTransformer::setErrorHandler`](https://apache.github.io/xalan-c/api/classxalanc_1_1XalanTransformer.html#af3eff73a57f2998a2b440c2c4f105371)
+before parsing any sources.
## String Transcoding
-*How do I make a `char*` out of `XalanDOMString` (or vice-versa)?*
+*How do I make a `char*` out of
+[`XalanDOMString`](https://apache.github.io/xalan-c/api/classxalanc_1_1XalanDOMString.html)
+(or vice-versa)?*
-See the static method `XalanDOMString::transcode`, or the functions
-`TranscodeToLocalCodePage` in the API documentation. However, you
-should be very careful when transcoding Unicode characters to the
-local code page, because not all Unicode characters can be
+See the static method
+[`XalanDOMString::transcode`](https://apache.github.io/xalan-c/api/classxalanc_1_1XalanDOMString.html#a0b7ab1c0f2ea4615962437b8837e11d7),
+or the functions
+[`TranscodeToLocalCodePage`](https://apache.github.io/xalan-c/api/namespacexalanc.html#ada7c55659cbbc92271ac1fa128afa07b).
+However, you should be very careful when transcoding Unicode characters
+to the local code page, because not all Unicode characters can be
represented.
## Error Code/Exception Summary
@@ -402,11 +417,11 @@ There isn't, but we're working on it.
## Extension Functions
-*The Xalan extension functions (xalan:node-set, etc.) don't work for
+*The Xalan extension functions (`xalan:node-set()`, etc.) don't work for
me. Help!*
Did you declare the namespace on the `xsl:stylesheet` or
-`xsl:transform` element? It should look like this:
+`xsl:transform` element? It should look like this:
```xml
<xsl:stylesheet version="1.0" xmlns:xalan="http://xml.apache.org/xalan"> …rest \
of stylesheet @@ -430,14 +445,13 @@ Did you build with ICU support? See
There is no Apache Perl wrapper, however Edwin Pratomo has written a
wrapper for Xalan-C++ version 1.4 that can be found on CPAN.
-## Missing LocalMsgIndex.hpp file
+## Missing *LocalMsgIndex.hpp* file
-*Why can't I find the `LocalMsgIndex.hpp` file?*
+*Why can't I find the *LocalMsgIndex.hpp* file?*
-The `LocalMsgIndex.hpp` file is not shipped with the distributions
-because this file is generated during compile time. This file is
-created at the start of the build process and customized for the locale
-and message set you are using.
+The *LocalMsgIndex.hpp* file is not shipped with the source
+distributions because this file is generated during the build process,
+customized for the locale and message set you are using.
-The LocalMsgIndex.hpp file is a member of the
-`include/xalanc/PlatformSupport` directory.
+The *LocalMsgIndex.hpp* file is a member of the
+*include/xalanc/PlatformSupport* directory.
diff --git a/images/Xalan-Trademark.txt b/images/Xalan-Trademark.txt
index 0bd3704..963c94a 100644
--- a/images/Xalan-Trademark.txt
+++ b/images/Xalan-Trademark.txt
@@ -2,7 +2,7 @@
The XALAN Logo - Trademark Description
--------------------------------------
-Prepared By:
+Prepared By:
Steven J. Hathaway
diff --git a/index.md b/index.md
index d34eb78..5e4cdb3 100644
--- a/index.md
+++ b/index.md
@@ -38,7 +38,7 @@
[XML Security Overview](secureweb.md)
-[API reference](api/index.html)
+[API reference](http://xalan.apache.org/xalan-c/apiDocs/index.html) [TODO: use new \
URI]
### Obtaining Xalan-C++
diff --git a/overview.md b/overview.md
index 37bdf08..43f7174 100644
--- a/overview.md
+++ b/overview.md
@@ -7,12 +7,12 @@ Xalan-C++ (named after a rare musical instrument) implements the
and the
[XML Path Language (XPath) Version 1.0](http://www.w3.org/TR/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, +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
-[Getting up to speed with XSLT](#getting-up-to-speed-with-xslt).
+[Getting up to speed with XSLT](#getting-up-to-speed-with-xslt).
Note: XSL also includes a vocabulary for formatting documents, which is
-not part of Xalan-C++. For more information, see
+not part of Xalan-C++. For more information, see
[Extensible Stylesheet Language (XSL) Version 1.0 W3C \
Recommendation](http://www.w3.org/TR/xsl) and the [Apache XML FOP (Formatting \
Objects Project)](http://xmlgraphics.apache.org/fop).
@@ -26,19 +26,20 @@ transformation result).
Note: The XSL stylesheet may generate and refer to cascading style
sheets ([CSS](http://www.w3.org/Style/CSS/)) as part of its output.
-In the following example, the foo.xsl stylesheet is used to transform `foo.xml` into \
`foo.out`: +In the following example, the *foo.xsl* stylesheet is used to transform
+*foo.xml* into *foo.out*:
-`foo.xml`:
+*foo.xml*:
```xml
<?xml version="1.0"?>
<doc>Hello</doc>
```
-`foo.xsl`:
+*foo.xsl*:
```xml
-<?xml version="1.0"?>
+<?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>
@@ -46,7 +47,7 @@ In the following example, the foo.xsl stylesheet is used to \
transform `foo.xml` </xsl:stylesheet>
```
-`foo.out`:
+*foo.out*:
```xml
<out>Hello</out>
@@ -60,7 +61,7 @@ In the following example, the foo.xsl stylesheet is used to \
transform `foo.xml` [XML Path Language (XPath) Version \
1.0](http://www.w3.org/TR/xpath).
* Xalan-C++ uses [Xerces-C++](http://xerces.apache.org/xerces-c/index.html)
to parse XML documents and XSL stylesheets. The input may appear in
- the form of a file or URL, a stream, or a [DOM](http://www.w3.org/DOM).
+ the form of a file or URL, a stream, or a [DOM](http://www.w3.org/DOM).
Xalan-C++ 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.
@@ -86,14 +87,14 @@ following:
* Doug Tidwell's [XSLT](http://www.oreilly.com/catalog/xslt/),
O'Reilly, 2001
* Bob DuCharme's [XSLT Quickly](http://www.manning.com/ducharme/index.html),
- Manning Publications, 2001
-* John Robert Gardner and Zarella Rendon's
+ Manning Publications, 2001
+* John Robert Gardner and Zarella Rendon's
[XSLT and XPath: A Guide to \
Transformations](http://vig.prenhall.com/catalog/academic/product/1,4096,0130404462,00.html),
- Prentice-Hall, 2001
+ Prentice-Hall, 2001
* Elliotte Rusty Harold's
[Chapter 17 of the XML Bible: XSL \
Transformations](http://www.ibiblio.org/xml/books/bible2/chapters/ch17.html)
* The Mulberry
- [XSL-List -- Open Forum on XSL](http://www.mulberrytech.com/xsl/xsl-list/)
+ [XSL-List -- Open Forum on XSL](http://www.mulberrytech.com/xsl/xsl-list/)
(of interest to XSL users at all levels)
* Objects by Design's
[Transforming XMI to \
HTML](http://www.objectsbydesign.com/projects/xmi_to_html.html) @@ -101,15 +102,15 @@ \
following: model," but also covers "generic" XML transformations) and their
related
[XSLT by Example](http://objectsbydesign.com/projects/xslt/xslt_by_example.html)
-* OASIS (the Organization for the Advancement of Structured Information Standards):
+* OASIS (the Organization for the Advancement of Structured Information Standards):
[Extensible Stylesheet Language (XSL)](http://www.oasis-open.org/cover/xsl.html)
by Robin Cover
-* Aaron Skonnard and Martin Gudgin's
- [Essential
+* Aaron Skonnard and Martin Gudgin's
+ [Essential
XML Quick Reference](http://www.theserverside.net/tt/books/addisonwesley/EssentialXML/index.tss"):
A Programmer's Reference to XML, XPath, XSLT, XML Schema, SOAP and
More. This reference is published by Addison Wesley, 2003, ISBN/0201740958.
-
+
When you come across other useful introductory or background materials,
please email the Xalan Development Mailing List, so we can add them to
this list.
@@ -132,7 +133,7 @@ this list.
<br>
<dt><strong>XSL Instruction</strong></dt>
<dd>Any tag associated with the XSLT namespace.</dd>
- <br>
+ <br>
<dt><strong>Template</strong></dt>
<dd>An element, usually with child elements, that specifies a "rule"
or set of instructions to perform when a particular kind of
diff --git a/programming.md b/programming.md
index 3de0476..e5d1519 100644
--- a/programming.md
+++ b/programming.md
@@ -16,7 +16,7 @@ Version 1.8. This feature introduces an object called \
`MemoryManager` which allows applications with stricter memory management \
requirements to utilize a more efficient allocation method. This `MemoryManager`
object can be applied to each processor instance, thus recovery
-procedures from memory leaks or processor crashes will be applied to
+procedures from memory leaks or processor crashes will be applied to
the associated instance only.
The memory management model is similar to the memory management feature
@@ -45,7 +45,7 @@ static void XalanTransformer::initialize(MemoryManager* \
initMemoryManager=0); ```c++
// Create instance of XalanTransformer
MemoryManager memMgrA; // memory manager object
-XalanTransformer transformerA(&memMgrA);
+XalanTransformer transformerA(&memMgrA);
MemoryManager memMgrB;
XalanTransformer transformerB(&memMgrB);
@@ -55,7 +55,7 @@ XalanTransformer transformerD; // Uses default static \
memory manager
The above method demonstrates how users can apply the basic pluggable
memory management feature. Users also have the option of implementing
-their own memory manager. This can be done by simply writing methods
+their own memory manager. This can be done by simply writing methods
for:
```c++
diff --git a/releases.md b/releases.md
index 9d04a3d..82bf0b6 100644
--- a/releases.md
+++ b/releases.md
@@ -11,6 +11,8 @@ The focus of this release is stability and compatibility.
* Xerces-C++ versions 3.0 and newer are supported. Xerces-C++
Version 3.2.3 is the preferred stable release.
* Addition of a CMake build for all supported platforms.
+* Rewrite of StyleBook XML documentation in Markdown, hosted at
+ [https://apache.github.io/xalan-c/](https://apache.github.io/xalan-c/).
* Removal of MacOS and Windows project files for old IDE versions
* Xalan-C++ new supports Microsoft Visual Studio 2019 and earlier
via the new CMake build, which replaces the old version-specific
diff --git a/samples.md b/samples.md
index 4cda117..aa8f56b 100644
--- a/samples.md
+++ b/samples.md
@@ -2,8 +2,9 @@
## Samples to help you get started
-Each of the subdirectories in the Xalan-C++ `samples` directory
-contains the source files for a sample application.
+Each of the subdirectories in the Xalan-C++
+[*samples*](https://github.com/apache/xalan-c/tree/master/samples)
+directory contains the source files for a sample application.
With most of the samples, you can use the following procedure:
@@ -11,16 +12,16 @@ With most of the samples, you can use the following procedure:
shell or PowerShell if you are running Windows)
2. Run the sample from the command line (as indicated below)
3. 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.
+ 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.
Note: Each sample application looks for input files in the current
directory, the directory from which you run the application. The
input files are in the samples subdirectory along with the sample
source files. The location of the sample executables may vary
depending upon the CMake generator used for building. They should
-typically be located within the `builddir/samples/<sample>`. In all
+typically be located within the *builddir/samples/\<sample\>*. In all
cases, be sure the sample executable is on the `PATH`, and run it
from the samples subdirectory that contains the input files.
@@ -33,39 +34,41 @@ of the processor with memory manager.
## ApacheModuleXSLT
Note: This sample must be built with the Apache Web server.
-
+
What it does: runs as an Apache module on an Apache Web server;
performs transformations and returns the output to a Web browser. You
configure Apache to respond to a given URL request for an output file
-(html or txt file in the configuration below) by applying an xsl
-stylesheet file to an xml document file (both with the specified name
+(html or txt file in the configuration below) by applying an XSL
+stylesheet file to an XML document file (both with the specified name
in a given location) and returning the transformation output to the
client.
-This sample also illustrates use of the `XalanTransformer` class and
-the C API defined in src/XalanTransformer/XalanCAPI.h. It returns
-transformation output in blocks to a callback function, which enables
-the browser to start displaying the result before the transformation
-has been completed.
+This sample also illustrates use of the
+[`XalanTransformer`](https://apache.github.io/xalan-c/api/classxalanc_1_1XalanTransformer.html)
+class and the C API defined in
+[*xalanc/XalanTransformer/XalanCAPI.h*](https://apache.github.io/xalan-c/api/XalanCAPI_8h.html#ab9ec00bf3fbe6a946e20418a53891755).
+It returns transformation output in blocks to a callback function,
+which enables the browser to start displaying the result before the
+transformation has been completed.
Note: You may need to configure CMake to locate the required Apache
header files.
-
+
### Setting up and using ApacheModuleXSLT
-To use ApacheModuleXSLT, do the following:
+To use `ApacheModuleXSLT`, do the following:
1. (UNIX only) Be sure the Xalan and Xerces libraries are on your
- system library path, and copy the Apache module to `/usr/lib/apache`.
+ system library path, and copy the Apache module to */usr/lib/apache*.
2. Add `LoadModule` and (UNIX only) `AddModule` entries to the Apache
- configuration file, `httpd.conf`.
+ configuration file, *httpd.conf*.
Windows: `LoadModule xslt_module \
Xalan-C_1_12_0;-<my_Windows_distribution>\bin\ApacheModuleXSLT.dll` UNIX: `AddModule \
mod_xslt.c` and `LoadModule xslt_module /usr/lib/apache/mod_xslt.<ref>xx</ref>`
where `<ref>xx</ref>` is the appropriate library suffix for the
- UNIX platform (".so" or ".a").
+ UNIX platform ("*.so*" or "*.a*").
3. Add a `<Location>` entry to `httpd.conf` that indicates where
- xml/xsl file pairs are to be found, and what target file
+ *.xml* and *.xsl* file pairs are to be found, and what target file
extensions to recognize. We suggest the following:
```xml
<Location /xslt>
@@ -74,39 +77,42 @@ To use ApacheModuleXSLT, do the following:
</Location>
```
This <Location> element instructs the module to respond to requests
- for `xxx.html` and `xxx.txt` files in the in the `xslt` subdirectory
- (under the document root; see next item) by applying the `xxx.xsl`
- stylesheet to `xxx.xml` (both in that directory) and returning the
+ for *xxx.html* and *xxx.txt* files in the in the *xslt* subdirectory
+ (under the document root; see next item) by applying the *xxx.xsl*
+ stylesheet to *xxx.xml* (both in that directory) and returning the
transformation result to the browser.<br>
- For example, a request for `foo.html` instructs the module to apply
- `foo.xsl` to `foo.xml` and return the result.<br>
+ For example, a request for *foo.html* instructs the module to apply
+ *foo.xsl* to *foo.xml* and return the result.<br>
Note: It is up to the stylesheet to apply the appropriate
`xsl:output` method to the output. Whether the user specifies
`html` or `txt` is, of itself, immaterial.
-4. Put xml/xsl file pairs in the `<Location>` subdirectory (xslt in the
- example)) under the document root directory specified in
- `httpd.conf` by the `DocumentRoot` and `<Directory>` settings.
- Alternatively, you can modify these settings to point to
- `samples/ApacheModuleXSLT`, which includes an `xslt` subdirectory
- with xml/xsl file pairs (`foo.xml/xsl`, `apachemod.xml/xsl`).
+4. Put *.xml* and *.xsl* file pairs in the `<Location>` subdirectory
+ (*xslt* in the example) under the document root directory specified
+ in *httpd.conf* by the `DocumentRoot` and `<Directory>` settings.
+ Alternatively, you can modify these settings to point to
+ *samples/ApacheModuleXSLT*, which includes an *xslt* subdirectory
+ with *.xml* and *.xsl* file pairs (*foo.xml* and *foo.xsl*,
+ *apachemod.xml* and *apachemod.xsl*).
5. Start the Apache server.
6. From a Web browser, call the module with a URL as follows:
`http://serverName/xslt/xxx.html`
where `serverName` is the Apache server (such as `www.myServer.com`)
- and `xxx` is the name of an xml/xsl pair of files (such as `foo.xml`
- and `foo.xsl`) in the `xslt` subdirectory under the `DocumentRoot`
+ and `xxx` is the name of an XML/XSL pair of files (such as *foo.xml*
+ and *foo.xsl*) in the *xslt* subdirectory under the `DocumentRoot`
directory.<br>
For example, `http://www.myServer.com/xslt/apachemod.html`
- instructs `ApacheModuleXSLT` to apply the `apachemod.xsl` stylesheet
- to the `apachemod.xml` XML document (both files in the `xslt`
+ instructs `ApacheModuleXSLT` to apply the *apachemod.xsl* stylesheet
+ to the *apachemod.xml* XML document (both files in the *xslt*
directory under the Apache `DocumentRoot` directory) and return the
transformation result to the browser.
-
+
## CompileStylesheet
-What it does: Use a compiled stylesheet to perform a series of transformations.
+What it does: Use a compiled stylesheet to perform a series of
+transformations.
-You can run it from the CompileStylesheet subdirectory with `CompileStylesheet`
+You can run it from the *CompileStylesheet* subdirectory with
+`CompileStylesheet`
See also:
[Performing a series of \
transformations](usagepatterns.md#performing-a-series-of-transformations). @@ -114,67 \
+120,68 @@ See also: ## DocumentBuilder
What it does: Use a `DocumentBuilder` to programmatically construct an
-XML document, apply the `foo.xsl` stylesheet to this document, and
-write the ouput to `foo.out`.
+XML document, apply the *foo.xsl* stylesheet to this document, and
+write the ouput to *foo.out*.
-You can run it from the DocumentBuilder subdirectory with `DocumentBuilder`.
+You can run it from the *DocumentBuilder* subdirectory with
+`DocumentBuilder`.
## ExternalFunctions
What it does: implement, install, and illustrate the 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
+(*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`.
+transformation. The output appears in *foo.out*.
-Run this sample from the `ExternalFunctions` subdirectory with
+Run this sample from the *ExternalFunctions* subdirectory with
`ExternalFunctions`.
See also: [Extension Functions](faq.md#extension-functions).
-
+
## ParsedSourceWrappers
What it does: performs a transformation with input in the form of a
pre-built `XercesDOM` or `XalanSourceTree`.
-Run this sample from the `ParsedSourceWrappers` subdirectory with
+Run this sample from the *ParsedSourceWrappers* subdirectory with
`ParsedSourceWrappers`
See `transformXercesDOM()` and `transformXalanSourceTree()` as called
-by `transform()` in `ParsedSourceWrappers.cpp`.
+by `transform()` in *ParsedSourceWrappers.cpp*.
## SerializeNodeSet
What it does: Serialize the node set returned by the application of an
XPath expression to an XML document.
-Run this sample from the `SerializeNodeSet` subdirectory with
+Run this sample from the *SerializeNodeSet* subdirectory with
```sh
SerializeNodeSet XMLFile ContextNode XPathExpression`
```
-where `XMLFile` is an XML source file, `ContextNode` is the location
-path to the context node, and `XPathExpression` is an XPath expression
-to apply to that context node. The `SerializeNodeSet` directory
-contains the same `foo.xml` sample source file as the preceding
+where *XMLFile* is an XML source file, *ContextNode* is the location
+path to the context node, and *XPathExpression* is an XPath expression
+to apply to that context node. The *SerializeNodeSet* directory
+contains the same *foo.xml* sample source file as the preceding
examples.
## SimpleTransform
-What it does: The `SimpleTransform` class uses the `foo.xsl` stylesheet
-to transform `foo.xml`, and writes the output to `foo.out`. The source
+What it does: The `SimpleTransform` class uses the *foo.xsl* stylesheet
+to transform *foo.xml*, and writes the output to *foo.out*. The source
for this sample has been modified to demonstrate the usage of the new
pluggable memory management feature.
-You can run it from the `SimpleTransform` subdirectory with
+You can run it from the *SimpleTransform* subdirectory with
`SimpleTransform`.
See also:
[Basic procedures for performing XSL \
transformations](usagepatterns.md#xalan-c-basic-usage-patterns).
-
+
## SimpleXPathAPI
What it does: Use the `XPathEvaluator` interface to evaluate an XPath
@@ -185,21 +192,21 @@ 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.
-Run this sample from the `SimpleXPathAPI` subdirectory with:
+Run this sample from the *SimpleXPathAPI* subdirectory with:
```sh
SimpleXPathAPI XMLFile ContextNode XPathExpression
```
-where `XMLFile` is an XML source file, `ContextNode` is the location
-path to the context node, and `XPathExpression` is an XPath expression
+where *XMLFile* is an XML source file, *ContextNode* is the location
+path to the context node, and *XPathExpression* is an XPath expression
to apply to that context node.
Keep in mind that the string value returned by an XPath expression is
the string value of the first node in the nodeset returned by the
expresssion.
-The `XPathWrapper` subdirectory contains an XML file named `xml.foo`
+The *XPathWrapper* subdirectory contains an XML file named *xml.foo*
(part of it appears below).
```xml
@@ -233,30 +240,32 @@ See also:
## SimpleXPathCAPI
-What it does: Use the `XPathEvaluator` C interface to evaluate an XPath
-expression and display the string value returned by the epxression.
+What it does: Use the
+[`XPathEvaluator`](https://apache.github.io/xalan-c/api/classxalanc_1_1XPathEvaluator.html)
+C interface to evaluate an XPath expression and display the string
+value returned by the expression.
Note: Keep in mind that the string value returned by an XPath
-expression is the string value of the first node in the nodeset
-returned by the epxresssion.
+expression is the string value of the first node in the nodeset
+returned by the expresssion.
-Run this sample from the SimpleXPathCAPI subdirectory with:
+Run this sample from the *SimpleXPathCAPI* subdirectory with:
```sh
SimpleXPathCAPI XMLFile XPathExpression
```
-where `XMLFile` is an XML source file, and `XPathExpression` is an
+where *XMLFile* is an XML source file, and *XPathExpression* is an
XPath expression to apply to the XML source file. The
-`SimpleXPathCAPI` subdirectory contains an XML file named `xml.foo`
-identical to `foo.xml` in the preceding example.
+*SimpleXPathCAPI* subdirectory contains an XML file named *xml.foo*
+identical to *foo.xml* in the preceding example.
You can try command lines like:
```sh
SimpleXPathCAPI foo.xml /doc/name[3]
```
-
+
## StreamTransform
What it does: The `StreamTransform` class processes character input
@@ -265,8 +274,8 @@ transformation output to a character output stream. This sample
illustrates the process for working with stylesheets and documents
that you assemble in memory.
-You can run it from the `SimpleTransform` subdirectory with `StreamTransform`.
-
+You can run it from the *SimpleTransform* subdirectory with `StreamTransform`.
+
## ThreadSafe
What it does: Multiple threads use a single compiled stylesheet
@@ -276,18 +285,18 @@ the threads in messages to the console, and each thread writes \
its own output file. Imagine a server application responding to multiple
clients who happen to request the same transformation.
-You can run it from the ThreadSafe subdirectory with `ThreadSafe`.
+You can run it from the *ThreadSafe* subdirectory with `ThreadSafe`.
See also:
-[Performing a series of \
transformations](usagepatterns.md#performing-a-series-of-transformations). \
+[Performing a series of \
transformations](usagepatterns.md#performing-a-series-of-transformations).
## TraceListen
What it does: Trace events during a transformation; the transformation
-uses `birds.xsl` to transform `birds.xml` and writes the output to
-`birds.out`.
+uses *birds.xsl* to transform *birds.xml* and writes the output to
+*birds.out*.
-You can run it from the TraceListen subdirectory with:
+You can run it from the *TraceListen* subdirectory with:
```sh
TraceListen traceFlags
@@ -295,10 +304,10 @@ TraceListen traceFlags
where `traceFlags` is one or more of the following:
-* `-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)
+* *-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)
These flags are also available in the
[command-line utility (TestXSLT)](commandline.md).
@@ -309,10 +318,10 @@ The core of this example is the following fragment:
// Set up a diagnostic writer to be used by the TraceListener…
XalanStdOutputStream theStdErr(cerr);
XalanOutputStreamPrintWriter diagnosticsWriter(theStdErr);
-// Make sure that error reporting, which includes any TraceListener
-// output does not throw exceptions when transcoding, since that could
+// Make sure that error reporting, which includes any TraceListener
+// output does not throw exceptions when transcoding, since that could
// result in an exception being thrown while another exception is active.
-// In particular, characters that the TraceListener writes might not be
+// In particular, characters that the TraceListener writes might not be
// representable in the local code page.
theStdErr.setThrowTranscodeException(false);
@@ -333,21 +342,21 @@ theProcessor.addTraceListener(&theTraceListener);
// Perform the transformation
…
```
-
+
## TransformToXercesDOM
What it does: Performs a simple transformation but puts the result in a
Xerces `DOMDocument`
-Run this sample from the `TransformToXercesDOM` subdirectory with:
+Run this sample from the *TransformToXercesDOM* subdirectory with:
```sh
TransformToXercesDOM XMLFile XSLFile
```
-where `XMLFile` is a source XML file, and `XSLFile` is the XSLT input
-file. The program will use `XSLFile` to transform the input file
-`XMLFile` using Xerces DOM as the output destination.
+where *XMLFile* is a source XML file, and *XSLFile* is the XSLT input
+file. The program will use *XSLFile* to transform the input file
+*XMLFile* using Xerces DOM as the output destination.
See the `FormatterToXercesDOM` usage in the sample code.
@@ -358,7 +367,7 @@ parameters. There are three supported types of parameters. One \
is a text string. A second is a number of type double. A nodeset or
parsed document can also be used.
-You can run it from the `UseStylesheetParam` subdirectory with:
+You can run it from the *UseStylesheetParam* subdirectory with:
```sh
UseStylesheetParam xmlfile stylesheet outfile [options]
@@ -366,9 +375,9 @@ UseStylesheetParam xmlfile stylesheet outfile [options]
where the options are:
-* `-s key "'String-Value'"`
-* `-n key Number`
-* `-d key "Document-URL"`
+* *-s key "'String-Value'"*
+* *-n key Number*
+* *-d key "Document-URL"*
The files used by the sample program and the top-level parameter
nodesets for this illustration are to be in working directory in which
@@ -385,11 +394,11 @@ UseStylesheetParam foo.xml foo.xslt foo.out \
```
The `parmA.xml` and `parmB.xml` files are parsed and converted to
-nodesets. The stylesheet `foo.xslt` merges the contents of `foo.xml`
-and the parameters into the `foo.out` file.
+nodesets. The stylesheet *foo.xslt* merges the contents of *foo.xml*
+and the parameters into the *foo.out* file.
The source sample is implemented in C++. Another example is
-implemented in 'C' using the `XalanCAPI library` `TestCAPIparm.c`. The
+implemented in 'C' using the XalanCAPI library, *TestCAPIparm.c*. The
usage interface for both is the same.
See also:
@@ -397,18 +406,19 @@ See also:
## XalanTransform
-What it does: `XalanTransform` uses the `XalanTransformer` class and
-the associated C++ API to apply an XSL stylesheet file to an XML
-document file and write the transformation output to either an output
-file or to a stream.
+What it does: `XalanTransform` uses the
+[`XalanTransformer`](https://apache.github.io/xalan-c/api/classxalanc_1_1XalanTransformer.html)
+class and the associated C++ API to apply an XSL stylesheet file to an
+XML document file and write the transformation output to either an
+output file or to a stream.
`XalanTransform` takes command-line arguments for the XML document to
-be transformed, the XSL stylesheet to apply, and an optional output
+be transformed, the XSL stylesheet to apply, and an optional output
file argument. If you omit the third argument, `XalanTransform` writes
the transformation output to a stream that is sent to standard out (the
console).
-You can run `XalanTransform` from the `XalanTransform` subdirectory
+You can run `XalanTransform` from the *XalanTransform* subdirectory
with:
```sh
@@ -430,7 +440,7 @@ transformation result, that is to begin working with the \
transformation result before the transformation has been completed. See
[Processing output incrementally](usagepatterns.md#processing-output-incrementally).
-You can run it from the `XalanTransformerCallback` subdirectory with:
+You can run it from the *XalanTransformerCallback* subdirectory with:
```sh
XalanTransformerCallback foo.xml foo.xsl [foo.out]
diff --git a/secureweb.md b/secureweb.md
index dda799a..2b32037 100644
--- a/secureweb.md
+++ b/secureweb.md
@@ -7,7 +7,7 @@ XML architecture. I will try to identify some of the most common
issues and threats and describe some mitigation strategies.
The biggest threat issue is a matter of trust.
-How well do you trust your sources of XML data?
+How well do you trust your sources of XML data?
What are the tools that can help increase the trust?
Most Web Service communications uses HTTP over standard TCP ports.
@@ -15,9 +15,9 @@ The HTTP protocol on standard TCP ports has free access through
business firewalls. How well do your proxy servers handle the Web
Service security issues required for your applications?
-How well are your resource identifiers protected?
-How well do your applications cope with resource identifier spoofing?
-Can your resource identifiers be trusted by outside clients?
+How well are your resource identifiers protected?
+How well do your applications cope with resource identifier spoofing?
+Can your resource identifiers be trusted by outside clients?
Can you trust the credentials of your clients?
Will the SOAP interface for your Web Service send error messages to an
@@ -105,7 +105,7 @@ from an outside source, these entity reference locations may be
unreachable, unreliable, or untrusted.
Web Service SOAP XML documents MUST NOT have `DOCTYPE` definitions.
-SOAP processors should not process `DOCTYPE` definitions.
+SOAP processors should not process `DOCTYPE` definitions.
The conformance is implementation dependent.
[http://www.w3.org/TR/soap](http://www.w3.org/TR/soap)
@@ -122,15 +122,15 @@ resources cannot be localized and secured.
A similar method can be designed specifically for each application.
-A trusted application may need to pre-screen any entity definitions in XML
+A trusted application may need to pre-screen any entity definitions in XML
before passing the information into the core of the application.
-A trusted application should install some type of entity resolving catalog
+A trusted application should install some type of entity resolving catalog
or database that can be trusted.
## Processing Instruction (PI) Threats
-Processing instructions are a mechanism to send specific information
+Processing instructions are a mechanism to send specific information
into an application. A common processing instruction is a stylesheet
declaration. This information is part of an XML document and comes
usually after the XML header and before the root element.
@@ -142,7 +142,7 @@ documents.
[http://www.w3.org/TR/xml-stylesheet](http://www.w3.org/TR/xml-stylesheet)
-Examples in the *xml-stylesheet* recommendation describe how to use the
+Examples in the *xml-stylesheet* recommendation describe how to use the
processing instruction to associate CSS stylesheets for XHTML.
Applications that use XSLT transformations will interpret the
xml-stylesheet processing instruction as the location of a XSLT
@@ -169,7 +169,7 @@ based on specifications that predate the adoption by the
[World Wide Web Consortium (W3C)](http://www.w3.org).
SOAP is not based on Microsoft technology. It is an open standard
drafted by UserLand, Ariba, Commerce One, Compaq, Developmentor, HP,
-IBM, IONA, Lotus, Microsoft, and SAP.
+IBM, IONA, Lotus, Microsoft, and SAP.
[SOAP 1.1](http://www.w3.org/TR/2000/NOTE-SOAP-20000508)
was presented to the W3C in May 2000 as an official Internet standard.
@@ -177,9 +177,9 @@ The original [SOAP 1.1](http://www.w3.org/TR/soap11) standard is
associated with this URI namespace prefix:
`http://schemas.xmlsoap.org/soap/`
-There are significant changes in naming conventions since SOAP 1.1
-was adopted by W3C as a recommended standard.
-The current iteration is [SOAP 1.2](http://www.w3.org/TR/soap12)
+There are significant changes in naming conventions since SOAP 1.1
+was adopted by W3C as a recommended standard.
+The current iteration is [SOAP 1.2](http://www.w3.org/TR/soap12)
and is associated with this URI namespace prefix:
`http://www.w3.org/2003/05`
diff --git a/usagepatterns.md b/usagepatterns.md
index ac5ca8e..6e91f53 100644
--- a/usagepatterns.md
+++ b/usagepatterns.md
@@ -1,29 +1,40 @@
# Xalan-C++ basic usage patterns
-
+
## Introduction
-To perform a transformation, use one of the `XalanTransformer`
-`transform()` methods. The transformation requires an XML source
-document and an XSL stylesheet. Both of these objects may be
-represented by instances of `XSLTInputSource`. You can construct an
-`XSLTInputSource` with a string (the system ID for a file or URI), an
-input stream, or a DOM.
+To perform a transformation, use one of the
+[`XalanTransformer`](https://apache.github.io/xalan-c/api/classxalanc_1_1XalanTransformer.html)
+[`transform()`](https://apache.github.io/xalan-c/api/classxalanc_1_1XalanTransformer.html#a3162d8129224a1a6ed67d8752f3447b4)
+methods. The transformation requires an XML source document and an XSL
+stylesheet. Both of these objects may be represented by instances of
+[`XSLTInputSource`](https://apache.github.io/xalan-c/api/classxalanc_1_1XSLTInputSource.html).
+You can construct an `XSLTInputSource` with a
+[string](https://apache.github.io/xalan-c/api/classxalanc_1_1XSLTInputSource.html#ab3f2b4a5da76309980d5c041ea19d285)
+(the system ID for a file or URI), an
+[input stream](https://apache.github.io/xalan-c/api/classxalanc_1_1XSLTInputSource.html#a2acff554b429f9a60216cdf27eced1c4),
+or a
+[DOM](https://apache.github.io/xalan-c/api/classxalanc_1_1XSLTInputSource.html#a96deb7a8eba28cb78cc6521f37fbdebb).
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 `XalanCompiledStylesheet`.
+transformations, you can improve performance by calling
+[`transform()`](https://apache.github.io/xalan-c/api/classxalanc_1_1XalanTransformer.html#ad3ea23f954aaadd99a984da3a3c549aa)
+with a compiled stylesheet, an instance of
+[`XalanCompiledStylesheet`](https://apache.github.io/xalan-c/api/classxalanc_1_1XalanCompiledStylesheet.html).
If you are transforming an XML source more than once, you should call
-`transform()` with a parsed XML source, an instance of
-`XalanParsedSource`. See
+[`transform()`](https://apache.github.io/xalan-c/api/classxalanc_1_1XalanTransformer.html#ad3ea23f954aaadd99a984da3a3c549aa)
+with a parsed XML source, an instance of
+[`XalanParsedSource`](https://apache.github.io/xalan-c/api/classxalanc_1_1XalanParsedSource.html).
+See
[Performing a series of transformations](#performing-a-series-of-transformations)
If you XML source document contains a stylesheet Processing Instruction
(PI), you do not need to include a stylesheet object when you call
-`transform()`.
+[`transform()`](https://apache.github.io/xalan-c/api/classxalanc_1_1XalanTransformer.html#a4adf2164af0f66831931ee104e383560).
-The transformation output is represented by an `XSLTResultTarget`, which
-you can set up to refer to an output stream, the system ID for a file
-or URI, or a Formatter for one of the various styles of DOM output.
+The transformation output is represented by an
+[`XSLTResultTarget`](https://apache.github.io/xalan-c/api/classxalanc_1_1XSLTResultTarget.html),
+which you can set up to refer to an output stream, the system ID for a
+file or URI, or a Formatter for one of the various styles of DOM output.
For detailed API documentation, see the Xalan-C++ API (doxygen). For
an overview of the command-line utility, see
@@ -31,18 +42,21 @@ an overview of the command-line utility, see
## Basic usage pattern with the XalanTransformer C++ API
-Using `XalanTransformer` and the C++ API, you can perform one or more
-transformations as described in the following steps.
+Using
+[`XalanTransformer`](https://apache.github.io/xalan-c/api/classxalanc_1_1XalanTransformer.html)
+and the C++ API, you can perform one or more transformations as
+described in the following steps.
Note: For a working sample that illustrates these steps, see the
[XalanTransform](samples.md#xalantransform) sample.
-
+
### 1. Include the required header files
-Always start with `xalanc/Include/PlatformDefinitions.hpp`, the
-Xalan-C++ base header file. Also include
-`xercesc/util/PlatformUtils.hpp`,
-`xalanc/XalanTransformer/XalanTransformer.hpp`, and any other header
+Always start with
+[*xalanc/Include/PlatformDefinitions.hpp*](https://apache.github.io/xalan-c/api/PlatformDefinitions_8hpp.html),
+the Xalan-C++ base header file. Also include
+*xercesc/util/PlatformUtils.hpp* and
+[*xalanc/XalanTransformer/XalanTransformer.hpp*](https://apache.github.io/xalan-c/api/XalanTransformer_8hpp.html), \
and any other header files your particular application requires.
```c++
@@ -86,10 +100,14 @@ XalanTransformer theXalanTransformer;
### 5. Perform each transformation
-You can explicitly instantiate `XSLTInputSource` objects for the XML
-source document and XSL stylesheet, and an `XSLTResultTarget` object
-for the output, and then call `XalanTransformer` `transform()` with
-those objects as parameters. For example:
+You can explicitly instantiate
+[`XSLTInputSource`](https://apache.github.io/xalan-c/api/classxalanc_1_1XSLTInputSource.html)
+objects for the XML source document and XSL stylesheet, and an
+[`XSLTResultTarget`](https://apache.github.io/xalan-c/api/classxalanc_1_1XSLTResultTarget.html)
+object for the output, and then call
+[`XalanTransformer`](https://apache.github.io/xalan-c/api/classxalanc_1_1XalanTransformer.html)
+[`transform()`](https://apache.github.io/xalan-c/api/classxalanc_1_1XalanTransformer.html#a3162d8129224a1a6ed67d8752f3447b4)
+with those objects as parameters. For example:
```c++
XSLTInputSource xmlIn("foo.xml");
@@ -112,26 +130,28 @@ int theResult =
theXalanTransformer.transform(xmlIn,xslIn,xmlOut)
```
-Keep in mind that `XSLTInputSource` and `XSLTResultTarget` provide a
-variety of single-argument constructors that you can use in this manner:
-
-* XSLTInputSource(const char* systemID)
-* XSLTInputSource(const XMLCh* systemID) (Unicode characters)
-* XSLTInputSource(istream* stream)
-* XSLTInputSource(XalanNode* node)
-* XSLTResultTarget(char* fileName)
-* XSLTResultTarget(XalanDOMString& fileName)
-* XSLTResultTarget(ostream* stream)
-* XSLTResultTarget(ostream& stream)
-* XSLTResultTarget(Writer* characterStream)
-* XSLTResultTarget(XalanDocument* document)
-* XSLTResultTarget(XalanDocumentFragment* documentFragment)
-* XSLTResultTarget(XalanElement* element)
-* XSLTResultTarget(FormatterListener& flistener)
+Keep in mind that
+[`XSLTInputSource`](https://apache.github.io/xalan-c/api/classxalanc_1_1XSLTInputSource.html)
+and
+[`XSLTResultTarget`](https://apache.github.io/xalan-c/api/classxalanc_1_1XSLTResultTarget.html)
+provide a variety of single-argument constructors that you can use in
+this manner:
+
+* [`XSLTInputSource(const char* \
systemID)`](https://apache.github.io/xalan-c/api/classxalanc_1_1XSLTInputSource.html#ab3f2b4a5da76309980d5c041ea19d285)
+* [`XSLTInputSource(const XMLCh* \
systemID)`](https://apache.github.io/xalan-c/api/classxalanc_1_1XSLTInputSource.html#a4f64b6ad613e97df373a08560edcbde0) \
(Unicode characters) +* [`XSLTInputSource(istream* \
stream)`](https://apache.github.io/xalan-c/api/classxalanc_1_1XSLTInputSource.html#a15252c4b7551019fde32c809a925a2e0)
+* [`XSLTInputSource(XalanNode* \
node)`](https://apache.github.io/xalan-c/api/classxalanc_1_1XSLTInputSource.html#a96deb7a8eba28cb78cc6521f37fbdebb)
+* [`XSLTResultTarget(char* \
fileName)`](https://apache.github.io/xalan-c/api/classxalanc_1_1XSLTResultTarget.html#a5ad1a1cc659c8b321acfdb088d2012d3)
+* [`XSLTResultTarget(XalanDOMString& \
fileName)`](https://apache.github.io/xalan-c/api/classxalanc_1_1XSLTResultTarget.html#a81dfd0938ce7f8b81512cba2fce5f9b2)
+* [`XSLTResultTarget(ostream* \
stream)`](https://apache.github.io/xalan-c/api/classxalanc_1_1XSLTResultTarget.html#aed57158ea3eabcc3dda8164b8f9afd38)
+* [`XSLTResultTarget(ostream& \
stream)`](https://apache.github.io/xalan-c/api/classxalanc_1_1XSLTResultTarget.html#a1dc8e4ec1b6817fcba5463292342e363)
+* [`XSLTResultTarget(Writer* \
characterStream)`](https://apache.github.io/xalan-c/api/classxalanc_1_1XSLTResultTarget.html#af1a6f0f49f60232ae5b57c839c35aca0)
+* [`XSLTResultTarget(FormatterListener& \
flistener)`](https://apache.github.io/xalan-c/api/classxalanc_1_1XSLTResultTarget.html#a931414334729593141383f5c26e0d50d)
Note: Each `transform()` method returns an integer code, 0 for success.
-If an error occurs, you can use the `getLastError()` method to return a
-pointer to the error message.
+If an error occurs, you can use the
+[`getLastError()`](https://apache.github.io/xalan-c/api/classxalanc_1_1XalanTransformer.html#a79d2edb51363413a1faa575d0e180c36)
+method to return a pointer to the error message.
### 6. Shut down Xalan
@@ -181,12 +201,15 @@ type double. The third is a nodeset (`XalanNode *`) parameter, \
usually implemented as a parsed document.
Any XObject that is created outside of the transformation can be
-associated with a top-level parameter. The `XalanTransformer` has an
-XObject factory whereby top-level parameters can be owned by the
+associated with a top-level parameter. The
+[`XalanTransformer`](https://apache.github.io/xalan-c/api/classxalanc_1_1XalanTransformer.html)
+has an XObject factory whereby top-level parameters can be owned by the
`XalanTransformer` object.
-To set a stylesheet parameter, use the `XalanTransformer`
-`setStylesheetParam()` method. The `setStylesheetParam()` method takes
+To set a stylesheet parameter, use the
+[`XalanTransformer`](https://apache.github.io/xalan-c/api/classxalanc_1_1XalanTransformer.html)
+[`setStylesheetParam()`](https://apache.github.io/xalan-c/api/classxalanc_1_1XalanTransformer.html#a4d634fc758724facf8ac3b880a783cd1)
+method. The `setStylesheetParam()` method takes
two arguments: the parameter name and the value. The value can be a
string type, a number double type, an (`XalanNode *`) pointer to a
nodeset or parsed document, or any XObjectPtr returned from an
@@ -194,10 +217,10 @@ XObject factory.
Top level parameters are sticky. Once set to an instance of an
`XalanTransformer` object, they can be used for multiple
-transformations. The `XalanTransformer` `reset()` method prepares a
-transformer for a new transformation. Use the
-`clearStylesheetParams()` method to release the top-level stylesheet
-parameters.
+transformations. The `XalanTransformer` `reset()` private method
+prepares a transformer for a new transformation. Use the
+[`clearStylesheetParams()`](https://apache.github.io/xalan-c/api/classxalanc_1_1XalanTransformer.html#a40a4246572036efcb4b5d373229ecba1)
+method to release the top-level stylesheet parameters.
The `Xalan` command line utility currently supports only a text string
value for a top-level stylesheet parameter. The single quotes are
@@ -217,9 +240,11 @@ The [UseStylesheetParam](samples.md#usestylesheetparam) sample
application supports all three types of top-level stylesheet
parameters.
-The 'C' language interface `XalanCAPI` also supports the three types of
-top-level parameters. The sample program `TestCAPIparms.c` shows how
-to use top-level parameters with 'C' language programs.
+The 'C' language interface
+[`XalanCAPI`](https://apache.github.io/xalan-c/api/XalanCAPI_8h.html)
+also supports the three types of top-level parameters. The sample
+program *TestCAPIparms.c* shows how to use top-level parameters with
+'C' language programs.
Note: The `Xalan` command line utility should be revised to accommodate
the number and nodeset types of top-level stylesheet parameters. Only
@@ -230,9 +255,12 @@ useful for the merging of multiple XML documents.
## Processing output incrementally
-`XalanTransformer` 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:
+[`XalanTransformer`](https://apache.github.io/xalan-c/api/classxalanc_1_1XalanTransformer.html)
+provides a
+[`transform()`](https://apache.github.io/xalan-c/api/classxalanc_1_1XalanTransformer.html#a960ea8a2459658b8926db69d3b338814)
+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:
```c++
int
@@ -253,17 +281,25 @@ 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()`.
-
-`XalanTransformer` includes methods for creating compiled stylesheets
-and parsed XML documents: the `compileStylesheet()` method returns a
-`XalanCompiledStylesheet`; the `parseSource()` method returns a pointer
-`XalanParsedSource`.
+representation when you call
+[`transform()`](https://apache.github.io/xalan-c/api/classxalanc_1_1XalanTransformer.html#a3162d8129224a1a6ed67d8752f3447b4).
+
+[`XalanTransformer`](https://apache.github.io/xalan-c/api/classxalanc_1_1XalanTransformer.html)
+includes methods for creating compiled stylesheets and parsed XML
+documents: the
+[`compileStylesheet()`](https://apache.github.io/xalan-c/api/classxalanc_1_1XalanTransformer.html#a9d31d4b43de86a6077f2df2a5a42c9d5)
+method returns a
+[`XalanCompiledStylesheet`](https://apache.github.io/xalan-c/api/classxalanc_1_1XalanCompiledStylesheet.html);
+the
+[`parseSource()`](https://apache.github.io/xalan-c/api/classxalanc_1_1XalanTransformer.html#ac03dba7386d874e22bf774ecb8dbd212)
+method returns a pointer
+[`XalanParsedSource`](https://apache.github.io/xalan-c/api/classxalanc_1_1XalanParsedSource.html).
Note: In the case of failure, both methods return 0.
-Example using a `XalanCompiledStylesheet` to perform multiple
-transformations:
+Example using a
+[`XalanCompiledStylesheet`](https://apache.github.io/xalan-c/api/classxalanc_1_1XalanCompiledStylesheet.html)
+to perform multiple transformations:
```c++
XalanCompiledStylesheet* compiledStylesheet = 0;
@@ -277,7 +313,9 @@ theXalanTransformer.transform("foo2.xml", *compiledStylesheet, \
"foo2.out"); For a working sample, see the
[CompileStylesheet](samples.md#compilestylesheet) sample.
-Example using a `XalanParsedSource` for multiple transformations:
+Example using a
+[`XalanParsedSource`](https://apache.github.io/xalan-c/api/classxalanc_1_1XalanParsedSource.html)
+for multiple transformations:
```c++
XalanParsedSource* parsedXML = 0;
@@ -293,8 +331,10 @@ stylesheet, see [ThreadSafe](samples.md#threadsafe).
## Working with DOM input and output
-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.
+You can set up an
+[`XSLTResultTarget`](https://apache.github.io/xalan-c/api/classxalanc_1_1XSLTResultTarget.html)
+to produce a DOM when you perform a transformation. You can also use a
+DOM as input for a transformation.
The following code fragment illustrates the procedures for working with
DOM output:
@@ -317,9 +357,9 @@ using xalanc::XalanTransformer;
// If you want to produce DOM output, create an empty Xerces Document
// to contain the transformation output.
-
- DOMDocument * theDOM =
- DOMImplementation::getImplementation()->createDocument();
+
+ DOMDocument * theDOM =
+ DOMImplementation::getImplementation()->createDocument();
// Now create a FormatterListener which can be used by the transformer
// to send each output node to the new Xerces document
@@ -329,8 +369,8 @@ using xalanc::XalanTransformer;
// Now do the transform as normal
XalanTransformer theXalanTransformer
int theResult = theXalanTransformer.transform(
- "foo.xml",
- "foo.xsl",
+ "foo.xml",
+ "foo.xsl",
theFormatter);
…
@@ -340,9 +380,10 @@ using xalanc::XalanTransformer;
```
Note: You can also follow the same process but use a
-`FormatterToDeprecatedXercesDOM` if you require a `DOM_Document`
-output. However this is discouraged, as support for the deprecated DOM
-may be removed in future releases of Xalan-C++.
+[`FormatterToDeprecatedXercesDOM`](https://apache.github.io/xalan-c/api/classxalanc_1_1FormatterToDeprecatedXercesDOM.html)
+if you require a `DOM_Document` output. However this is discouraged,
+as support for the deprecated DOM may be removed in future releases of
+Xalan-C++.
If you want to use a Xerces DOM object as input for a transformation
without wrapping the DOM in a `XercesParserLiaison`, see
@@ -364,36 +405,37 @@ crash.
### Passing in a Xerces DOM to a transformation
You may want to use a Xerces DOM that was created without using the
-`XalanTransformer` class. As the following code snippet illustrates,
-`XercesDOMWrapperParsedSource` to pass in a Xerces DOM as the source
-for an XSL transformation.
+[`XalanTransformer`](https://apache.github.io/xalan-c/api/classxalanc_1_1XalanTransformer.html)
+class. As the following code snippet illustrates,
+[`XercesDOMWrapperParsedSource`](https://apache.github.io/xalan-c/api/classxalanc_1_1XercesDOMWrapperParsedSource.html)
+to pass in a Xerces DOM as the source for an XSL transformation.
```c++
#include <xercesc/parsers/DOMParser.hpp>
#include <xalanc/XalanTransformer/XercesDOMWrapperParsedSource.hpp>
-void parseWithXerces(XalanTransformer &xalan,
+void parseWithXerces(XalanTransformer &xalan,
const XSLTInputSource &xmlInput,
const XalanCompiledStylesheet* styleSheet,
const XSLTResultTarget &output,
XMLFileReporter &logFile)
{
XercesDOMParser theParser;
-
+
// Turn on validation and namespace support.
theParser.setDoValidation(true);
theParser.setDoNamespaces(true);
// Parse the document
-
+
theParser.parse(xmlInput);
DOMDocument *theDOM = theParser.getDocument();
theDOM->normalize();
XercesDOMSupport theDOMSupport;
XercesParserLiaison theParserLiaison;
-
- // Use the DOM to create a XercesDOMWrapperParsedSource,
+
+ // Use the DOM to create a XercesDOMWrapperParsedSource,
// which you can pass to the transform method.
try
{
@@ -410,7 +452,7 @@ void parseWithXerces(XalanTransformer &xalan,
{
…
}
-}
+}
```
## Working with XPath expressions
@@ -419,18 +461,21 @@ 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.
-Xalan-C++ provides an `XPathEvaluator` interface to simplify the
-process of executing XPath expressions.
+Xalan-C++ provides an
+[`XPathEvaluator`](https://apache.github.io/xalan-c/api/classxalanc_1_1XPathEvaluator.html)
+interface to simplify the process of executing XPath expressions.
For an example that executes XPath expressions against XML source
-files, see [SimpleXPathAPI](samples.md#simplexpathapi) (takes
-advantage of the `XPathEvaluator` interface) and `XPathWrapper`.
+files, see the [SimpleXPathAPI](samples.md#simplexpathapi) sample
+(which takes advantage of the `XPathEvaluator` interface) and the
+`XPathWrapper` sample.
## Using TraceListener
-`TraceListener` is a debugging abstract base class implemented by
-`TraceListenerDefault`. You can use `TraceListener` to trace any
-combination of the following:
+[`TraceListener`](https://apache.github.io/xalan-c/api/classxalanc_1_1TraceListener.html)
+is a debugging abstract base class implemented by
+[`TraceListenerDefault`](https://apache.github.io/xalan-c/api/classxalanc_1_1TraceListenerDefault.html).
+You can use `TraceListener` to trace any combination of the following:
* Calls to templates
* Calls to template children
@@ -438,11 +483,16 @@ combination of the following:
* Result tree generation events
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 `XSLTEngineImpl` `setTraceSelects()` and
-`addTraceListener()` methods to add the `TraceListener` to an
-`XSLTProcessor`.
-
+[`PrintWriter`](https://apache.github.io/xalan-c/api/classxalanc_1_1PrintWriter.html)
+and a boolean for each of these four tracing options. You can then use
+the
+[`XSLTEngineImpl`](https://apache.github.io/xalan-c/api/classxalanc_1_1XSLTEngineImpl.html)
+[`setTraceSelects()`](https://apache.github.io/xalan-c/api/classxalanc_1_1XSLTEngineImpl.html#a166e1275b28edc1102a1ec3cb83f7e70)
+and
+[`addTraceListener()`](https://apache.github.io/xalan-c/api/classxalanc_1_1XSLTEngineImpl.html#aaf85408a01bdd47b10f3e53e38f547a4)
+methods to add the `TraceListener` to an
+[`XSLTProcessor`](https://apache.github.io/xalan-c/api/classxalanc_1_1XSLTProcessor.html).
+
See the [TraceListen](samples.md#tracelisten) sample
application. The `TraceListen` sample uses `TraceListenerDefault` to
write events to the screen.
@@ -454,14 +504,14 @@ You can use the
extend support for encoding, number formatting, and sorting.
* *Encoding*. Xerces-C++ and Xalan-C++ use UTF-16 encoding to work
- with Unicode data. If you integrate the ICU with Xerces-C++, both
+ with Unicode data. If you integrate the ICU with Xerces-C++, both
Xerces-C++ and Xalan-C++ use ICU support for input and output
transcoding.
* *`format-number()`*. This XSLT function includes two or three
arguments (the third is optional): number, format pattern, and
decimal-format name. Xalan-C++ ignores the format pattern and
optional decimal-format name. If you install ICU support for
- format-number(), this function is fully supported with all its
+ `format-number()`, this function is fully supported with all its
arguments.
* *`xsl:sort`*. If you install ICU support for `xml:sort`, Xalan-C++
implements Unicode-style collation.
@@ -478,7 +528,7 @@ encoding. See the
With ICU support enabled in Xerces-C++, Xalan-C++ automatically uses
ICU support for output encoding (the `xsl:output` encoding attribute).
-### Enabling ICU support for number formatting and sorting
+### Enabling ICU support for number formatting and sorting
If you only want to use the ICU to support number formatting and
sorting, you do not need to enable ICU support in Xalan-C++, but you
@@ -488,11 +538,13 @@ support:
* Define the environment variable `ICUROOT`.
* Substitute ICU support for `format-number()`, `xsl:number`, and/or
`xsl:sort`.
-* Rebuild the Xalan-C++ library to include the `ICUBridge`.
+* Rebuild the Xalan-C++ library to include the
+ [*ICUBridge*](https://apache.github.io/xalan-c/api/dir_2b905b8b39cf407945c0c5e85a4e6b9d.html).
*ICUBridge*
-All Xalan-C++ references to ICU are centralized in the ICUBridge
+All Xalan-C++ references to ICU are centralized in the
+[*ICUBridge*](https://apache.github.io/xalan-c/api/dir_2b905b8b39cf407945c0c5e85a4e6b9d.html)
module, which supplies the infrastructure for enabling ICU support for
number formatting and sorting.
@@ -516,7 +568,7 @@ following:
FunctionICUFormatNumber::FunctionICUFormatNumberInstaller theInstaller;
```
-*Sorting*
+*Sorting*
To enable ICU support for `xsl:sort`, do the following:
@@ -531,7 +583,7 @@ theExecutionContext.installCollationCompareFunctor(&theICUFunctor);
## Basic XalanTransformer usage pattern with the C API
We also include a simple C interface for using the `XalanTransformer`
-class. The [ApacheModuleXSLT](samples.md#apachemodulexslt) sample
+class. The [ApacheModuleXSLT](samples.md#apachemodulexslt) sample
illustrates the use of this C API.
Basic strategy:
@@ -571,8 +623,9 @@ theResult = XalanTransformToFile(xmlfilename,
```
Note: If the XML input file contains a stylesheet processing
-instruction that you want to use, use an empty `XSLTInputSource` for
-the stylesheet argument.
+instruction that you want to use, use an empty
+[`XSLTInputSource`](https://apache.github.io/xalan-c/api/classxalanc_1_1XSLTInputSource.html)
+for the stylesheet argument.
### 5. Shut down Xalan
@@ -587,17 +640,25 @@ C++ API. In particular, you can
* Use stylesheet processing instructions (PI) to indicate the URI of
the stylesheet. Supply `NULL` for the stylesheet argument.
-* Set stylesheet parameters. Use the `SetStylesheetParam()` function.
-* Compile stylesheets. Use the `CompileStylesheet()` method to compile
- a stylesheet, and the `TransformToFileCSS()` or
- `TransformToDataCSS()` function to use the compiled stylesheet in a
- transformation.
-* Parse XML sources. Use the `XalanParseSource()` or
- `XalanParseSouceUseXalan()` method.
+* Set stylesheet parameters. Use the
+ [`SetStylesheetParam()`](https://apache.github.io/xalan-c/api/XalanCAPI_8h.html#af076f4ff44907f720bbfe859ae763271)
+ function.
+* Compile stylesheets. Use the
+ [`CompileStylesheet()`](https://apache.github.io/xalan-c/api/XalanCAPI_8h.html#a051cb11b9652d45700d46a07f2dfeb51)
+ method to compile a stylesheet, and the
+ [`TransformToFile()`](https://apache.github.io/xalan-c/api/XalanCAPI_8h.html#a7c4c4cb77cd7ea68b460d525b4d06dff)
+ or
+ [`TransformToData()`](https://apache.github.io/xalan-c/api/XalanCAPI_8h.html#ad2cf845c20c6b40ee1d558314a81de32)
+ function to use the compiled stylesheet in a transformation.
+* Parse XML sources. Use the
+ [`XalanParseSource()`](https://apache.github.io/xalan-c/api/XalanCAPI_8h.html#a9a376f062779b8e01bbaad16eaf826b4)
+ method.
* 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.
+ [`TransformToData()`](https://apache.github.io/xalan-c/api/XalanCAPI_8h.html#ad2cf845c20c6b40ee1d558314a81de32)
+ function. After you
+ perform the transformation, use the
+ [`XalanFreeData()`](https://apache.github.io/xalan-c/api/XalanCAPI_8h.html#a95ef1a205f372f95d320f53739417653)
+ function to free memory allocated for the output data.
* Send the output to a callback function to process blocks of output
data as they arrive.
---------------------------------------------------------------------
To unsubscribe, e-mail: commits-unsubscribe@xalan.apache.org
For additional commands, e-mail: commits-help@xalan.apache.org
[prev in list] [next in list] [prev in thread] [next in thread]
Configure |
About |
News |
Add a list |
Sponsored by KoreLogic