From 262ca7a67898f993a683f18773af5b8341087a16 Mon Sep 17 00:00:00 2001
From: Tinny Ng <tng@apache.org>
Date: Thu, 13 Jun 2002 18:10:34 +0000
Subject: [PATCH] Documentation update
git-svn-id: https://svn.apache.org/repos/asf/xerces/c/trunk@173835 13f79535-47bb-0310-9956-ffa450edef68
---
doc/apidocs.xml | 34 +++++++----
doc/dom3.xml | 74 ++++++++++++++++++++++++
doc/faq-parse.xml | 97 ++++++++++++++-----------------
doc/program-dom.xml | 8 +++
doc/program.xml | 1 +
doc/readme.xml | 131 ++++++++++++++++++++++++++----------------
doc/xerces-c_book.xml | 1 +
7 files changed, 232 insertions(+), 114 deletions(-)
create mode 100644 doc/dom3.xml
diff --git a/doc/apidocs.xml b/doc/apidocs.xml
index c99641943..0a9f97ef4 100644
--- a/doc/apidocs.xml
+++ b/doc/apidocs.xml
@@ -2,24 +2,34 @@
<!DOCTYPE s1 SYSTEM "sbk:/style/dtd/document.dtd">
<s1 title="API Documentation">
- <s2 title="API Docs for SAX and DOM">
+ <s2 title="API Docs for &XercesCName;">
<p>&XercesCName; is packaged with the API documentation for SAX and DOM, the two
most common programming interfaces for XML. The most common
framework classes have also been documented.</p>
- <p>&XercesCName; DOM is an implementation of the
- <jump href="http://www.w3.org/TR/REC-DOM-Level-1/">Document Object
- Model (Core) Level 1</jump> as defined in the W3C Recommendation of 1 October, 1998; and
- <jump href="http://www.w3.org/TR/DOM-Level-2-Core/">Document Object
- Model (Core) Level 2</jump> as defined in the W3C Recommendation of 13 November, 2000.
- For a complete understanding of how the &XercesCName; APIs work,
- we recommend you to read these documents.</p>
-
<p>&XercesCName; SAX is an implementation of the
- <jump href="http://sax.sourceforge.net/">SAX 1.0/2.0</jump> specification.
- You are encouraged to read this document for a better
- understanding of the SAX API in &XercesCName;.</p>
+ <jump href="http://sax.sourceforge.net/">SAX 1.0/2.0</jump> specification.</p>
+
+ <p>&XercesCName; DOM is an implementation of the</p>
+ <ul>
+ <li><jump href="http://www.w3.org/TR/1998/REC-DOM-Level-1-19981001/">
+ DOM Level 1 Specification</jump>, a W3C Recommendation of October 1, 1998</li>
+ <li><jump href="http://www.w3.org/TR/2000/REC-DOM-Level-2-Core-20001113/">
+ DOM Level 2 Core Specification</jump>, a W3C Recommendation of November 13, 2000</li>
+ <li><jump href="http://www.w3.org/TR/2000/REC-DOM-Level-2-Traversal-Range-20001113/">
+ DOM Level 2 Traversal and Range Specification</jump>, a W3C Recommendation of November 13, 2000</li>
+ <li>Contains a partial implementation of the
+ <jump href="http://www.w3.org/TR/2002/WD-DOM-Level-3-Core-20020409/">
+ DOM Level 3.0 Core Specification</jump>, and
+ <jump href="http://www.w3.org/TR/2002/WD-DOM-Level-3-ASLS-20020409/">
+ DOM Level 3.0 Load and Save Specification</jump> (W3C Working Draft of 09 April 2002).
+ This implementation is experimental.
+ See <jump href="dom3.html">DOM Level 3 Support</jump> for details.</li>
+ </ul>
+
+ <p>For a complete understanding of how the &XercesCName; APIs work,
+ we recommend you to read these documents.</p>
<p>See the <em><jump href="apiDocs/index.html">&XercesCName; API documentation.</jump></em> for more details.</p>
diff --git a/doc/dom3.xml b/doc/dom3.xml
new file mode 100644
index 000000000..9cfcfe046
--- /dev/null
+++ b/doc/dom3.xml
@@ -0,0 +1,74 @@
+<?xml version="1.0" standalone="no"?>
+<!DOCTYPE s1 SYSTEM "sbk:/style/dtd/document.dtd">
+
+<s1 title="DOM Level 3 Support">
+<s2 title="Disclaimer">
+ <p>
+ The &XercesCName; &XercesCVersion; contains a partial implementation of the W3C Document Object Model
+ Level 3. This implementation is experimental. The DOM Level 3 specification is
+ still in working draft stage: you should not consider this implementation complete or correct.</p>
+ <p>The limitations of this implementation are detailed below.
+ Please, read this document before using &XercesCName; &XercesCVersion;.
+ </p>
+</s2>
+<s2 title="Introduction">
+ <p>
+ The &XercesCName; &XercesCVersion; contains an experimental implementation of
+ a subset of the W3C DOM Level 3 as specified in </p>
+ <ul>
+ <li><jump href="http://www.w3.org/TR/2002/WD-DOM-Level-3-Core-20020409/">
+ DOM Level 3.0 Core Specification</jump>, a W3C Working Draft of 09 April 2002 and</li>
+ <li><jump href="http://www.w3.org/TR/2002/WD-DOM-Level-3-ASLS-20020409/">
+ DOM Level 3.0 Load and Save Specification</jump>, a W3C Working Draft of 09 April 2002.</li>
+ </ul>
+</s2>
+
+<s2 title='Implementation of DOM Level 3 Core'>
+<ul>
+ <li>
+ <code>DOMImplementationRegistry</code>, <code>DOMImplementationSource</code>
+ </li>
+
+ <li>
+ <code>DOMDocument</code>: set/getActualEncoding, set/getEncoding, set/getVersion, set/getStandalone, set/getDocumentURI.
+ </li>
+ <li>
+ <code>DOMEntity</code>: set/getActualEncoding, set/getEncoding, set/getVersion
+ </li>
+ <li>
+ <code>DOMErrorHandler</code>, <code>DOMError</code>, <code>DOMLocator</code>
+ </li>
+ <li>
+ <code>DOMNode</code>: set/getUserData
+ </li>
+ <li>
+ <code>DOMUserDataHandler</code>
+ </li>
+</ul>
+</s2>
+
+<s2 title='Implementation of DOM Level 3 Load and Save'>
+<ul>
+ <li>
+ <code>DOMImplementationLS</code>
+ </li>
+ <li>
+ <code>DOMBuilder</code>: does not provide implementation of parseWithContext() and <code>DOMBuilderFilter</code>.
+ </li>
+ <li>
+ <code>DOMEntityResolver</code>
+ </li>
+ <li>
+ <code>DOMInputSource</code>
+ </li>
+ <li>
+ <code>DOMWriter</code> and <code>DOMWriterFilter</code>
+ </li>
+</ul>
+
+</s2>
+<s2 title='Implementation of DOM Level 3 Abstract Schemas'>
+<p>Not Supported</p>
+</s2>
+
+</s1>
diff --git a/doc/faq-parse.xml b/doc/faq-parse.xml
index 05a9cb2a4..89a2f8af4 100644
--- a/doc/faq-parse.xml
+++ b/doc/faq-parse.xml
@@ -296,18 +296,28 @@ catch (const XMLException& toCatch) {
</a>
</faq>
- <faq title="Can I use Xerces to perform write validation">
+ <faq title="Can &XercesCName; create an XML skeleton based on a DTD">
- <q>Can I use Xerces to perform "write validation" (which is having an
- appropriate DTD and being able to add elements to the DOM whilst validating
- against the DTD)? Is there a function that I have totally missed that creates
+ <q>Is there a function that I have totally missed that creates
an XML file from a DTD, (obviously with the values missing, a skeleton, as it
- were.)</q>
+ were)?</q>
<a>
- <p>The answers are: "No" and "No." Write Validation is a commonly requested
- feature, but &XercesCName; does not have it yet.</p>
+ <p>No. This is not supported.</p>
+
+ </a>
+ </faq>
+
+ <faq title="Can I use &XercesCName; to perform write validation">
+
+ <q>Can I use &XercesCName; to perform "write validation" (which is having an
+ appropriate Grammar and being able to add elements to the DOM whilst validating
+ against the grammar)?</q>
+
+ <a>
+
+ <p>No. This is not supported.</p>
<p>The best you can do for now is to create the DOM document, write it back
as XML and re-parse it.</p>
@@ -322,60 +332,28 @@ catch (const XMLException& toCatch) {
<a>
- <p>No. This is a frequently requested feature, but at this time it is not
- possible to feed XML data from the DOM directly back to the DTD validator. The
- best option for now is to generate XML source from the DOM and feed that back
+ <p>No. The best option for now is to generate XML source from the DOM and feed that back
into the parser.</p>
</a>
</faq>
- <faq title="How to write out a DOM tree into an XML file?">
- <q>How to write out a DOM tree into an XML file?</q>
+ <faq title="How to write out a DOM tree into a string or an XML file?">
+ <q>How to write out a DOM tree into a string or an XML file?</q>
<a>
- <p>This feature is not yet available in the parser. Take a look at the DOMPrint sample
- for an example on parsing XML file, then writing it out back to the screen. You
- can use that code.</p>
+ <p>Please make sure you are using &XercesCName; &XercesCVersion; or up.</p>
+
+ <p>You can use
+ the DOMWriter::writeToString, or DOMWriter::writeNode to serialize a DOM tree.
+ Please refer to the sample DOMPrint or the API documentation for more details of
+ DOMWriter.</p>
</a>
</faq>
- <faq title="Why DOM_Node::cloneNode() does not clone the pointer assigned to a DOM_Node via DOM_Node::setUserData()?">
- <q>Why DOM_Node::cloneNode() does not clone the pointer assigned to a DOM_Node via DOM_Node::setUserData()?</q>
+ <faq title="Why DOMNode::cloneNode() does not clone the pointer assigned to a DOMNode via DOMNode::setUserData()?">
+ <q>Why DOMNode::cloneNode() does not clone the pointer assigned to a DOMNode via DOMNode::setUserData()?</q>
<a>
- <p>There are several possible options for how cloneNode should handle userData:
- </p>
- <ul>
- <li>
- 1) Copy the pointer. May be a Very Bad Idea if you really wanted the data
- associated with a particular node object.
- </li>
- <li>
- 2) Clone the object being pointed at. Maybe a Very Bad Idea if that object,
- in turn, wasn't designed to be cloned at this time.
- </li>
- <li>
- 3) A complex call-back API has been proposed which would allow the userData
- object to tell the DOM which of these three options should be taken, but
- that would require that only objects implementing that API be registered as
- userData. That doesn't seem to be a good option.
- </li>
- <li>
- 4) Do nothing. This is by far the lowest-overhead and safest choice. And
- since cloneNode is a DOM operation, and userData is _not_ defined by the
- standard DOM API, one can make a very strong case for this being the "most
- correct" option.
- </li>
- </ul>
- <p>
- We chose (4), very deliberately. If you want one of the others, you can
- implement it by creating your own wrapper operation for cloneNode() and
- calling that.
- </p>
- <p>
- NOTE that userData should be considered a non-portable, experimental feature
- of the Xerces DOM. It may evaporate entirely in favor of a scheme based on
- the DOM Level 3 "node key" mechanism, when that becomes officially
- available.
+ <p>&XercesCName; supports the DOMNode::userData specified in
</p>
</a>
</faq>
@@ -587,7 +565,7 @@ catch (const XMLException& toCatch) {
<faq title="Why does deleting a transcoded string result in assertion on windows?">
<q>Why does deleting a transcoded string result in assertion on windows?</q>
<a>
- <p>Both your application program and the Xerces DLL must use the same *DLL* version of the
+ <p>Both your application program and the &XercesCName; DLL must use the same *DLL* version of the
runtime library. If either statically links to the runtime library, the
problem will still occur.
@@ -605,7 +583,7 @@ catch (const XMLException& toCatch) {
code page. If this is not true, you must transcode the text yourself. You
can do this using local transcoding support on your OS, such as Iconv on
Unix or IBM's ICU package. However, if your transcoding needs are simple,
- you can achieve some better portability by using the Xerces parser's
+ you can achieve some better portability by using the &XercesCName; parser's
transcoder wrappers. You get a transcoder like this:
</p>
<ul>
@@ -720,7 +698,18 @@ catch (const XMLException& toCatch) {
validation is turned off.
</p>
- <p>To ignore the DTD, the only way to get around this is to install an EntityResolver
+ <p>To ignore the DTD, with &XercesCName; &XercesCVersion; or up, you can call
+ <code>setLoadExternalDTD(false)</code> (or
+ <code>setFeature(XMLUni::fgSAX2XercesLoadExternalDTD, false)</code>
+ to disable the loading of external DTD. The parser will then ignore
+ any external DTD completely if the validationScheme is set to Val_Never.
+ </p>
+
+ <p>Note: This flag is ignored if the validationScheme is set to Val_Always or Val_Auto.
+ </p>
+
+ <p>To ignore the DTD in earlier version of &XercesCName;, the
+ only way to get around this is to install an EntityResolver
(see the Redirect sample for an example of how this is done), and reset the
DTD file to "".
</p>
diff --git a/doc/program-dom.xml b/doc/program-dom.xml
index f18c5f53a..b161e6ee4 100644
--- a/doc/program-dom.xml
+++ b/doc/program-dom.xml
@@ -194,6 +194,14 @@ int main (int argc, char* args[]) {
</s3>
</s2>
+ <anchor name="DOM3"/>
+ <s2 title="DOM Level 3 Support in &XercesCName;">
+ <p>The &XercesCName; &XercesCVersion; contains a partial implementation of the W3C
+ Document Object Model Level 3. This implementation is experimental. See the document
+ <jump href="dom3.html"> DOM Level 3 Support</jump> for details.
+ </p>
+ </s2>
+
<anchor name="Deprecated"/>
<s2 title="Deprecated - Java-like DOM">
<p>Earlier, &XercesCName; has provided a set of C++ DOM interfaces that is
diff --git a/doc/program.xml b/doc/program.xml
index be8d3f107..7274ac096 100644
--- a/doc/program.xml
+++ b/doc/program.xml
@@ -12,6 +12,7 @@
<li><jump href="program-dom.html#Objectives">Design Objectives</jump></li>
<li><jump href="program-dom.html#ConstructXercesDOMParser">Constructing a XercesDOMParser</jump></li>
<li><jump href="program-dom.html#UsingDOMAPI">Using DOM API</jump></li>
+ <li><jump href="program-dom.html#DOM3">DOM Level 3 Support in &XercesCName; </jump></li>
<li><jump href="program-dom.html#Deprecated">Deprecated - Java-like DOM</jump></li>
</ul>
</s2>
diff --git a/doc/readme.xml b/doc/readme.xml
index 29e74074a..0c621546f 100644
--- a/doc/readme.xml
+++ b/doc/readme.xml
@@ -5,24 +5,17 @@
<s2 title="&XercesCName; Version &XercesCVersion;">
- <p>&XercesCName; is a validating XML parser written in a portable subset of C++.
- &XercesCName; makes it easy to give your application the ability to read and write
- <jump href="http://www.w3.org/XML/">XML</jump> data.
- A shared library is provided for parsing, generating, manipulating, and validating XML
- documents.
+ <p>&XercesCName; is a validating XML parser written in a portable subset of
+ C++. &XercesCName; makes it easy to give your application the ability to read and write
+ <jump href="http://www.w3.org/XML/">XML</jump> data. A shared
+ library is provided for parsing, generating, manipulating, and validating XML documents.
</p>
<p>&XercesCName; is faithful to the
<jump href="http://www.w3.org/TR/REC-xml">XML 1.0</jump> recommendation
- and associated standards (
- <jump href="http://www.w3.org/TR/REC-DOM-Level-1/">DOM 1.0</jump>,
- <jump href="http://www.w3.org/TR/DOM-Level-2-Core/">DOM 2.0</jump>.
- <jump href="http://sax.sourceforge.net/?selected=sax1">SAX 1.0</jump>,
- <jump href="http://sax.sourceforge.net/">SAX 2.0</jump>,
- <jump href="http://www.w3.org/TR/REC-xml-names/">Namespaces</jump>, and
- <jump href="http://www.w3.org/XML/Schema.html">W3C's XML Schema recommendation version 1.0</jump>.)
+ and many associated standards (see <link anchor="Features">Features</link> below).
</p>
- <p>The parser provides high performance, modularity, and scalability.
- Source code, samples and API documentation are provided with the parser. For
+ <p>The parser provides high performance, modularity, and scalability. Source
+ code, samples and API documentation are provided with the parser. For
portability, care has been taken to make minimal use of templates,
no RTTI, no C++ namespaces and minimal use of #ifdefs.</p>
@@ -42,16 +35,35 @@
</ul>
</s2>
+ <anchor name="Features"/>
<s2 title="Features">
<ul>
- <li>Conforms to <jump href="http://www.w3.org/TR/REC-xml">XML Spec 1.0</jump></li>
- <li>Tracking of latest
- <jump href="http://www.w3.org/TR/REC-DOM-Level-1/">DOM (Level 1.0)</jump>,
- <jump href="http://www.w3.org/TR/DOM-Level-2-Core/">DOM (Level 2.0)</jump>,
- <jump href="http://sax.sourceforge.net/">SAX/SAX2</jump>,
- <jump href="http://www.w3.org/TR/REC-xml-names/">Namespace</jump>, and
- <jump href="http://www.w3.org/XML/Schema.html">W3C's XML Schema recommendation version 1.0</jump>
- specifications.</li>
+ <li>Conforms to</li>
+ <ul>
+ <li><jump href="http://www.w3.org/TR/2000/REC-xml-20001006">
+ XML 1.0 (Second Edition)</jump>, W3C Recommendation of October 6, 2000</li>
+ <li><jump href="http://www.w3.org/TR/1998/REC-DOM-Level-1-19981001/">
+ DOM Level 1 Specification</jump>, W3C Recommendation of October 1, 1998</li>
+ <li><jump href="http://www.w3.org/TR/2000/REC-DOM-Level-2-Core-20001113/">
+ DOM Level 2 Core Specification</jump>, W3C Recommendation of November 13, 2000</li>
+ <li><jump href="http://www.w3.org/TR/2000/REC-DOM-Level-2-Traversal-Range-20001113/">
+ DOM Level 2 Traversal and Range Specification</jump>,
+ W3C Recommendation of November 13, 2000</li>
+ <li><jump href="http://sax.sourceforge.net/">SAX 1.0 and SAX 2.0</jump></li>
+ <li><jump href="http://www.w3.org/TR/1999/REC-xml-names-19990114/">
+ Namespaces in XML</jump>, W3C Recommendation of January 14, 1999</li>
+ <li><jump href="http://www.w3.org/TR/2001/REC-xmlschema-1-20010502/">
+ XML Schema Part 1: Structure</jump>, W3C Recommendation 2 May 2001</li>
+ <li><jump href="http://www.w3.org/TR/2001/REC-xmlschema-2-20010502/">
+ XML Schema Part 2: Datatypes</jump>, W3C Recommendation 2 May 2001</li>
+ </ul>
+ <li>Contains a partial implementation of the
+ <jump href="http://www.w3.org/TR/2002/WD-DOM-Level-3-Core-20020409/">
+ DOM Level 3.0 Core Specification</jump>, W3C Working Draft of 09 April 2002 and
+ <jump href="http://www.w3.org/TR/2002/WD-DOM-Level-3-ASLS-20020409/">
+ DOM Level 3.0 Load and Save Specification</jump>, W3C Working Draft of 09 April 2002.
+ This implementation is experimental.
+ See <jump href="dom3.html">DOM Level 3 Support</jump> for details.</li>
<li>Source code, samples, and documentation is provided.</li>
<li>Programmatic generation and validation of XML</li>
<li>Pluggable catalogs, validators and encodings</li>
@@ -61,34 +73,50 @@
</s2>
<s2 title="Platforms with Binaries">
- <ul>
- <li>Win32 using MSVC 6.0 SP3</li>
- <li>Linux (RedHat 7.2) using g++ 2.96</li>
- <li>Solaris 2.6 using Forte C++ Version 6 Update 2</li>
- <li>AIX 4.3 using xlC_r 5.0.2</li>
- <li>HP-UX 11 using aCC A.03.13 with pthreads</li>
- </ul>
- </s2>
-
- <s2 title="Digital Signatures">
- <p>The distributions of &XercesCName; Version &XercesCVersion; have been digitally signed
- (using GPG). There is an accompanyiny distribution.asc file in the same directory with each
- distribution. Here is the <jump href="http://xml.apache.org/xerces-c/keys/KEYS">KEYS file</jump>.
- </p>
- <p>Always test available signatures, e.g.</p>
- <source>
- pgpk -a KEYS
- pgpv &XercesCSrcInstallDir;.tar.gz.asc
- -- or --
- pgp -ka KEYS
- pgp &XercesCSrcInstallDir;.tar.gz.asc
- -- or --
- gpg --import KEYS
- gpg --verify &XercesCSrcInstallDir;.tar.gz.asc
- </source>
+ <table>
+ <tr>
+ <td><em>Operating System</em></td>
+ <td><em>Compiler</em></td>
+ </tr>
+ <tr>
+ <td><em>32-bit binary</em></td>
+ <td></td>
+ </tr>
+ <tr>
+ <td>Windows NT 4.0 SP5/2000</td>
+ <td>MSVC 6.0 SP3</td>
+ </tr>
+ <tr>
+ <td>Redhat Linux 7.2</td>
+ <td>g++ 3.1</td>
+ </tr>
+ <tr>
+ <td>AIX 4.3</td>
+ <td>xlC_r 5.0.2</td>
+ </tr>
+ <tr>
+ <td>Solaris 2.6</td>
+ <td>Forte C++ Version 6 Update 2</td>
+ </tr>
+ <tr>
+ <td>HP-UX 11.0</td>
+ <td>aCC A.03.13 with pthreads</td>
+ </tr>
+ <tr>
+ <td><em>64-bit binary</em></td>
+ <td></td>
+ </tr>
+ <tr>
+ <td>AIX 5.1</td>
+ <td>xlC_r 5.0.2</td>
+ </tr>
+ <tr>
+ <td>HP-UX 11.0</td>
+ <td>aCC A.03.13 with pthreads</td>
+ </tr>
+ </table>
</s2>
-
<s2 title="Other ports...">
<ul>
<li>OS/390</li>
@@ -103,4 +131,11 @@
</ul>
</s2>
+ <s2 title='License Information'>
+ <p>The &XercesCName; Version &XercesCVersion; is available in both source distribution and
+ binary distribution. Both &XercesCName; are made available under the
+ <jump href='http://xml.apache.org/LICENSE'>Apache Software License</jump>.
+ </p>
+ </s2>
+
</s1>
diff --git a/doc/xerces-c_book.xml b/doc/xerces-c_book.xml
index 68e800c8c..a402f732e 100644
--- a/doc/xerces-c_book.xml
+++ b/doc/xerces-c_book.xml
@@ -52,6 +52,7 @@
<hidden id="program-sax" source="program-sax.xml"/>
<hidden id="program-sax2" source="program-sax2.xml"/>
<hidden id="program-dom" source="program-dom.xml"/>
+ <hidden id="dom3" source="dom3.xml"/>
<hidden id="program-deprecateddom" source="program-deprecateddom.xml"/>
<hidden id="schema" source="schema.xml"/>
<hidden id="program-others" source="program-others.xml"/>
--
GitLab