You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@xerces.apache.org by bo...@apache.org on 2008/09/22 11:50:50 UTC
svn commit: r697763 [3/3] - in /xerces/c/trunk/doc: ./ style/dtd/
Modified: xerces/c/trunk/doc/program-others.xml
URL: http://svn.apache.org/viewvc/xerces/c/trunk/doc/program-others.xml?rev=697763&r1=697762&r2=697763&view=diff
==============================================================================
--- xerces/c/trunk/doc/program-others.xml (original)
+++ xerces/c/trunk/doc/program-others.xml Mon Sep 22 02:50:49 2008
@@ -21,23 +21,23 @@
<s1 title="Programming Guide">
<anchor name="Macro"/>
<s2 title="Version Macro">
- <p>&XercesCName; has defined a numeric preprocessor macro, _XERCES_VERSION, for users to
+ <p>&XercesCName; defines a numeric preprocessor macro, _XERCES_VERSION, for users to
introduce into their code to perform conditional compilation where the
- version of Xerces is detected in order to enable or disable version
+ version of &XercesCName; is detected in order to enable or disable version
specific capabilities. For example,
</p>
<source>
-#if _XERCES_VERSION >= 20304
- // code specific to Xerces-C++ version 2.3.4
+#if _XERCES_VERSION >= 30102
+ // Code specific to Xerces-C++ version 3.1.2 and later.
#else
- // old code here...
+ // Old code.
#endif
</source>
<p>The minor and revision (patch level) numbers have two digits of resolution
- which means that '3' becomes '03' and '4' becomes '04' in this example.
+ which means that '1' becomes '01' and '2' becomes '02' in this example.
</p>
<p>There are also other string macros or constants to represent the Xerces-C++ version.
- Please refer to the header xercesc/util/XercesVersion.hpp for further details.
+ Please refer to the <code>xercesc/util/XercesVersion.hpp</code> header for details.
</p>
</s2>
@@ -45,32 +45,32 @@
<anchor name="Schema"/>
<s2 title="Schema Support">
<p>&XercesCName; contains an implementation of the W3C XML Schema
- Language. See <jump href="schema-&XercesC3Series;.html">the Schema page</jump> for details.
+ Language. See the <jump href="schema-&XercesC3Series;.html">XML Schema Support</jump> page for details.
</p>
</s2>
<anchor name="Progressive"/>
<s2 title="Progressive Parsing">
- <p>In addition to using the <ref>parse()</ref> method to parse an XML File.
- You can use the other two parsing methods, <ref>parseFirst()</ref> and <ref>parseNext()</ref>
- to do 'progressive parsing', so that you don't
- have to depend upon throwing an exception to terminate the
+ <p>In addition to using the <code>parse()</code> method to parse an XML File.
+ You can use the other two parsing methods, <code>parseFirst()</code> and <code>parseNext()</code>
+ to do the so called progressive parsing. This way you don't
+ have to depend on throwing an exception to terminate the
parsing operation.
</p>
<p>
- Calling parseFirst() will cause the DTD (both internal and
+ Calling <code>parseFirst()</code> will cause the DTD (both internal and
external subsets), and any pre-content, i.e. everything up to
but not including the root element, to be parsed. Subsequent calls to
- parseNext() will cause one more pieces of markup to be parsed,
- and spit out from the core scanning code to the parser (and
- hence either on to you if using SAX or into the DOM tree if
+ <code>parseNext()</code> will cause one more pieces of markup to be parsed,
+ and propagated from the core scanning code to the parser (and
+ hence either on to you if using SAX/SAX2 or into the DOM tree if
using DOM).
</p>
<p>
You can quit the parse any time by just not
- calling parseNext() anymore and breaking out of the loop. When
- you call parseNext() and the end of the root element is the
+ calling <code>parseNext()</code> anymore and breaking out of the loop. When
+ you call <code>parseNext()</code> and the end of the root element is the
next piece of markup, the parser will continue on to the end
of the file and return false, to let you know that the parse
is done. So a typical progressive parse loop will look like
@@ -93,9 +93,10 @@
while (gotMore && !handler.getDone())
gotMore = parser.parseNext(token);</source>
- <p>In this case, our event handler object (named 'handler'
- surprisingly enough) is watching for some criteria and will
- return a status from its getDone() method. Since the handler
+ <p>In this case, our event handler object (named 'handler')
+ is watching for some criteria and will
+ return a status from its <code>getDone()</code> method. Since
+ the handler
sees the SAX events coming out of the SAXParser, it can tell
when it finds what it wants. So we loop until we get no more
data or our handler indicates that it saw what it wanted to
@@ -120,25 +121,26 @@
<p>Also note that you must create a scan token and pass it
back in on each call. This insures that things don't get done
- out of sequence. When you call parseFirst() or parse(), any
+ out of sequence. When you call <code>parseFirst()</code> or
+ <code>parse()</code>, any
previous scan tokens are invalidated and will cause an error
if used again. This prevents incorrect mixed use of the two
different parsing schemes or incorrect calls to
- parseNext().</p>
+ <code>parseNext()</code>.</p>
</s2>
<anchor name="GrammarCache"/>
- <s2 title="Preparsing Grammar and Grammar Caching">
- <p>&XercesCName; &XercesC3Version; provides a new function to pre-parse the grammar so that users
- can check for any syntax or error before using the grammar. Users can also optionally
+ <s2 title="Pre-parsing Grammar and Grammar Caching">
+ <p>&XercesCName; provides a function to pre-parse the grammar so that users
+ can check for any syntax error before using the grammar. Users can also optionally
cache these pre-parsed grammars for later use during actual parsing.
</p>
<p>Here is an example:</p>
<source>
XercesDOMParser parser;
-// enbale schema processing
+// Enable schema processing.
parser.setDoSchema(true);
parser.setDONamespaces(true);
@@ -220,8 +222,9 @@
<ul>
<li>When caching/reusing DTD grammars, no internal subset is allowed.</li>
<li>When preparsing grammars with caching option enabled, if a grammar, in the
- result set, already exists in the pool (same NS for schema or same system
- id for DTD), the entire set will not be cached.</li>
+ result set, already exists in the pool (same namespace for schema or same system
+ id for DTD), the entire set will not be cached. This behavior is the default but can
+ be overridden for XML Schema caching. See the SAX/SAX2/DOM parser features for details.</li>
<li>When parsing an XML document with the grammar caching option enabled, the
reuse option is also automatically enabled. We will only parse a grammar if it
does not exist in the pool.</li>
@@ -232,7 +235,8 @@
<s2 title="Loadable Message Text">
<p>The &XercesCName; supports loadable message text. Although
- the current drop just supports English, it is capable to support other
+ the current distribution only supports English, it is capable of
+ supporting other
languages. Anyone interested in contributing any translations
should contact us. This would be an extremely useful
service.</p>
@@ -240,7 +244,7 @@
<p>In order to support the local message loading services, all the error messages
are captured in an XML file in the src/xercesc/NLS/ directory.
There is a simple program, in the tools/NLS/Xlat/ directory,
- which can spit out that text in various formats. It currently
+ which can translate that text in various formats. It currently
supports a simple 'in memory' format (i.e. an array of
strings), the Win32 resource format, and the message catalog
format. The 'in memory' format is intended for very simple
@@ -293,78 +297,23 @@
<anchor name="PortingGuidelines"/>
<s2 title="Porting Guidelines">
- <p>All platform dependent code in &XercesCProjectName; has been
+ <p>All platform dependent code in &XercesCName; has been
isolated to a couple of files, which should ease the porting
- effort. Here are the basic steps that should be followed to
- port &XercesCProjectName;.</p>
+ effort. The <code>src/xercesc/util</code> directory
+ contains all such files. In particular:</p>
- <ol>
+ <ul>
+ <li>The <code>src/xercesc/util/FileManagers</code> directory
+ contains implementations of file managers for various
+ platforms.</li>
+
+ <li>The <code>src/xercesc/util/MutexManagers</code> directory
+ contains implementations of mutex managers for various
+ platforms.</li>
- <li>The directory <code>src/xercesc/util/Platforms</code> contains the
- platform sensitive files while <code>src/xercesc/util/Compilers</code> contains
- all development environment sensitive files. Each operating
- system has a file of its own and each development environment
- has another one of its own too.
-
- <br/>
-
- As an example, the Win32 platform as a <code>Win32Defs.hpp</code> file
- and the Visual C++ environment has a <code>VCPPDefs.hpp</code> file.
- These files set up certain define tokens, typedefs,
- constants, etc... that will drive the rest of the code to
- do the right thing for that platform and development
- environment. AIX/CSet have their own <code>AIXDefs.hpp</code> and
- <code>CSetDefs.hpp</code> files, and so on. You should create new
- versions of these files for your platform and environment
- and follow the comments in them to set up your own.
- Probably the comments in the Win32 and Visual C++ will be
- the best to follow, since that is where the main
- development is done.</li>
-
- <li>Next, edit the file <code>XercesDefs.hpp</code>, which is where all
- of the fundamental stuff comes into the system. You will
- see conditional sections in there where the above
- per-platform and per-environment headers are brought in.
- Add the new ones for your platform under the appropriate
- conditionals.</li>
-
- <li>Now edit <code>AutoSense.hpp</code>. Here we set canonical &XercesCProjectName;
- internal <code>#define</code> tokens which indicate the platform and
- compiler. These definitions are based on known platform
- and compiler defines.
- <br/>
- <code>AutoSense.hpp</code> is included in <code>XercesDefs.hpp</code> and the
- canonical platform and compiler settings thus defined will
- make the particular platform and compiler headers to be
- the included at compilation.
- <br/>
- It might be a little tricky to decipher this file so be
- careful. If you are using say another compiler on Win32,
- probably it will use similar tokens so that the platform
- will get picked up already using what is already there.</li>
-
- <li>Once this is done, you will then need to implement a
- version of the <ref>platform utilities</ref> for your platform.
- Each operating system has a file which implements some
- methods of the XMLPlatformUtils class, specific to that
- operating system. These are not terribly complex, so it
- should not be a lot of work. The Win32 version is called
- <code>Win32PlatformUtils.cpp</code>, the AIX version is
- <code>AIXPlatformUtils.cpp</code> and so on. Create one for your
- platform, with the correct name, and empty out all of the
- implementation so that just the empty shells of the
- methods are there (with dummy returns where needed to make
- the compiler happy.) Once you've done that, you can start
- to get it to build without any real implementation.</li>
-
- <li>Once you have the system building, then start
- implementing your own platform utilities methods. Follow
- the comments in the Win32 version as to what they do, the
- comments will be improved in subsequent versions, but they
- should be fairly obvious now. Once you have these
- implementations done, you should be able to start
- debugging the system using the demo programs.</li>
- </ol>
+ <li>The <code>src/xercesc/util/Xerces_autoconf_const*</code> files
+ provide base definitions for various platforms.</li>
+ </ul>
<p>Other concerns are:</p>
@@ -382,87 +331,79 @@
further details.</li>
</ul>
- <p>That is the work required in a nutshell!</p>
- </s2>
-
- <anchor name="CPPNamespace"/>
- <s2 title="Using C++ Namespace">
-
- <p>&XercesCName; &XercesC3Version; supports C++ Namespace as of Version 2.2.0.</p>
-
- <p>The macro <code>XERCES_HAS_CPP_NAMESPACE</code> is defined in each Compiler
- Definition file if C++ Namespace is supported.</p>
- <p>For example in header <code>xercesc/util/Compilers/GCCDefs.hpp</code>,
- the C++ Namespace is enabled:</p>
-
-<source>
-// -------------------------------------------------------------------------
-// Indicate that we support C++ namespace
-// Do not define it if the compile cannot handle C++ namespace
-// -------------------------------------------------------------------------
-#define XERCES_HAS_CPP_NAMESPACE
-</source>
-
- <p>If C++ Namespace support is ENABLED (all the binary
- distributions of &XercesCName; &XercesC3Version; are built
- with C++ Namespace enabled), users' applications must
- namespace qualify all the &XercesCName; classes, data and
- variables with <code>XERCES_CPP_NAMESPACE_QUALIFIER </code>
- or add the <code>XERCES_CPP_NAMESPACE_USE</code>
- statement. Users also need to ensure all forward
- declarations are properly qualified or scoped.</p>
-
- <p>Note: If If C++ Namespace support is ENABLED,
- <code>XERCES_CPP_NAMESPACE_QUALIFIER</code> expands to the
- &XercesCName; namespace name followed by two colons, and
- <code>XERCES_CPP_NAMESPACE_USE</code> expands to the full
- <code>using namespace</code> statement, including the
- semicolon. Do NOT add colons or semicolons following these
- macros in your source.</p>
+ <p>Finally, you need to decide about how to define XMLCh. Generally,
+ XMLCh should be defined to be a type suitable for holding a
+ utf-16 encoded (16 bit) value, usually an <code>unsigned short</code>. </p>
+
+ <p>All XML data is handled within &XercesCName; as strings of
+ XMLCh characters. Regardless of the size of the
+ type chosen, the data stored in variables of type XMLCh
+ will always be utf-16 encoded values. </p>
- <p>If C++ Namespace support is not enabled, both macros expand
- to an empty string. The same holds for macros
- <code>XERCES_CPP_NAMESPACE_BEGIN</code> and
- <code>XERCES_CPP_NAMESPACE_END</code>, introduced in the
- example below. You will also see all of these macros used
- throughout the &XercesCName; source code.</p>
- <p>For example:</p>
-<source>
-#include <stdio.h>
-#include <stdlib.h>
-#include <xercesc/sax/HandlerBase.hpp>
+ <p>Unlike XMLCh, the encoding
+ of wchar_t is platform dependent. Sometimes it is utf-16
+ (AIX, Windows), sometimes ucs-4 (Solaris,
+ Linux), sometimes it is not based on Unicode at all
+ (HP/UX, AS/400, system 390). </p>
+
+ <p>Some earlier releases of &XercesCName; defined XMLCh to be the
+ same type as wchar_t on most platforms, with the goal of making
+ it possible to pass XMLCh strings to library or system functions
+ that were expecting wchar_t parameters. This approach has
+ been abandoned because of</p>
-// indicate using &XercesCName; namespace in general
-XERCES_CPP_NAMESPACE_USE
+ <ul>
+ <li>
+ Portability problems with any code that assumes that
+ the types of XMLCh and wchar_t are compatible
+ </li>
+
+ <li>Excessive memory usage, especially in the DOM, on
+ platforms with 32 bit wchar_t.
+ </li>
+
+ <li>utf-16 encoded XMLCh is not always compatible with
+ ucs-4 encoded wchar_t on Solaris and Linux. The
+ problem occurs with Unicode characters with values
+ greater than 64k; in ucs-4 the value is stored as
+ a single 32 bit quantity. With utf-16, the value
+ will be stored as a "surrogate pair" of two 16 bit
+ values. Even with XMLCh equated to wchar_t, xerces will
+ still create the utf-16 encoded surrogate pairs, which
+ are illegal in ucs-4 encoded wchar_t strings.
+ </li>
+ </ul>
-// need to properly scope any forward declarations
-XERCES_CPP_NAMESPACE_BEGIN
- class AttributeList;
-XERCES_CPP_NAMESPACE_END
-// or namespace qualifier the forward declarations
-class XERCES_CPP_NAMESPACE_QUALIFIER ErrorHandler;
+ </s2>
-class MySAXHandlers : public HandlerBase
-{
-public:
- // -----------------------------------------------------------------------
- // Handlers for the SAX DocumentHandler interface
- // -----------------------------------------------------------------------
- void startElement(const XMLCh* const name, AttributeList& attributes);
- void characters(const XMLCh* const chars, const unsigned int length);
-:
-:
-};
-</source>
+ <anchor name="CPPNamespace"/>
+ <s2 title="Using C++ Namespace">
- <p>All macros used above are defined in header file <code>xercesc/util/XercesDefs.hpp</code>:</p>
+ <p>&XercesCName; makes use of C++ namespace to make sure its
+ definitions do not conflict with other libraries and
+ applications. As a result applications must
+ namespace-qualify all &XercesCName; classes, data and
+ variables using the <code>xercesc</code> name. Alternatively,
+ applications can use <code>using xercesc::<Name>;</code>
+ declarations
+ to make individual &XercesCName; names visible in the
+ current scope
+ or <code>using namespace xercesc;</code>
+ definition to make all &XercesCName; names visible in the
+ current scope.</p>
+
+ <p>While the above information should be sufficient for the majority
+ of applications, for cases where several versions of the &XercesCName;
+ library must be used in the same application, namespace versioning is
+ provided. The following convenience macros can be used to access the
+ &XercesCName; namespace names with versions embedded
+ (see <code>src/xercesc/util/XercesDefs.hpp</code>):</p>
<source>
-#if defined(XERCES_HAS_CPP_NAMESPACE)
#define XERCES_CPP_NAMESPACE_BEGIN namespace &XercesC3NSVersion; {
#define XERCES_CPP_NAMESPACE_END }
#define XERCES_CPP_NAMESPACE_USE using namespace &XercesC3NSVersion;;
@@ -470,111 +411,32 @@
namespace &XercesC3NSVersion; { }
namespace &XercesC3Namespace; = &XercesC3NSVersion;;
-#else
- #define XERCES_CPP_NAMESPACE_BEGIN
- #define XERCES_CPP_NAMESPACE_END
- #define XERCES_CPP_NAMESPACE_USE
- #define XERCES_CPP_NAMESPACE_QUALIFIER
-#endif
-</source>
-
- <p>Users should make use of these pre-defined macro in their applications. For example:</p>
-<source>
-#include <stdio.h>
-#include <stdlib.h>
-#include <xercesc/sax/HandlerBase.hpp>
-
-// indicate using &XercesCName; namespace in general
-XERCES_CPP_NAMESPACE_USE
-
-// need to properly scope any forward declarations
-XERCES_CPP_NAMESPACE_BEGIN
-class AttributeList;
-XERCES_CPP_NAMESPACE_END
-
-// or namespace qualify the forward declarations
-class XERCES_CPP_NAMESPACE_QUALIFIER ErrorHandler;
-
-class MySAXHandlers : public HandlerBase
-{
-public:
- // -----------------------------------------------------------------------
- // Handlers for the SAX DocumentHandler interface
- // -----------------------------------------------------------------------
- void startElement(const XMLCh* const name, AttributeList& attributes);
- void characters(const XMLCh* const chars, const unsigned int length);
-:
-:
-};
-</source>
-
- <p>For those users who want to selectively pick which version of API to use, they can do
- something like the code below (Note that this is not the best of examples, as the
- API is the same in all versions):</p>
-
-<source>
-#if _XERCES_VERSION == 20300
- // code specific to Xerces-C++ version 2.3.0
- new xercesc_2_3::SAXParser();
-#elif _XERCES_VERSION == 20200
- // code specific to Xerces-C++ version 2.2.0
- new xercesc_2_2::SAXParser();
-#else
- // old code here...
- new SAXParser();
-#endif
</source>
-
- <p>But for those who just want to call the latest API, then they should use
- the macro <code>XERCES_CPP_NAMESPACE_QUALIFIER</code>
- for source compatibility:</p>
-
-<source>
-new XERCES_CPP_NAMESPACE_QUALIFIER SAXParser();
-</source>
-
- <p>Header file <code>xercesc/util/XercesDefs.hpp</code> also
- declares <code>namespace &XercesC3Namespace;</code> as a
- generic namespace name which will be assigned to
- <code>xercesc_YY_ZZ</code> in each specific release, where
- "YY" is the Major Release Number and "ZZ" is the Minor
- Version Number. However, when you use
- <code>&XercesC3Namespace;::</code> instead of
- <code>XERCES_CPP_NAMESPACE_QUALIFIER </code> when your
- compiler does not support namespaces, your code will not
- work.</p>
-
-
-
</s2>
<anchor name="SpecifyLocaleForMessageLoader"/>
<s2 title="Specify Locale for Message Loader">
- <p>The &XercesCName; has implemented mechanism to support NLS, though
- the current drop has only English version message file, it is capable
- to support other languages once the translated version of the target
- language is available.</p>
+ <p>&XercesCName; provides mechanisms for Native Language Support (NLS).
+ Even though
+ the current distribution has only English message file, it is capable
+ of supporting other languages once the translated version of the
+ target language is available.</p>
- <p>Application can specify the locale for the message loader in their
+ <p>An application can specify the locale for the message loader in their
very first invocation to XMLPlatformUtils::Initialize() by supplying
a parameter for the target locale intended. The default locale is "en_US".
</p>
-
<source>
-
-...
// Initialize the parser system
try
{
XMLPlatformUtils::Initialize("fr_FR");
}
-
catch ()
{
}
-..
</source>
</s2>
@@ -582,64 +444,58 @@
<anchor name="SpecifyLocationForMessageLoader"/>
<s2 title="Specify Location for Message Loader">
- <p>The &XercesCName; searches for message files at the default message directory, $XERCESCROOT/msg.
+ <p>&XercesCName; searches for message files at the location
+ specified in the <code>XERCESC_NLS_HOME</code> environment
+ variable and, if that is not set, at the default
+ message directory, <code>$XERCESCROOT/msg</code>.
</p>
<p>Application can specify an alternative location for the message files in their
very first invocation to XMLPlatformUtils::Initialize() by supplying
- a parameter for the alternative location intended.
+ a parameter for the alternative location.
</p>
<source>
-
-...
// Initialize the parser system
try
{
- XMLPlatformUtils::Initialize("en_US", "/usr/application_root/msg_home");
+ XMLPlatformUtils::Initialize("en_US", "/usr/nls");
}
-
catch ()
{
}
-..
</source>
</s2>
<anchor name="PluggablePanicHandler"/>
<s2 title="Pluggable Panic Handler">
- <p>The &XercesCName; reports, through the method panic(), any panic encountered,
- to the panic handler installed, which in turn takes whatever action appropriate,
- to handle the panic.
- </p>
- <p>The &XercesCName; allows application plugging a customized panic handler
- (class implementing the interface PanicHandler), in its very first invocation to
- XMLPlatformUtils::Initialize() by supplying a parameter for the panic handler
- intended.
+ <p>&XercesCName; reports panic conditions encountered to the panic
+ handler installed. The panic handler can take whatever action
+ appropriate to handle the panic condition.
+ </p>
+ <p>&XercesCName; allows application to provide a customized panic handler
+ (class implementing the interface PanicHandler), in its very first invocation of
+ XMLPlatformUtils::Initialize().
</p>
- <p>In the absence of such a plugged panic handler, &XercesCName; default
+ <p>In the absence of an application-specific panic handler, &XercesCName; default
panic handler is installed and used, which aborts program whenever a panic
- is seen.
+ condition is encountered.
</p>
<source>
-
-...
// Initialize the parser system
try
{
PanicHandler* ph = new MyPanicHandler();
- XMLPlatformUtils::Initialize("en_US"
- , "/usr/application_root/msg_home"
- , ph);
+ XMLPlatformUtils::Initialize("en_US",
+ "/usr/nls",
+ ph);
}
-
catch ()
{
}
-..
</source>
</s2>
@@ -650,29 +506,18 @@
from crashes of individual components, as well as to allocate
memory more efficiently than a general-purpose OS-level
procedure with no knowledge of the characteristics of the
- program making the requests for memory. As of Xerces-C 2.3.0 this
+ program making the requests for memory. In &XercesCName; this
is supported via the Pluggable Memory Handler.
</p>
- <p>Users that have no particular memory management
- requirements (beyond that components don't leak memory or
- attempt to read from or write to areas of memory they haven't
- been assigned), should notice no behavioural changes in the
- parser, so long as their code conforms to Xerces-C best
- practices (e.g., avoids implicit destruction of objects
- related to the parser after XMLPlatformUtils::Terminate() has
- been called; see <jump href="faq-parse-&XercesC3Series;.html#faq-7">the FAQ
- entry describing a reason why applications may suddenly start
- segfaulting with Xerces-C 2.3.0</jump> for details.). Such users can ignore this subsection and
- continue using the parser as they always had.
- </p>
+
<p>Users who wish to implement their own MemoryManager,
- an interface found in xercesc/framework/MemoryManager.hpp, need
- implement only two methods:</p>
+ an interface found in <code>xercesc/framework/MemoryManager.hpp</code>,
+ need to implement only two methods:</p>
<source>
// This method allocates requested memory.
// the parameter is the requested memory size
// A pointer to the allocated memory is returned.
-virtual void* allocate(size_t size) = 0;
+virtual void* allocate(XMLSize_t size) = 0;
// This method deallocates memory
// The parameter is a pointer to the allocated memory to be deleted
@@ -708,47 +553,11 @@
XMLPlatformUtils::Terminate();
</source>
<p>
- Notice that, to maintain backward compatibility, the
- MemoryManager parameter is positioned last in the list of
- parameters to XMLPlatformUtils::Initialize(); this means that
- all other parameters must be specified with their defaults as
- found in Xerces code if all other aspects of standard
- behaviour are to be preserved.
- </p>
- <p>
If a user provides a MemoryManager object to the parser, then
the user owns that object. It is also important to note that
- Xerces default implementation simply uses the global new and
- delete.
- </p>
- <p>
- Finally, there are two platform/compiler-related
- limitations of our memory handling facilities that
- certain users will need to be aware of:
+ &XercesCName; default implementation simply uses the global
+ new and delete operators.
</p>
- <ul>
- <li>The compiler shipped with HPUX 11 does not understand
- "placement" delete operators. These versions of delete
- have the same signature as our "placement" new operators
- but will only be invoked when an exception is thrown
- during the construction of an object. Since the HP
- compiler does not permit delete to be overridden twice
- within a class, we cannot provide a placement delete;
- hence, in the few cases in which an exception may be
- thrown during object construction by Xerces, destructors of objects
- created during that construction will not be called.</li>
- <li>There is a bug in versions of GCC older than 2.96
- which makes it impossible to have the pluggable memory
- manager create elements in the
- <code>RefHash3KeysIdPool</code> template hashtable.
- Therefore, on this compiler, we must use global new for
- this purpose. These elements will be properly destroyed
- under this compiler; the limitation is that, since the
- pluggable memory manager cannot be used, these particular
- elements will not be destroyed if the user destroys their
- memory manager directly. Note that this hashtable is not
- used that often in Xerces.</li>
- </ul>
</s2>
<anchor name="SecurityManager"/>
@@ -778,11 +587,11 @@
that should suit most applications.
</p>
<p>
- By default, Xerces-C is a wholly conformant XML parser; that
+ By default, &XercesCName; is a wholly conformant XML parser; that
is, no security-related considerations will be observed by
- default. An application must set an instance of the
- SecurityManager class on a Xerces parser in order to make that
- parser behave in a security-conscious manner. i.e.:
+ default. An application must provide an instance of the
+ SecurityManager class to a parser in order to make that
+ parser behave in a security-conscious manner. For example:
</p>
<source>
SAXParser *myParser = new SAXParser();
@@ -793,13 +602,13 @@
</source>
<p>
Note that SecurityManager instances may be set on all kinds of
- Xerces parsers; please see the documentation for the
+ &XercesCName; parsers; please see the documentation for the
individual parsers for details.
</p>
<p>
Note also that the application always owns the SecurityManager
- instance. The default SecurityManager that Xerces provides is
- not thread-safe; although it only uses primitive operations at
+ instance. The default SecurityManager that &XercesCName; provides
+ is not thread-safe; although it only uses primitive operations at
the moment, users may need to extend the class with a
thread-safe implementation on some platforms.
</p>
@@ -807,10 +616,10 @@
<anchor name="UseSpecificScanner"/>
<s2 title="Use Specific Scanner">
- <p>For performance and modularity, the &XercesCName; has implemented a mechanism
- to allow users to specify the scanner to use when scanning an XML document.
- Such mechanism will enable the creation of special purpose scanners that can be easily
- plugged in.</p>
+ <p>For performance and modularity &XercesCName; provides a mechanism
+ for specifying the scanner to be used when scanning an XML document.
+ Such mechanism will enable the creation of special purpose scanners
+ that can be easily plugged in.</p>
<p>&XercesCName; supports the following scanners:</p>
@@ -893,10 +702,12 @@
<source>
// Create a DOMLSParser parser
-DOMLSParser *parser = ((DOMImplementationLS*)impl)->createLSParser(DOMImplementationLS::MODE_SYNCHRONOUS, 0);
+DOMLSParser *parser = ((DOMImplementationLS*)impl)->createLSParser(
+ DOMImplementationLS::MODE_SYNCHRONOUS, 0);
// Specify scanner name - This is optional as IGXMLScanner is the default
-parser->getDomConfig()->setParameter(XMLUni::fgXercesScannerName, (void *)XMLUni::fgIGXMLScanner);
+parser->getDomConfig()->setParameter(
+ XMLUni::fgXercesScannerName, (void *)XMLUni::fgIGXMLScanner);
// Specify other parser features, e.g.
parser->getDomConfig()->setParameter(XMLUni::fgDOMNamespaces, doNamespaces);
Modified: xerces/c/trunk/doc/program-sax.xml
URL: http://svn.apache.org/viewvc/xerces/c/trunk/doc/program-sax.xml?rev=697763&r1=697762&r2=697763&view=diff
==============================================================================
--- xerces/c/trunk/doc/program-sax.xml (original)
+++ xerces/c/trunk/doc/program-sax.xml Mon Sep 22 02:50:49 2008
@@ -18,7 +18,7 @@
<!DOCTYPE s1 SYSTEM "sbk:/style/dtd/document.dtd">
-<s1 title="SAX1 Programming Guide">
+<s1 title="SAX Programming Guide">
<anchor name="UsingSAX1API"/>
<s2 title="Using the SAX API">
@@ -36,11 +36,11 @@
commonly used handler classes are DocumentHandler which is
called when XML constructs are recognized, and ErrorHandler
which is called when an error occurs. The header files for the
- various SAX handler classes are in
- '<&XercesC3InstallDir;>/include/xercesc/sax'</p>
+ various SAX handler classes are in the <code>xercesc/sax/</code>
+ directory.</p>
- <p>As a convenience, &XercesCName; provides the class
- HandlerBase, which is a single class which is publicly derived
+ <p>As a convenience, &XercesCName; provides
+ HandlerBase, a single class which is publicly derived
from all the Handler classes. HandlerBase's default
implementation of the handler callback methods is to do
nothing. A convenient way to get started with &XercesCName; is
@@ -63,7 +63,9 @@
<p>This is the implementation file MySAXHandler.cpp:</p>
<source>#include "MySAXHandler.hpp"
-#include <iostream.h>
+#include <iostream>
+
+using namespace std;
MySAXHandler::MySAXHandler()
{
@@ -87,8 +89,8 @@
}</source>
<p>The XMLCh and AttributeList types are supplied by
- &XercesCName; and are documented in the include
- files. Examples of their usage appear in the source code to
+ &XercesCName; and are documented in the API reference.
+ Examples of their usage appear in the source code for
the sample applications.</p>
</s2>
@@ -96,7 +98,7 @@
<s2 title="SAXParser">
<anchor name="ConstructParser"/>
<s3 title="Constructing a SAXParser">
- <p>In order to use &XercesCName; to parse XML files, you will
+ <p>In order to use &XercesCName; SAX to parse XML files, you will
need to create an instance of the SAXParser class. The example
below shows the code you need in order to create an instance
of SAXParser. The DocumentHandler and ErrorHandler instances
@@ -108,13 +110,10 @@
#include <xercesc/sax/HandlerBase.hpp>
#include <xercesc/util/XMLString.hpp>
- #if defined(XERCES_NEW_IOSTREAMS)
#include <iostream>
- #else
- #include <iostream.h>
- #endif
- XERCES_CPP_NAMESPACE_USE
+ using namespace std;
+ using namespace xercesc;
int main (int argc, char* args[]) {
Modified: xerces/c/trunk/doc/program-sax2.xml
URL: http://svn.apache.org/viewvc/xerces/c/trunk/doc/program-sax2.xml?rev=697763&r1=697762&r2=697763&view=diff
==============================================================================
--- xerces/c/trunk/doc/program-sax2.xml (original)
+++ xerces/c/trunk/doc/program-sax2.xml Mon Sep 22 02:50:49 2008
@@ -36,11 +36,11 @@
commonly used handler classes are ContentHandler which is
called when XML constructs are recognized, and ErrorHandler
which is called when an error occurs. The header files for the
- various SAX2 handler classes are in
- '<&XercesC3InstallDir;>/include/xercesc/sax2'</p>
+ various SAX2 handler classes are in the <code>xercesc/sax2/</code>
+ directory.</p>
- <p>As a convenience, &XercesCName; provides the class
- DefaultHandler, which is a single class which is publicly derived
+ <p>As a convenience, &XercesCName; provides DefaultHandler,
+ a single class which is publicly derived
from all the Handler classes. DefaultHandler's default
implementation of the handler callback methods is to do
nothing. A convenient way to get started with &XercesCName; is
@@ -68,7 +68,9 @@
<p>This is the implementation file MySAX2Handler.cpp:</p>
<source>#include "MySAX2Handler.hpp"
-#include <iostream.h>
+#include <iostream>
+
+using namespace std;
MySAX2Handler::MySAX2Handler()
{
@@ -94,8 +96,8 @@
}</source>
<p>The XMLCh and Attributes types are supplied by
- &XercesCName; and are documented in the include
- files. Examples of their usage appear in the source code to
+ &XercesCName; and are documented in the API Reference.
+ Examples of their usage appear in the source code to
the sample applications.</p>
</s2>
@@ -103,11 +105,11 @@
<s2 title="SAX2XMLReader">
<anchor name="ConstructParser2"/>
<s3 title="Constructing an XML Reader">
- <p>In order to use &XercesCName; to parse XML files, you will
+ <p>In order to use &XercesCName; SAX2 to parse XML files, you will
need to create an instance of the SAX2XMLReader class. The example
below shows the code you need in order to create an instance
of SAX2XMLReader. The ContentHandler and ErrorHandler instances
- required by the SAX API are provided using the DefaultHandler
+ required by the SAX2 API are provided using the DefaultHandler
class supplied with &XercesCName;.</p>
<source>
@@ -116,13 +118,10 @@
#include <xercesc/sax2/DefaultHandler.hpp>
#include <xercesc/util/XMLString.hpp>
- #if defined(XERCES_NEW_IOSTREAMS)
#include <iostream>
- #else
- #include <iostream.h>
- #endif
- XERCES_CPP_NAMESPACE_USE
+ using namespace std;
+ using namespace xercesc;
int main (int argc, char* args[]) {
Modified: xerces/c/trunk/doc/program.xml
URL: http://svn.apache.org/viewvc/xerces/c/trunk/doc/program.xml?rev=697763&r1=697762&r2=697763&view=diff
==============================================================================
--- xerces/c/trunk/doc/program.xml (original)
+++ xerces/c/trunk/doc/program.xml Mon Sep 22 02:50:49 2008
@@ -29,7 +29,8 @@
<source>
#include <xercesc/util/PlatformUtils.hpp>
// Other include files, declarations, and non-&XercesCName; initializations.
-XERCES_CPP_NAMESPACE_USE
+
+using namespace xercesc;
int main(int argc, char* argv[])
{
@@ -97,19 +98,6 @@
</ul>
</s2>
- <s2 title="SAX Programming Guide">
- <p>Read the <jump href="program-sax-&XercesC3Series;.html">SAX Programming Guide</jump> document
- or jump directly to:</p>
- <ul>
- <li><jump href="program-sax-&XercesC3Series;.html#UsingSAX1API">Using the SAX API</jump></li>
- <li><jump href="program-sax-&XercesC3Series;.html#SAXParser">SAXParser</jump></li>
- <ul>
- <li><jump href="program-sax-&XercesC3Series;.html#ConstructParser">Constructing a SAXParser</jump></li>
- <li><jump href="program-sax-&XercesC3Series;.html#SAXFeatures">Supported Features</jump></li>
- </ul>
- </ul>
- </s2>
-
<s2 title="SAX2 Programming Guide">
<p>Read the <jump href="program-sax2-&XercesC3Series;.html">SAX2 Programming Guide</jump> document
or jump directly to:</p>
@@ -124,6 +112,19 @@
</ul>
</s2>
+ <s2 title="SAX Programming Guide">
+ <p>Read the <jump href="program-sax-&XercesC3Series;.html">SAX Programming Guide</jump> document
+ or jump directly to:</p>
+ <ul>
+ <li><jump href="program-sax-&XercesC3Series;.html#UsingSAX1API">Using the SAX API</jump></li>
+ <li><jump href="program-sax-&XercesC3Series;.html#SAXParser">SAXParser</jump></li>
+ <ul>
+ <li><jump href="program-sax-&XercesC3Series;.html#ConstructParser">Constructing a SAXParser</jump></li>
+ <li><jump href="program-sax-&XercesC3Series;.html#SAXFeatures">Supported Features</jump></li>
+ </ul>
+ </ul>
+ </s2>
+
<s2 title="Other Features">
<p>Read the <jump href="program-others-&XercesC3Series;.html">&XercesCName; Programming Guide</jump> document
or jump directly to:</p>
@@ -131,7 +132,7 @@
<li><jump href="program-others-&XercesC3Series;.html#Macro">Version Macros</jump></li>
<li><jump href="program-others-&XercesC3Series;.html#Schema">Schema Support</jump></li>
<li><jump href="program-others-&XercesC3Series;.html#Progressive">Progressive Parsing</jump></li>
- <li><jump href="program-others-&XercesC3Series;.html#GrammarCache">Preparsing Grammar and Grammar Caching</jump></li>
+ <li><jump href="program-others-&XercesC3Series;.html#GrammarCache">Pre-parsing Grammar and Grammar Caching</jump></li>
<li><jump href="program-others-&XercesC3Series;.html#LoadableMessageText">Loadable Message Text</jump></li>
<li><jump href="program-others-&XercesC3Series;.html#PluggableTranscoders">Pluggable Transcoders</jump></li>
<li><jump href="program-others-&XercesC3Series;.html#PortingGuidelines">Porting Guidelines</jump></li>
Modified: xerces/c/trunk/doc/psviwriter.xml
URL: http://svn.apache.org/viewvc/xerces/c/trunk/doc/psviwriter.xml?rev=697763&r1=697762&r2=697763&view=diff
==============================================================================
--- xerces/c/trunk/doc/psviwriter.xml (original)
+++ xerces/c/trunk/doc/psviwriter.xml Mon Sep 22 02:50:49 2008
@@ -21,7 +21,7 @@
<s1 title="Sample: PSVIWriter">
<s2 title="PSVIWriter">
- <p>PSVIWriter shows how to access the PSVI and Schema Component Model
+ <p>PSVIWriter shows how to access the Post Schema Validation Infoset (PSVI) and Schema Component Model
information for the parsed document.</p>
<s3 title="Running PSVIWriter">
@@ -48,11 +48,11 @@
</source>
<p>Here is some sample output from PSVWriter (as the output is verbose
it has been truncated)</p>
-<source>cd &XercesC3InstallDir;-linux/samples/data
+<source>cd &XercesC3InstallDir;/samples/data
PSVIWriter personal.xml
-<document xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
- xmlns:psv="http://apache.org/xml/2001/PSVInfosetExtension"
+<document xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+ xmlns:psv="http://apache.org/xml/2001/PSVInfosetExtension"
xmlns="http://www.w3.org/2001/05/XMLInfoset">
<characterEncodingScheme>UTF8</characterEncodingScheme>
<standalone xsi:nil="true"/>
@@ -62,7 +62,7 @@
<content> @version: </content>
</comment>
-...
+...
</source>
</s3>
</s2>
Modified: xerces/c/trunk/doc/redirect.xml
URL: http://svn.apache.org/viewvc/xerces/c/trunk/doc/redirect.xml?rev=697763&r1=697762&r2=697763&view=diff
==============================================================================
--- xerces/c/trunk/doc/redirect.xml (original)
+++ xerces/c/trunk/doc/redirect.xml Mon Sep 22 02:50:49 2008
@@ -24,13 +24,13 @@
<p>Redirect uses the SAX EntityResolver handler to redirect the
input stream for external entities. It installs an entity
resolver, traps the call to the external DTD file and redirects
- it to another specific file which contains the actual DTD.</p>
+ it to another file which contains the actual DTD.</p>
<s3 title="Running Redirect">
- <p>This program illustrates how a XML application can use the SAX EntityResolver
+ <p>This program illustrates how an application can use the SAX EntityResolver
handler to redirect the input stream for external entities. It installs an entity
- resolver, traps the call to the external DTD file and redirects it to another specific
+ resolver, traps the call to the external DTD file and redirects it to another
file which contains the actual DTD.</p>
<p>The program then counts and reports the number of elements and attributes in
@@ -38,10 +38,10 @@
<source>Redirect <XML file></source>
<p>Redirect is invoked as follows:</p>
-<source>cd &XercesC3InstallDir;-linux/samples/data
+<source>cd &XercesC3InstallDir;/samples/data
Redirect personal.xml</source>
<p>The output is the following:</p>
-<source>cd &XercesC3InstallDir;-linux/samples/data
+<source>cd &XercesC3InstallDir;/samples/data
Redirect personal.xml
personal.xml: 30 ms (37 elems, 12 attrs, 0 spaces, 268 chars)</source>
@@ -58,7 +58,7 @@
redirect all references to entities outside of its domain to local cached copies.</p>
<note>The time reported by the program may be different depending on your
- machine processor.</note>
+ processor speed.</note>
</s3>
</s2>
Modified: xerces/c/trunk/doc/samples.xml
URL: http://svn.apache.org/viewvc/xerces/c/trunk/doc/samples.xml?rev=697763&r1=697762&r2=697763&view=diff
==============================================================================
--- xerces/c/trunk/doc/samples.xml (original)
+++ xerces/c/trunk/doc/samples.xml Mon Sep 22 02:50:49 2008
@@ -21,10 +21,11 @@
<s1 title="&XercesCName; Samples">
<s2 title="Introduction">
- <p>&XercesCName; comes packaged with sample applications that
- demonstrate salient features of the parser using simple
+ <p>&XercesCName; comes with sample applications that
+ demonstrate salient features of the parser. They are simple
applications written on top of the SAX and DOM APIs provided by
- the parser. Sample XML data files are provided in the samples/data directory.</p>
+ the parser. Sample XML data files are provided in the
+ <code>samples/data</code> directory.</p>
</s2>
<s2 title="Running the Samples">
@@ -35,64 +36,54 @@
environment variable is set properly to pick up these shared libraries at
runtime.</p>
- <p>On UNIX platforms you must ensure that <ref>LIBPATH</ref>
+ <p>On UNIX platforms you must ensure that <code>LD_LIBRARY_PATH</code>
environment variable is set properly to pick up the shared libraries at
- runtime. (UNIX gurus will understand here that <ref>LIBPATH</ref> actually
- translates to <em>LD_LIBRARY_PATH</em> on Solaris and Linux, <em>SHLIB_PATH</em> on HP-UX,
- <em>DYLD_LIBRARY_PATH</em> on Mac OS X,
- and stays as <em>LIBPATH</em> on AIX).</p>
-
- <p>To set you LIBPATH (on AIX for example), you would type:</p>
-
- <source>export LIBPATH=&XercesC3InstallDir;/lib:$LIBPATH</source>
-
- <p>On both Windows and UNIX platforms, if the parser is built with icu message loader
- (like IBM XML4C binaries), or message catalog loader, then you need to set another environment
- variable, XERCESC_NLS_HOME to point to the directory, &XercesC3SrcInstallDir;/msg, where
- the message files reside.
+ runtime. (UNIX gurus will understand here that <code>LD_LIBRARY_PATH</code>
+ actually translates to <code>LD_LIBRARY_PATH</code> on Solaris and Linux,
+ <code>SHLIB_PATH</code> on HP-UX, <code>DYLD_LIBRARY_PATH</code> on Mac OS X,
+ and <code>LIBPATH</code> on AIX).</p>
+
+ <p>On both Windows and UNIX platforms, if the parser is built with the ICU
+ message loader or message catalog loader, then you may need to set another
+ environment variable, <code>XERCESC_NLS_HOME</code>, to point to the
+ &XercesC3SrcInstallDir;/msg directory, which is where the message
+ files reside.
</p>
-<source>
-set XERCESC_NLS_HOME=&XercesC3InstallDir;\msg
-or
-export XERCESC_NLS_HOME=&XercesC3InstallDir;/msg
-or
-setenv XERCESC_NLS_HOME=&XercesC3InstallDir;/msg
-</source>
<p>Once you have set up the environment variables, you can run the
samples by opening a command window (or your shell prompt for
UNIX environments).</p>
- <s3 title="&XercesCName; Samples">
+ <s3 title="&XercesCName; Samples">
<ul>
<li><link idref="saxcount-&XercesC3Series;">SAXCount</link>
<br/>SAXCount counts the elements, attributes, spaces and
characters in an XML file.</li>
<li><link idref="saxprint-&XercesC3Series;">SAXPrint</link>
<br/>SAXPrint parses an XML file and prints it out.</li>
+ <li><link idref="sax2count-&XercesC3Series;">SAX2Count</link>
+ <br/>SAX2Count counts the elements, attributes, spaces and
+ characters in an XML file.</li>
+ <li><link idref="sax2print-&XercesC3Series;">SAX2Print</link>
+ <br/>SAX2Print parses an XML file and prints it out.</li>
<li><link idref="domcount-&XercesC3Series;">DOMCount</link>
<br/>DOMCount counts the elements in a XML file.</li>
<li><link idref="domprint-&XercesC3Series;">DOMPrint</link>
<br/>DOMPrint parses an XML file and prints it out.</li>
+ <li><link idref="createdoc-&XercesC3Series;">CreateDOMDocument</link>
+ <br/>CreateDOMDocument creates a DOM tree in memory from scratch.</li>
<li><link idref="memparse-&XercesC3Series;">MemParse</link>
- <br/>MemParse parses XML in a memory buffer, outputing the number of elements and attributes.</li>
+ <br/>MemParse parses XML in a memory buffer, printing the number of elements and attributes.</li>
<li><link idref="redirect-&XercesC3Series;">Redirect</link>
<br/>Redirect redirects the input stream for external entities.</li>
<li><link idref="pparse-&XercesC3Series;">PParse</link>
<br/>PParse demonstrates progressive parsing.</li>
<li><link idref="stdinparse-&XercesC3Series;">StdInParse</link>
<br/>StdInParse demonstrates streaming XML data from standard input.</li>
- <li><link idref="enumva-&XercesC3Series;">EnumVal</link>
- <br/>EnumVal shows how to enumerate the markup decls in a DTD Grammar.</li>
+ <li><link idref="enumval-&XercesC3Series;">EnumVal</link>
+ <br/>EnumVal shows how to enumerate the markup declarations in a DTD Grammar.</li>
<li><link idref="senumval-&XercesC3Series;">SEnumVal</link>
- <br/>SEnumVal shows how to enumerate the markup decls in a Schema Grammar.</li>
- <li><link idref="createdoc-&XercesC3Series;">CreateDOMDocument</link>
- <br/>CreateDOMDocument creates a DOM tree in memory from scratch.</li>
- <li><link idref="sax2count-&XercesC3Series;">SAX2Count</link>
- <br/>SAX2Count counts the elements, attributes, spaces and
- characters in an XML file.</li>
- <li><link idref="sax2print-&XercesC3Series;">SAX2Print</link>
- <br/>SAX2Print parses an XML file and prints it out.</li>
+ <br/>SEnumVal shows how to enumerate the markup declarations in a Schema Grammar.</li>
<li><link idref="psviwriter-&XercesC3Series;">PSVIWriter</link>
<br/>PSVIWriter exposes the underlying PSVI of the parsed XML file.</li>
<li><link idref="scmprint-&XercesC3Series;">SCMPrint</link>
Modified: xerces/c/trunk/doc/sax2count.xml
URL: http://svn.apache.org/viewvc/xerces/c/trunk/doc/sax2count.xml?rev=697763&r1=697762&r2=697763&view=diff
==============================================================================
--- xerces/c/trunk/doc/sax2count.xml (original)
+++ xerces/c/trunk/doc/sax2count.xml Mon Sep 22 02:50:49 2008
@@ -21,13 +21,13 @@
<s1 title="Sample: SAX2Count">
<s2 title="SAX2Count">
- <p>SAX2Count is the simplest application that counts the elements and characters of
+ <p>SAX2Count is a simple application that counts the elements and characters of
a given XML file using the (event based) SAX2 API.</p>
<s3 title="Running SAX2Count">
- <p>The SAX2Count sample parses an XML file and prints out a count of the number of
- elements in the file. To run SAX2Count, enter the following </p>
+ <p>The SAX2Count sample parses an XML file and prints out the number of
+ elements and characters in the file. To run SAX2Count, enter the following </p>
<source>SAX2Count <XML File></source>
<p>The following parameters may be set from the command line </p>
<source>
@@ -47,7 +47,7 @@
NOTE: THIS IS OPPOSITE FROM OTHER SAMPLES.
-s Disable schema processing. Defaults to on.
NOTE: THIS IS OPPOSITE FROM OTHER SAMPLES.
- -locale=ll_CC specify the locale, default: en_US
+ -locale=ll_CC specify the locale, default: en_US
-? Show this help.
* = Default if not provided explicitly.
@@ -56,7 +56,7 @@
<em>-v=never</em> will not use any validation<br/>
<em>-v=auto</em> will validate if a DOCTYPE declaration or a schema declaration is present in the XML document</p>
<p>Here is a sample output from SAX2Count</p>
-<source>cd &XercesC3InstallDir;-linux/samples/data
+<source>cd &XercesC3InstallDir;/samples/data
SAX2Count -v=always personal.xml
personal.xml: 60 ms (37 elems, 12 attrs, 134 spaces, 134 chars)</source>
<p>Running SAX2Count with the validating parser gives a different result because
@@ -66,7 +66,7 @@
<p>Note that the sum of spaces and characters in both versions is the same.</p>
<note>The time reported by the program may be different depending on your
- machine processor.</note>
+ processor speed.</note>
</s3>
</s2>
Modified: xerces/c/trunk/doc/sax2print.xml
URL: http://svn.apache.org/viewvc/xerces/c/trunk/doc/sax2print.xml?rev=697763&r1=697762&r2=697763&view=diff
==============================================================================
--- xerces/c/trunk/doc/sax2print.xml (original)
+++ xerces/c/trunk/doc/sax2print.xml Mon Sep 22 02:50:49 2008
@@ -70,7 +70,7 @@
<em>-v=never</em> will not use any validation<br/>
<em>-v=auto</em> will validate if a DOCTYPE declaration or a schema declaration is present in the XML document</p>
<p>Here is a sample output from SAX2Print</p>
-<source>cd &XercesC3InstallDir;-linux/samples/data
+<source>cd &XercesC3InstallDir;/samples/data
SAX2Print -v=always personal.xml
<?xml version="1.0" encoding="LATIN1"?>
Modified: xerces/c/trunk/doc/saxcount.xml
URL: http://svn.apache.org/viewvc/xerces/c/trunk/doc/saxcount.xml?rev=697763&r1=697762&r2=697763&view=diff
==============================================================================
--- xerces/c/trunk/doc/saxcount.xml (original)
+++ xerces/c/trunk/doc/saxcount.xml Mon Sep 22 02:50:49 2008
@@ -26,7 +26,7 @@
<s3 title="Running SAXCount">
- <p>The SAXCount sample parses an XML file and prints out a count of the number of
+ <p>The SAXCount sample parses an XML file and prints out the number of
elements in the file. To run SAXCount, enter the following </p>
<source>SAXCount <XML File></source>
<p>The following parameters may be set from the command line </p>
@@ -45,7 +45,7 @@
-n Enable namespace processing. Defaults to off.
-s Enable schema processing. Defaults to off.
-f Enable full schema constraint checking. Defaults to off.
- -locale=ll_CC specify the locale, default: en_US
+ -locale=ll_CC specify the locale, default: en_US
-? Show this help.
* = Default if not provided explicitly.
@@ -54,7 +54,7 @@
<em>-v=never</em> will not use any validation<br/>
<em>-v=auto</em> will validate if a DOCTYPE declaration or a schema declaration is present in the XML document</p>
<p>Here is a sample output from SAXCount</p>
-<source>cd &XercesC3InstallDir;-linux/samples/data
+<source>cd &XercesC3InstallDir;/samples/data
SAXCount -v=always personal.xml
personal.xml: 60 ms (37 elems, 12 attrs, 134 spaces, 134 chars)</source>
<p>Running SAXCount with the validating parser gives a different result because
@@ -64,7 +64,7 @@
<p>Note that the sum of spaces and characters in both versions is the same.</p>
<note>The time reported by the program may be different depending on your
- machine processor.</note>
+ processor speed.</note>
</s3>
</s2>
Modified: xerces/c/trunk/doc/saxprint.xml
URL: http://svn.apache.org/viewvc/xerces/c/trunk/doc/saxprint.xml?rev=697763&r1=697762&r2=697763&view=diff
==============================================================================
--- xerces/c/trunk/doc/saxprint.xml (original)
+++ xerces/c/trunk/doc/saxprint.xml Mon Sep 22 02:50:49 2008
@@ -66,7 +66,7 @@
<em>-v=never</em> will not use any validation<br/>
<em>-v=auto</em> will validate if a DOCTYPE declaration or a schema declaration is present in the XML document</p>
<p>Here is a sample output from SAXPrint</p>
-<source>cd &XercesC3InstallDir;-linux/samples/data
+<source>cd &XercesC3InstallDir;/samples/data
SAXPrint -v=always personal.xml
<?xml version="1.0" encoding="LATIN1"?>
Modified: xerces/c/trunk/doc/schema.xml
URL: http://svn.apache.org/viewvc/xerces/c/trunk/doc/schema.xml?rev=697763&r1=697762&r2=697763&view=diff
==============================================================================
--- xerces/c/trunk/doc/schema.xml (original)
+++ xerces/c/trunk/doc/schema.xml Mon Sep 22 02:50:49 2008
@@ -17,35 +17,28 @@
-->
<!DOCTYPE s1 SYSTEM "sbk:/style/dtd/document.dtd">
-<s1 title="Schema">
+<s1 title="XML Schema Support">
<s2 title="Introduction">
- <p>This package contains an implementation of the W3C XML Schema
- Language, a recommendation of the Worldwide Web Consortium
+ <p>&XercesCName; includes an implementation of the W3C XML Schema
+ specification, a recommendation of the Worldwide Web Consortium
available in three parts:
- <jump href="http://www.w3.org/TR/xmlschema-0/">XML Schema: Primer</jump> and
+ <jump href="http://www.w3.org/TR/xmlschema-0/">XML Schema: Primer</jump>,
<jump href="http://www.w3.org/TR/xmlschema-1/">XML Schema: Structures</jump> and
<jump href="http://www.w3.org/TR/xmlschema-2/">XML Schema: Datatypes</jump>.
- We consider this implementation complete except for the limitations cited below.
- </p>
-
- <p>We would very much appreciate feedback on the package via the
- <jump href="&MailURI;">&XercesCName; mailing lists</jump>,
- and we encourage the submission of bugs as described on the
- <jump href="&BugURI;">Bug Reporting</jump> page. Please
- read this document before using this package.
+ We consider this implementation complete except for the limitations outlined below.
</p>
</s2>
<anchor name="limitation"/>
<s2 title="Limitations">
<ul>
- <li>Due to the way in which the parser constructs content
- models for elements with complex content, specifying large
+ <li>In certain complex content models specifying large
values for the <code>minOccurs</code> or <code>maxOccurs</code>
- attributes may cause a stack overflow or very poor performance
- in the parser. Large values for <code>minOccurs</code> should be
- avoided, and <code>unbounded</code> should be used instead of
- a large value for <code>maxOccurs</code>.</li>
+ attributes may result in poor performance and/or large amount
+ of memory being allocated by the parser. In such situations large values for
+ <code>minOccurs</code> should be avoided, and <code>unbounded</code>
+ should be used instead.</li>
+
<li>The parser treats local elements in the same scope with the
same name and namespace as one element declaration and does not
differentiate between them.</li>
@@ -66,8 +59,8 @@
<s3 title="out-of-bound float values">
<p>
- For float data, the specs does not explicitly specify how to deal with
- out-of-bound data. Xerces converts these values as below (the values
+ For float data, the specification does not explicitly prescribe how to deal with
+ out-of-bound data. &XercesCName; converts these values as shown below (the values
depend on the system specific values of FLT_MAX and FLT_MIN):
</p>
<table>
@@ -102,7 +95,7 @@
<s3 title="out-of-bound double values">
<p>
- Similarly, Xerces converts double values as below (the values
+ Similarly, &XercesCName; converts double values as shown below (the values
depend on the system specific values of DBL_MAX and DBL_MIN):
</p>
<table>
@@ -133,7 +126,7 @@
<anchor name="usage"/>
<s2 title="Usage">
- <p>Here is an example how to turn on schema processing in DOMParser
+ <p>Below is an example that shows how to turn on schema processing in DOMParser
(default is off). Note that you must also turn on namespace support
(default is off) for schema processing.
</p>
@@ -143,10 +136,10 @@
parser.setDoSchema(true);
parser.parse(xmlFile);
</source>
- <p>Usage in SAXParser is similar, please refer to the
- sample program 'samples/SAXCount/SAXCount.cpp' for further reference.
+ <p>Usage in SAXParser is similar, please refer to the SAXCount
+ sample program for further reference.
</p>
- <p>Here is an example how to turn on schema processing in SAX2XMLReader
+ <p>Below is an example that shows how to turn on schema processing in SAX2XMLReader
(default is on). Note that namespace must be on (default is on) as well.
</p>
<source>SAX2XMLReader* parser = XMLReaderFactory::createXMLReader();
@@ -154,17 +147,41 @@
parser->setFeature(XMLUni::fgXercesSchema, true);
parser->parse(xmlFile);
</source>
- <p>Review the sample file, 'samples/data/personal-schema.xml' and
- 'samples/data/personal.xsd' for an example of an XML Schema grammar.
- </p>
</s2>
<anchor name="associate"/>
<s2 title="Associating Schema Grammar with instance document">
- <p>Schema grammars can be associated with instance documents in two ways.
+ <p>Schema grammars can be associated with instance documents in three ways.
</p>
- <s3 title="Specifying Schema Grammar through method calls:">
+ <s3 title="Specifying Schema Grammar through attributes in the instance document">
+ <p>If schema grammar was not specified externally through methods,
+ then each instance document that uses XML Schema grammars must specify the location of
+ the grammars it uses by using an xsi:schemaLocation attribute if they use
+ namespaces, and xsi:noNamespaceSchemaLocation attribute otherwise.
+ </p>
+ <p>Here is an example with no target namespace:
+ </p>
+<source><?xml version="1.0" encoding="UTF-8"?>
+<personnel xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+ xsi:noNamespaceSchemaLocation='personal.xsd'>
+...
+</personnel>
+</source>
+ <p>Here is an example with a target namespace. Note that it is an error to specify a
+ different namespace in xsi:schemaLocation attribute than the target namespace
+ defined in the Schema.
+ </p>
+<source><?xml version="1.0" encoding="UTF-8"?>
+<personnel xmlns="http://my.com"
+ xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+ xsi:schemaLocation="http://my.com personal.xsd http://my2.com test2.xsd">
+...
+</personnel>
+</source>
+ </s3>
+
+ <s3 title="Specifying Schema Grammar through method calls">
<p>An application developer may associate schemas with instance documents through
methods <code>setExternalSchemaLocation</code> if they use namespaces, and
<code>setExternalNoNamespaceSchemaLocation</code> otherwise.
@@ -202,12 +219,14 @@
DOMParser parser;
parser.setDoNamespaces(true);
parser.setDoSchema(true);
-parser.setExternalSchemaLocation("http://my.com personal.xsd http://my2.com test2.xsd");
+parser.setExternalSchemaLocation(
+ "http://my.com personal.xsd http://my2.com test2.xsd");
parser.parse("test.xml");
// Instantiate the SAX2 XMLReader.
SAX2XMLReader* parser = XMLReaderFactory::createXMLReader();
-XMLCh* propertyValue = XMLString::transcode("http://my.com personal.xsd http://my2.com test2.xsd");
+XMLCh* propertyValue = XMLString::transcode(
+ "http://my.com personal.xsd http://my2.com test2.xsd");
ArrayJanitor<XMLCh> janValue(propertyValue);
parser->setProperty(
@@ -216,31 +235,14 @@
parser.parse("test.xml");
</source>
</s3>
- <s3 title="Specifying Schema Grammar through attributes in the instance document:">
- <p>If schema grammar was not specified externally through methods,
- then each instance document that uses XML Schema grammars must specify the location of
- the grammars it uses by using an xsi:schemaLocation attribute if they use
- namespaces, and xsi:noNamespaceSchemaLocation attribute otherwise.
- </p>
- <p>Here is an example with no target namespace:
- </p>
-<source><?xml version="1.0" encoding="UTF-8"?>
-<personnel xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
- xsi:noNamespaceSchemaLocation='personal.xsd'>
-...
-</personnel>
-</source>
- <p>Here is an example with a target namespace. Note that it is an error to specify a
- different namespace in xsi:schemaLocation attribute than the target namespace
- defined in the Schema.
- </p>
-<source><?xml version="1.0" encoding="UTF-8"?>
-<personnel xmlns="http://my.com"
- xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
- xsi:schemaLocation="http://my.com personal.xsd http://my2.com test2.xsd">
-...
-</personnel>
-</source>
+
+ <s3 title="Pre-parsing and Caching Schema Grammar">
+ <p>An application developer may also pre-parse and
+ cache the grammar corresponding to the XML document
+ namespace as described in the
+ <jump href="program-others-&XercesC3Series;.html#GrammarCache">Pre-parsing
+ Grammar and Grammar Caching</jump> section of the
+ &XercesCName; Programming Guide.</p>
</s3>
</s2>
</s1>
Modified: xerces/c/trunk/doc/scmprint.xml
URL: http://svn.apache.org/viewvc/xerces/c/trunk/doc/scmprint.xml?rev=697763&r1=697762&r2=697763&view=diff
==============================================================================
--- xerces/c/trunk/doc/scmprint.xml (original)
+++ xerces/c/trunk/doc/scmprint.xml Mon Sep 22 02:50:49 2008
@@ -41,7 +41,7 @@
</source>
<p>Here is some sample output from SCMPrint (as the output is verbose
it has been truncated)</p>
-<source>cd &XercesC3InstallDir;-linux/samples/data
+<source>cd &XercesC3InstallDir;/samples/data
SCMPrint personal.xsd
********** Printing out information from Schema **********
Modified: xerces/c/trunk/doc/senumval.xml
URL: http://svn.apache.org/viewvc/xerces/c/trunk/doc/senumval.xml?rev=697763&r1=697762&r2=697763&view=diff
==============================================================================
--- xerces/c/trunk/doc/senumval.xml (original)
+++ xerces/c/trunk/doc/senumval.xml Mon Sep 22 02:50:49 2008
@@ -21,7 +21,7 @@
<s1 title="Sample: SEnumVal">
<s2 title="SEnumVal">
- <p>SEnumVal shows how to enumerate the markup decls in a Schema Grammar.</p>
+ <p>SEnumVal shows how to enumerate the markup declarations in a Schema Grammar.</p>
<s3 title="Running SEnumVal">
<p>This program parses the specified XML file, then shows how to
@@ -35,7 +35,7 @@
access the Schema information stored in internal data structures.
</source>
<p>Here is a sample output from SEnumVal</p>
-<source>cd &XercesC3InstallDir;-linux/samples/data
+<source>cd &XercesC3InstallDir;/samples/data
SEnumVal personal-schema.xml
Name: personnel
@@ -73,7 +73,7 @@
Default Type: #DEFAULT
Value: false
Base Datatype: string
-Enumeration:
+Enumeration:
true
false
Modified: xerces/c/trunk/doc/stdinparse.xml
URL: http://svn.apache.org/viewvc/xerces/c/trunk/doc/stdinparse.xml?rev=697763&r1=697762&r2=697763&view=diff
==============================================================================
--- xerces/c/trunk/doc/stdinparse.xml (original)
+++ xerces/c/trunk/doc/stdinparse.xml Mon Sep 22 02:50:49 2008
@@ -24,8 +24,8 @@
<p>StdInParse demonstrates streaming XML data from standard input.</p>
<s3 title="Running StdInParse">
- <p>The StdInParse sample parses an XML file from standard input and prints out a
- count of the number of
+ <p>The StdInParse sample parses an XML file from standard input and prints out
+ the number of
elements in the file. To run StdInParse, enter the following: </p>
<source>StdInParse < <XML file></source>
<p>The following parameters may be set from the command line </p>
@@ -52,7 +52,7 @@
<em>-v=auto</em> will validate if a DOCTYPE declaration or a schema declaration is present in the XML document</p>
<p>Make sure that you run StdInParse in the samples/data directory.</p>
<p>Here is a sample output from StdInParse:</p>
-<source>cd &XercesC3InstallDir;-linux/samples/data
+<source>cd &XercesC3InstallDir;/samples/data
StdInParse -v=always < personal.xml
stdin: 10 ms (37 elems, 12 attrs, 0 spaces, 268 chars)</source>
<p>Running StdInParse with the validating parser gives a different result because
@@ -62,7 +62,7 @@
<p>Note that the sum of spaces and characters in both versions is the same.</p>
<note>The time reported by the program may be different depending on your
- machine processor.</note>
+ processor speed.</note>
</s3>
</s2>
</s1>
Modified: xerces/c/trunk/doc/style/dtd/entities.ent
URL: http://svn.apache.org/viewvc/xerces/c/trunk/doc/style/dtd/entities.ent?rev=697763&r1=697762&r2=697763&view=diff
==============================================================================
--- xerces/c/trunk/doc/style/dtd/entities.ent (original)
+++ xerces/c/trunk/doc/style/dtd/entities.ent Mon Sep 22 02:50:49 2008
@@ -5,13 +5,12 @@
<!ENTITY XercesCName "Xerces-C++"> <!-- productname -->
<!ENTITY XercesC3Series "3"> <!-- release series -->
<!ENTITY XercesC3Version "3.0.0"> <!-- 3-series version number -->
-<!ENTITY XercesC3InstallDir "xerces-c_3_0_0"> <!-- installdirname -->
-<!ENTITY XercesC3SrcInstallDir "xerces-c-src_3_0_0"> <!-- sourcedirectory -->
-<!ENTITY XercesC3ToolsInstallDir "xerces-c-tools_3_0_0"> <!-- sourcedirectory -->
+<!ENTITY XercesC3InstallDir "xerces-c-3.0.0"> <!-- installdirname -->
+<!ENTITY XercesC3SrcInstallDir "xerces-c-3.0.0"> <!-- sourcedirectory -->
+<!ENTITY XercesC3ToolsInstallDir "xerces-c-tools-3.0.0"> <!-- sourcedirectory -->
<!ENTITY XercesC3WindowsLib "xerces-c_3"> <!-- windowslibname -->
<!ENTITY XercesC3WindowsDLL "xerces-c_3_0"> <!-- windowsDLLname -->
-<!ENTITY XercesC3UnixSoName "30.0"> <!-- unixlibname -->
-<!ENTITY XercesC3UnixVersion "30"> <!-- unixlibname -->
+<!ENTITY XercesC3UnixSoVersion "3.0"> <!-- unixlibversion -->
<!ENTITY XercesC3UnixLib "libxerces-c"> <!-- unixlibname -->
<!ENTITY XercesC3Namespace "xercesc"> <!-- C++ namespace name -->
<!ENTITY XercesC3NSVersion "xercesc_3_0"> <!-- C++ namespace name with Version -->
Modified: xerces/c/trunk/doc/xerces-c_book.xml
URL: http://svn.apache.org/viewvc/xerces/c/trunk/doc/xerces-c_book.xml?rev=697763&r1=697762&r2=697763&view=diff
==============================================================================
--- xerces/c/trunk/doc/xerces-c_book.xml (original)
+++ xerces/c/trunk/doc/xerces-c_book.xml Mon Sep 22 02:50:49 2008
@@ -25,9 +25,6 @@
<document id="index" label="Readme" source="readme.xml"/>
<document id="install-&XercesC3Series;" label="Installation" source="install.xml"/>
<document id="build-&XercesC3Series;" label="Build Instructions" source="build.xml"/>
- <hidden id="build-winunix-&XercesC3Series;" source="build-winunix.xml"/>
- <hidden id="build-other-&XercesC3Series;" source="build-other.xml"/>
- <hidden id="build-misc-&XercesC3Series;" source="build-misc.xml"/>
<separator-space/>
@@ -54,6 +51,7 @@
<hidden id="senumval-&XercesC3Series;" source="senumval.xml"/>
<hidden id="psviwriter-&XercesC3Series;" source="psviwriter.xml"/>
<hidden id="scmprint-&XercesC3Series;" source="scmprint.xml"/>
+ <hidden id="xinclude-&XercesC3Series;" source="xinclude.xml"/>
<group id="faqs-&XercesC3Series;" label="FAQs">
<entry id="faq-distrib-&XercesC3Series;" source="faq-distrib.xml"/>
Modified: xerces/c/trunk/doc/xinclude.xml
URL: http://svn.apache.org/viewvc/xerces/c/trunk/doc/xinclude.xml?rev=697763&r1=697762&r2=697763&view=diff
==============================================================================
--- xerces/c/trunk/doc/xinclude.xml (original)
+++ xerces/c/trunk/doc/xinclude.xml Mon Sep 22 02:50:49 2008
@@ -21,9 +21,9 @@
<s1 title="Sample: XInclude">
<s2 title="XInclude">
- <p>XInclude uses the provided DOM API to parse an XML file,
- constructs the DOM tree, expands the xi:include elements
- and writes the resulting tree to a file.</p>
+ <p>The XInclude example uses the provided DOM API to parse an XML file
+ while expanding the xi:include elements. It then writes
+ the resulting DOM tree in the expanded form.</p>
<s3 title="Running XInclude">
---------------------------------------------------------------------
To unsubscribe, e-mail: commits-unsubscribe@xerces.apache.org
For additional commands, e-mail: commits-help@xerces.apache.org