cargilld 2004/09/21 14:51:54
Modified: c/doc bug-report.xml program-deprecateddom.xml
migration_archive.xml program-sax.xml faq-build.xml
program-others.xml program-sax2.xml
xerces-c_book.xml program.xml program-dom.xml
faq-parse.xml
Log:
Documentation Updates.
Revision Changes Path
1.12 +5 -1 xml-xerces/c/doc/bug-report.xml
Index: bug-report.xml
===================================================================
RCS file: /home/cvs/xml-xerces/c/doc/bug-report.xml,v
retrieving revision 1.11
retrieving revision 1.12
diff -u -r1.11 -r1.12
--- bug-report.xml 8 Sep 2004 18:55:00 -0000 1.11
+++ bug-report.xml 21 Sep 2004 21:51:54 -0000 1.12
@@ -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>
1.13 +8 -0 xml-xerces/c/doc/program-deprecateddom.xml
Index: program-deprecateddom.xml
===================================================================
RCS file: /home/cvs/xml-xerces/c/doc/program-deprecateddom.xml,v
retrieving revision 1.12
retrieving revision 1.13
diff -u -r1.12 -r1.13
--- program-deprecateddom.xml 8 Sep 2004 18:55:00 -0000 1.12
+++ program-deprecateddom.xml 21 Sep 2004 21:51:54 -0000 1.13
@@ -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 {
1.16 +3 -5 xml-xerces/c/doc/migration_archive.xml
Index: migration_archive.xml
===================================================================
RCS file: /home/cvs/xml-xerces/c/doc/migration_archive.xml,v
retrieving revision 1.15
retrieving revision 1.16
diff -u -r1.15 -r1.16
--- migration_archive.xml 8 Sep 2004 18:55:00 -0000 1.15
+++ migration_archive.xml 21 Sep 2004 21:51:54 -0000 1.16
@@ -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>
1.17 +10 -2 xml-xerces/c/doc/program-sax.xml
Index: program-sax.xml
===================================================================
RCS file: /home/cvs/xml-xerces/c/doc/program-sax.xml,v
retrieving revision 1.16
retrieving revision 1.17
diff -u -r1.16 -r1.17
--- program-sax.xml 8 Sep 2004 18:55:00 -0000 1.16
+++ program-sax.xml 21 Sep 2004 21:51:54 -0000 1.17
@@ -68,7 +68,7 @@
{
}
-MySAXHandler::startElement(const XMLCh* const name,
+void MySAXHandler::startElement(const XMLCh* const name,
AttributeList& attributes)
{
char* message = XMLString::transcode(name);
@@ -76,7 +76,7 @@
XMLString::release(&message);
}
-MySAXHandler::fatalError(const SAXParseException& exception)
+void MySAXHandler::fatalError(const SAXParseException& exception)
{
char* message = XMLString::transcode(exception.getMessage());
cout << "Fatal Error: " << message
@@ -105,6 +105,14 @@
#include <xercesc/parsers/SAXParser.hpp>
#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[]) {
1.21 +12 -41 xml-xerces/c/doc/faq-build.xml
Index: faq-build.xml
===================================================================
RCS file: /home/cvs/xml-xerces/c/doc/faq-build.xml,v
retrieving revision 1.20
retrieving revision 1.21
diff -u -r1.20 -r1.21
--- faq-build.xml 8 Sep 2004 18:55:00 -0000 1.20
+++ faq-build.xml 21 Sep 2004 21:51:54 -0000 1.21
@@ -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 @@
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>
1.22 +52 -30 xml-xerces/c/doc/program-others.xml
Index: program-others.xml
===================================================================
RCS file: /home/cvs/xml-xerces/c/doc/program-others.xml,v
retrieving revision 1.21
retrieving revision 1.22
diff -u -r1.21 -r1.22
--- program-others.xml 8 Sep 2004 18:55:00 -0000 1.21
+++ program-others.xml 21 Sep 2004 21:51:54 -0000 1.22
@@ -93,7 +93,7 @@
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 @@
<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 @@
#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 @@
#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 @@
};
</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 @@
#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 @@
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 @@
};
</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 @@
</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>
1.23 +12 -4 xml-xerces/c/doc/program-sax2.xml
Index: program-sax2.xml
===================================================================
RCS file: /home/cvs/xml-xerces/c/doc/program-sax2.xml,v
retrieving revision 1.22
retrieving revision 1.23
diff -u -r1.22 -r1.23
--- program-sax2.xml 8 Sep 2004 18:55:00 -0000 1.22
+++ program-sax2.xml 21 Sep 2004 21:51:54 -0000 1.23
@@ -73,17 +73,17 @@
{
}
-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 @@
#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 @@
}
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);
1.32 +2 -1 xml-xerces/c/doc/xerces-c_book.xml
Index: xerces-c_book.xml
===================================================================
RCS file: /home/cvs/xml-xerces/c/doc/xerces-c_book.xml,v
retrieving revision 1.31
retrieving revision 1.32
diff -u -r1.31 -r1.32
--- xerces-c_book.xml 8 Sep 2004 18:54:59 -0000 1.31
+++ xerces-c_book.xml 21 Sep 2004 21:51:54 -0000 1.32
@@ -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"/>
1.39 +36 -0 xml-xerces/c/doc/program.xml
Index: program.xml
===================================================================
RCS file: /home/cvs/xml-xerces/c/doc/program.xml,v
retrieving revision 1.38
retrieving revision 1.39
diff -u -r1.38 -r1.39
--- program.xml 8 Sep 2004 18:55:00 -0000 1.38
+++ program.xml 21 Sep 2004 21:51:54 -0000 1.39
@@ -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>
1.41 +23 -0 xml-xerces/c/doc/program-dom.xml
Index: program-dom.xml
===================================================================
RCS file: /home/cvs/xml-xerces/c/doc/program-dom.xml,v
retrieving revision 1.40
retrieving revision 1.41
diff -u -r1.40 -r1.41
--- program-dom.xml 8 Sep 2004 18:55:00 -0000 1.40
+++ program-dom.xml 21 Sep 2004 21:51:54 -0000 1.41
@@ -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];
1.64 +2 -1 xml-xerces/c/doc/faq-parse.xml
Index: faq-parse.xml
===================================================================
RCS file: /home/cvs/xml-xerces/c/doc/faq-parse.xml,v
retrieving revision 1.63
retrieving revision 1.64
diff -u -r1.63 -r1.64
--- faq-parse.xml 8 Sep 2004 18:55:00 -0000 1.63
+++ faq-parse.xml 21 Sep 2004 21:51:54 -0000 1.64
@@ -749,7 +749,8 @@
<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 );
---------------------------------------------------------------------
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
