From cebe1b463938f947cd04827155b2ccf43d18e15e Mon Sep 17 00:00:00 2001
From: David Abram Cargill <cargilld@apache.org>
Date: Tue, 21 Sep 2004 21:51:54 +0000
Subject: [PATCH] Documentation Updates.
git-svn-id: https://svn.apache.org/repos/asf/xerces/c/trunk@176060 13f79535-47bb-0310-9956-ffa450edef68
---
doc/bug-report.xml | 6 ++-
doc/faq-build.xml | 53 +++++-----------------
doc/faq-parse.xml | 3 +-
doc/migration_archive.xml | 8 ++--
doc/program-deprecateddom.xml | 8 ++++
doc/program-dom.xml | 25 ++++++++++-
doc/program-others.xml | 82 ++++++++++++++++++++++-------------
doc/program-sax.xml | 12 ++++-
doc/program-sax2.xml | 16 +++++--
doc/program.xml | 36 +++++++++++++++
doc/xerces-c_book.xml | 3 +-
11 files changed, 166 insertions(+), 86 deletions(-)
diff --git a/doc/bug-report.xml b/doc/bug-report.xml
index e1ebd647f..1750de2a1 100644
--- a/doc/bug-report.xml
+++ b/doc/bug-report.xml
@@ -74,6 +74,10 @@
are all necessary information to allow developer to reproduce,
identify, evaluate and eventually, fix the bug, which is the very
purpose of your reporting of the bug.
- </p>
+ </p>
+ <p>If you are providing a patch please review the information in
+ <jump href="faq-contributing.html#Submitting Patches">Submitting Patches</jump>.
+ </p>
+
</s2>
</s1>
diff --git a/doc/faq-build.xml b/doc/faq-build.xml
index 727fc4ede..5ad57b204 100644
--- a/doc/faq-build.xml
+++ b/doc/faq-build.xml
@@ -26,45 +26,17 @@
<a>
<p>&XercesCName; &XercesCVersion; now supports C++ Namespace.</p>
-
- <p>If C++ Namespace is ENABLED,
- users' applications must namespace qualified all the &XercesCName; classes/data/variables with
- <code>"&XercesCNamespace;::"</code> or add the <code>"using namespace &XercesCNamespace;;"</code>
- clause. Users also need to ensure all forward declarations are properly qualified or scope.
- For example
+
+ <p>If C++ Namespace is 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> clause.
+ Users also need to ensure all forward declarations are
+ properly qualified or scoped.
</p>
-
-<source>
-#include <stdio.h>
-#include <stdlib.h>
-#include <xercesc/sax/HandlerBase.hpp>
-
-// indicate using &XercesCName; namespace in general
-using namespace &XercesCNamespace;;
-
-// need to properly scope any forward declarations
-namespace &XercesCNamespace; {
-class AttributeList;
-}
-
-// or namespace qualifier the forward declarations
-class &XercesCNamespace;::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>See the Programming Guide <jump href="program-others.html#CPPNamespace">
- Using C++ Namespace</jump> for more details.
+ Using C++ Namespace</jump> for details.
</p>
</a>
@@ -160,10 +132,9 @@ public:
versions of <code>gmake</code> and <code>autoconf</code> are on your system.</li>
<li>If C++ Namespace support is ENABLED (all the binary distributions of &XercesCName;
&XercesCVersion; are built with C++ Namespace enabled), users' applications
- must namespace qualified all the &XercesCName; classes/data/variables with
- <code>"&XercesCNamespace;::"</code> or add the <code>"using namespace &XercesCNamespace;"</code>
- clause. See the Programming Guide <jump href="program-others.html#CPPNamespace">
- Using C++ Namespace</jump> for more details.</li>
+ must namespace qualify all the &XercesCName; classes, data and variables.
+ See the Programming Guide <jump href="program-others.html#CPPNamespace">
+ Using C++ Namespace</jump> for details.</li>
</ol>
</a>
</faq>
diff --git a/doc/faq-parse.xml b/doc/faq-parse.xml
index 3c601914d..d437466a1 100644
--- a/doc/faq-parse.xml
+++ b/doc/faq-parse.xml
@@ -749,7 +749,8 @@ void myParsingFunction()
<source>
// create an XMLTranscoder that is able to transcode between Unicode and Big5
// ASSUMPTION: assumes your underlying transcoding utility supports this encoding Big5
-XMLTranscoder* t = XMLPlatformUtils::fgTransService->makeNewTranscoderFor("Big5", failReason, 16*1024);
+XMLTranscoder* t =
+ XMLPlatformUtils::fgTransService->makeNewTranscoderFor("Big5", failReason, 16*1024, MemoryManager);
// source string is in Unicode, wanna to transcode to Big5
t->transcodeTo(source_unicode, length, result_Big5, length, charsEaten, XMLTranscoder::UnRep_Throw );
diff --git a/doc/migration_archive.xml b/doc/migration_archive.xml
index ee40961cc..6d6f0e834 100644
--- a/doc/migration_archive.xml
+++ b/doc/migration_archive.xml
@@ -220,17 +220,15 @@
<anchor name="CPPNamespace220"/>
<s3 title="Using C++ Namespace">
<p>&XercesCName; 2.2.0 now supports C++ Namespace. All &XercesCName;
- classes/data/variables are defined in the <code>"namespace &XercesCNamespace;"</code>
+ classes, data and variables are defined in the &XercesCNamespace; namespace
if C++ Namespace support is ENABLED.</p>
<p>All the binary distributions of &XercesCName; 2.2.0 are now built with
C++ Namespace enabled. Therefore users' applications that links with the distributed
- binary packages must namespace qualified all the &XercesCName; classes/data/variables
- with <code>"&XercesCNamespace;::"</code> or add the
- <code>"using namespace &XercesCNamespace;"</code> clause.</p>
+ binary packages must namespace qualify all the &XercesCName; classes, data and variables.</p>
<p>See the Programming Guide <jump href="program-others.html#CPPNamespace">Using C++ Namespace</jump>
- for more details.</p>
+ for details.</p>
</s3>
diff --git a/doc/program-deprecateddom.xml b/doc/program-deprecateddom.xml
index 930c2052d..ad2d181be 100644
--- a/doc/program-deprecateddom.xml
+++ b/doc/program-deprecateddom.xml
@@ -289,6 +289,14 @@
#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
+
int main (int argc, char* args[]) {
try {
diff --git a/doc/program-dom.xml b/doc/program-dom.xml
index c4b9249af..fa6e0f4f9 100644
--- a/doc/program-dom.xml
+++ b/doc/program-dom.xml
@@ -287,6 +287,14 @@
#include <xercesc/util/XMLString.hpp>
#include <xercesc/util/PlatformUtils.hpp>
+ #if defined(XERCES_NEW_IOSTREAMS)
+ #include <iostream>
+ #else
+ #include <iostream.h>
+ #endif
+
+ XERCES_CPP_NAMESPACE_USE
+
int main (int argc, char* args[]) {
try {
@@ -713,6 +721,14 @@
#include <xercesc/util/XMLString.hpp>
#include <xercesc/util/PlatformUtils.hpp>
+ #if defined(XERCES_NEW_IOSTREAMS)
+ #include <iostream>
+ #else
+ #include <iostream.h>
+ #endif
+
+ XERCES_CPP_NAMESPACE_USE
+
int main (int argc, char* args[]) {
try {
@@ -1367,7 +1383,14 @@
#include <xercesc/dom/DOM.hpp>
#include <xercesc/util/XMLString.hpp>
#include <xercesc/util/PlatformUtils.hpp>
-
+
+ #if defined(XERCES_NEW_IOSTREAMS)
+ #include <iostream>
+ #else
+ #include <iostream.h>
+ #endif
+
+ XERCES_CPP_NAMESPACE_USE
int serializeDOM(DOMNode* node) {
XMLCh tempStr[100];
diff --git a/doc/program-others.xml b/doc/program-others.xml
index 1e8da95dd..7b0e96b62 100644
--- a/doc/program-others.xml
+++ b/doc/program-others.xml
@@ -93,7 +93,7 @@ while (gotMore && !handler.getDone())
gotMore = parser.parseNext(token);</source>
<p>In this case, our event handler object (named 'handler'
- surprisingly enough) is watching form some criteria and will
+ surprisingly enough) is watching for some criteria and will
return a status from its getDone() 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
@@ -387,7 +387,7 @@ parser->parse(xmlFile2);
<anchor name="CPPNamespace"/>
<s2 title="Using C++ Namespace">
- <p>&XercesCName; &XercesCVersion; supports C++ Namespace.</p>
+ <p>&XercesCName; &XercesCVersion; 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>
@@ -402,13 +402,31 @@ parser->parse(xmlFile2);
#define XERCES_HAS_CPP_NAMESPACE
</source>
- <p>If C++ Namespace support is ENABLED (all the binary distributions of &XercesCName;
- &XercesCVersion; are built with C++ Namespace enabled),
- users' applications must namespace qualified all the &XercesCName; classes/data/variables with
- <code>"&XercesCNamespace;::"</code> or add the <code>"using namespace &XercesCNamespace;"</code>
- clause. Users also need to ensure all forward declarations are properly qualified or scope.
- For example
- </p>
+ <p>If C++ Namespace support is ENABLED (all the binary
+ distributions of &XercesCName; &XercesCVersion; 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>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>
@@ -416,15 +434,16 @@ parser->parse(xmlFile2);
#include <xercesc/sax/HandlerBase.hpp>
// indicate using &XercesCName; namespace in general
-using namespace &XercesCNamespace;;
+XERCES_CPP_NAMESPACE_USE
// need to properly scope any forward declarations
-namespace &XercesCNamespace; {
-class AttributeList;
-}
+XERCES_CPP_NAMESPACE_BEGIN
+ class AttributeList;
+XERCES_CPP_NAMESPACE_END
+
// or namespace qualifier the forward declarations
-class &XercesCNamespace;::ErrorHandler;
+class XERCES_CPP_NAMESPACE_QUALIFIER ErrorHandler;
class MySAXHandlers : public HandlerBase
{
@@ -439,7 +458,7 @@ public:
};
</source>
- <p>Header <code>"xercesc/util/XercesDefs.hpp"</code> has defined the following macros</p>
+ <p>All macros used above are defined in header file <code>xercesc/util/XercesDefs.hpp</code>:</p>
<source>
#if defined(XERCES_HAS_CPP_NAMESPACE)
@@ -458,7 +477,7 @@ public:
#endif
</source>
- <p>Users can also make use of these pre-defined macro in their applications. For example:</p>
+ <p>Users should make use of these pre-defined macro in their applications. For example:</p>
<source>
#include <stdio.h>
#include <stdlib.h>
@@ -472,7 +491,7 @@ XERCES_CPP_NAMESPACE_BEGIN
class AttributeList;
XERCES_CPP_NAMESPACE_END
-// or namespace qualifier the forward declarations
+// or namespace qualify the forward declarations
class XERCES_CPP_NAMESPACE_QUALIFIER ErrorHandler;
class MySAXHandlers : public HandlerBase
@@ -488,11 +507,9 @@ public:
};
</source>
- <p>NOTE: <code>"namespace &XercesCNamespace;"</code> and <code>"namespace &XercesCNSVersion;"</code>
- are equivalent in this release.</p>
-
<p>For those users who want to selectively pick which version of API to use, they can do
- something like this:</p>
+ 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
@@ -508,20 +525,25 @@ public:
</source>
<p>But for those who just want to call the latest API, then they should use
- <code>&XercesCNamespace;::</code> or the macro <code>XERCES_CPP_NAMESPACE_QUALIFIER</code>
+ the macro <code>XERCES_CPP_NAMESPACE_QUALIFIER</code>
for source compatibility:</p>
<source>
-//use the current namespace, &XercesCNamespace;
-new &XercesCNamespace;::SAXParser();
-
-//or use the macro
new XERCES_CPP_NAMESPACE_QUALIFIER SAXParser();
</source>
-
- <p><code>&XercesCNamespace;</code> is 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.</p>
+
+ <p>Header file <code>xercesc/util/XercesDefs.hpp</code> also
+ declares <code>namespace &XercesCNamespace;</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>&XercesCNamespace;::</code> instead of
+ <code>XERCES_CPP_NAMESPACE_QUALIFIER </code> when your
+ compiler does not support namespaces, your code will not
+ work.</p>
+
+
</s2>
diff --git a/doc/program-sax.xml b/doc/program-sax.xml
index b2a7053a4..4ecf99c6f 100644
--- a/doc/program-sax.xml
+++ b/doc/program-sax.xml
@@ -68,7 +68,7 @@ MySAXHandler::MySAXHandler()
{
}
-MySAXHandler::startElement(const XMLCh* const name,
+void MySAXHandler::startElement(const XMLCh* const name,
AttributeList& attributes)
{
char* message = XMLString::transcode(name);
@@ -76,7 +76,7 @@ MySAXHandler::startElement(const XMLCh* const name,
XMLString::release(&message);
}
-MySAXHandler::fatalError(const SAXParseException& exception)
+void MySAXHandler::fatalError(const SAXParseException& exception)
{
char* message = XMLString::transcode(exception.getMessage());
cout << "Fatal Error: " << message
@@ -106,6 +106,14 @@ MySAXHandler::fatalError(const SAXParseException& exception)
#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
+
int main (int argc, char* args[]) {
try {
diff --git a/doc/program-sax2.xml b/doc/program-sax2.xml
index 8f2d6530d..0fd0152d5 100644
--- a/doc/program-sax2.xml
+++ b/doc/program-sax2.xml
@@ -73,17 +73,17 @@ MySAX2Handler::MySAX2Handler()
{
}
-MySAX2Handler::startElement(const XMLCh* const uri,
+void MySAX2Handler::startElement(const XMLCh* const uri,
const XMLCh* const localname,
const XMLCh* const qname,
const Attributes& attrs)
{
- char* message = XMLString::transcode(name);
+ char* message = XMLString::transcode(localname);
cout << "I saw element: "<< message << endl;
XMLString::release(&message);
}
-MySAX2Handler::fatalError(const SAXParseException& exception)
+void MySAX2Handler::fatalError(const SAXParseException& exception)
{
char* message = XMLString::transcode(exception.getMessage());
cout << "Fatal Error: " << message
@@ -114,6 +114,14 @@ MySAX2Handler::fatalError(const SAXParseException& exception)
#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
+
int main (int argc, char* args[]) {
try {
@@ -121,7 +129,7 @@ MySAX2Handler::fatalError(const SAXParseException& exception)
}
catch (const XMLException& toCatch) {
char* message = XMLString::transcode(toCatch.getMessage());
- cout << "Error during initialization! :\n"
+ cout << "Error during initialization! :\n";
cout << "Exception message is: \n"
<< message << "\n";
XMLString::release(&message);
diff --git a/doc/program.xml b/doc/program.xml
index d545637f4..920726338 100644
--- a/doc/program.xml
+++ b/doc/program.xml
@@ -19,6 +19,42 @@
<s1 title="Programming Guide">
+ <p>Independent of the API you want to use, DOM, SAX, or SAX2, your
+ application must initialize the &XercesCProjectName; system
+ before using the API, and terminate it after you are done. This
+ is achieved by the following code:</p>
+<source>
+int main(int argc, char* argv[])
+{
+ #include <xercesc/util/PlatformUtils.hpp>
+ // Other include files, declarations, and non-&XercesCName; initializations.
+
+ try {
+ XMLPlatformUtils::Initialize();
+ }
+ catch (const XMLException& toCatch) {
+ // Do your failure processing here
+ return 1;
+ }
+
+ // Do your actual work with &XercesCName; here.
+
+ XMLPlatformUtils::Terminate();
+
+ // Other terminations and cleanup.
+ return 0;
+}</source>
+
+
+<p><code>XMLPlatformUtils::Initialize()</code> and
+ <code>XMLPlatformUtils::Terminate</code> must be called at
+ least once in each process. You are allowed to call
+ <code>XMLPlatformUtils::Initialize()</code> and
+ <code>XMLPlatformUtils::Terminate</code> multiple times, but
+ each call to <code>XMLPlatformUtils::Initialize()</code> must
+ be matched with a call to
+ <code>XMLPlatformUtils::Terminate</code>.</p>
+
<s2 title="DOM Programming Guide">
<p>The DOM API is based on the
<jump href="ApacheDOMC++Binding.html">Apache Recommended DOM C++ binding</jump>.</p>
diff --git a/doc/xerces-c_book.xml b/doc/xerces-c_book.xml
index 94c26a313..4a015b950 100644
--- a/doc/xerces-c_book.xml
+++ b/doc/xerces-c_book.xml
@@ -43,6 +43,7 @@
<entry id="faq-build" source="faq-build.xml"/>
<entry id="faq-parse" source="faq-parse.xml"/>
<entry id="faq-other" source="faq-other.xml"/>
+ <entry id="faq-contributing" source="faq-contributing.xml"/>
</group>
<document id="samples" label="Samples" source="samples.xml"/>
@@ -79,7 +80,7 @@
<document id="migrate" label="Migration Guide" source="migration.xml"/>
<hidden id="migrate_archive" source="migration_archive.xml"/>
-
+
<separator/>
<document id="feedback" label="Feedback" source="feedback.xml"/>
--
GitLab