knoaman 2003/01/06 13:19:42
Modified: c/doc program.xml program-sax2.xml program-sax.xml
program-others.xml program-dom.xml
program-deprecateddom.xml migration.xml
Log:
Documentation update.
Revision Changes Path
1.34 +1 -0 xml-xerces/c/doc/program.xml
Index: program.xml
===================================================================
RCS file: /home/cvs/xml-xerces/c/doc/program.xml,v
retrieving revision 1.33
retrieving revision 1.34
diff -u -r1.33 -r1.34
--- program.xml 22 Nov 2002 21:34:29 -0000 1.33
+++ program.xml 6 Jan 2003 21:19:41 -0000 1.34
@@ -81,6 +81,7 @@
<li><jump href="program-others.html#PortingGuidelines">Porting
Guidelines</jump></li>
<li><jump href="program-others.html#CPPNamespace">Using C++
Namespace</jump></li>
<li><jump href="program-others.html#SpecifylocaleforMessageLoader">Specify
locale for Message Loader</jump></li>
+ <li><jump href="program-others.html#UseSpecificScanner">Use Specific
Scanner</jump></li>
</ul>
</s2>
1.16 +33 -0 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.15
retrieving revision 1.16
diff -u -r1.15 -r1.16
--- program-sax2.xml 3 Jan 2003 20:10:29 -0000 1.15
+++ program-sax2.xml 6 Jan 2003 21:19:42 -0000 1.16
@@ -340,6 +340,18 @@
</table>
<p/>
+ <anchor name="CalculateSrcOffset"/>
+ <table>
+ <tr><th
colspan="2"><em>http://apache.org/xml/features/calculate-src-ofs</em></th></tr>
+ <tr><th><em>true:</em></th><td> Enable src offset calculation.
</td></tr>
+ <tr><th><em>false:</em></th><td> Disable src offset calculation.
</td></tr>
+ <tr><th><em>default:</em></th><td> false </td></tr>
+ <tr><th><em>note:</em></th><td> If set to true, the user can
inquire about
+ the current src offset within the input source. Setting it to false
(default)
+ improves the performance.</td></tr>
+ </table>
+ <p/>
+
</s4>
</s3>
@@ -397,6 +409,27 @@
attribute that may occur in an instance document:
e.g."file_name.xsd". </td></tr>
<tr><th><em>Value Type</em></th><td> XMLCh* </td></tr>
</table>
+ <p/>
+
+ <table>
+ <tr><th
colspan="2"><em>http://apache.org/xml/properties/scannerName</em></th></tr>
+ <tr><th><em>Description</em></th><td> This property allows the user
to specify the name of
+ the XMLScanner to use for scanning XML documents. If
not specified, the default
+ scanner "IGXMLScanner" is used.</td></tr>
+ <tr><th><em>Value</em></th><td> The recognized scanner names are:
<br/>
+ 1."WFXMLScanner" - scanner that performs
well-formedness checking only.<br/>
+ 2. "DGXMLScanner" - scanner that handles XML documents
with DTD grammar information.<br/>
+ 3. "SGXMLScanner" - scanner that handles XML documents
with XML schema grammar information.<br/>
+ 4. "IGXMLScanner" - scanner that handles XML documents
with DTD or/and XML schema grammar information.<br/>
+ Users can use the predefined constants defined in
XMLUni directly or a string that matches the value of
+ one of those constants.</td></tr>
+ <tr><th><em>Value Type</em></th><td> XMLCh* </td></tr>
+ <tr><th><em>note: </em></th><td> See <jump
href="program-others.html#UseSpecificScanner">Use Specific Scanner</jump>
+ for more programming details. </td></tr>
+ </table>
+
+ <p/>
+
</s4>
</s3>
</s2>
1.11 +31 -0 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.10
retrieving revision 1.11
diff -u -r1.10 -r1.11
--- program-sax.xml 3 Jan 2003 20:10:29 -0000 1.10
+++ program-sax.xml 6 Jan 2003 21:19:42 -0000 1.11
@@ -325,6 +325,18 @@
</table>
<p/>
+ <anchor name="CalculateSrcOffset"/>
+ <table>
+ <tr><th colspan="2"><em>void setCalculateSrcOfs(const
bool)</em></th></tr>
+ <tr><th><em>true:</em></th><td> Enable src offset calculation.
</td></tr>
+ <tr><th><em>false:</em></th><td> Disable src offset calculation.
</td></tr>
+ <tr><th><em>default:</em></th><td> false </td></tr>
+ <tr><th><em>note:</em></th><td> If set to true, the user can
inquire about
+ the current src offset within the input source. Setting it to false
(default)
+ improves the performance.</td></tr>
+ </table>
+ <p/>
+
<table>
<tr><th colspan="2"><em>void setExternalSchemaLocation(const XMLCh*
const)</em></th></tr>
<tr><th><em>Description</em></th><td> The XML Schema Recommendation
explicitly states that
@@ -357,6 +369,25 @@
<tr><th><em>Value</em></th><td> The syntax is the same as for the
noNamespaceSchemaLocation
attribute that may occur in an instance document:
e.g."file_name.xsd". </td></tr>
<tr><th><em>Value Type</em></th><td> XMLCh* </td></tr>
+ </table>
+
+ <p/>
+
+ <table>
+ <tr><th colspan="2"><em>void useScanner(const XMLCh*
const)</em></th></tr>
+ <tr><th><em>Description</em></th><td> This property allows the user
to specify the name of
+ the XMLScanner to use for scanning XML documents. If
not specified, the default
+ scanner "IGXMLScanner" is used.</td></tr>
+ <tr><th><em>Value</em></th><td> The recognized scanner names are:
<br/>
+ 1."WFXMLScanner" - scanner that performs
well-formedness checking only.<br/>
+ 2. "DGXMLScanner" - scanner that handles XML documents
with DTD grammar information.<br/>
+ 3. "SGXMLScanner" - scanner that handles XML documents
with XML schema grammar information.<br/>
+ 4. "IGXMLScanner" - scanner that handles XML documents
with DTD or/and XML schema grammar information.<br/>
+ Users can use the predefined constants defined in
XMLUni directly or a string that matches the value of
+ one of those constants.</td></tr>
+ <tr><th><em>Value Type</em></th><td> XMLCh* </td></tr>
+ <tr><th><em>note: </em></th><td> See <jump
href="program-others.html#UseSpecificScanner">Use Specific Scanner</jump>
+ for more programming details. </td></tr>
</table>
<p/>
1.10 +103 -0 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.9
retrieving revision 1.10
diff -u -r1.9 -r1.10
--- program-others.xml 22 Nov 2002 21:34:29 -0000 1.9
+++ program-others.xml 6 Jan 2003 21:19:42 -0000 1.10
@@ -474,5 +474,108 @@
}
..
</source>
+
+<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>&XercesCName; supports the following scanners:</p>
+
+ <s3 title="WFXMLScanner">
+
+ <p>
+ The WFXMLScanner is a non-validating scanner which performs
well-formedness check only.
+ It does not do any DTD/XMLSchema processing. If the XML document
contains a DOCTYPE, it
+ will be silently ignored (i.e. no warning message is issued).
Similiarly, any schema
+ specific attributes (e.g. schemaLocation), will be treated as normal
element attributes.
+ Setting grammar specific features/properties will have no effect on its
behavior
+ (e.g. setLoadExternalDTD(true) is ignored).
+ </p>
+
+<source>
+// Create a DOM parser
+XercesDOMParser parser;
+
+// Specify scanner name
+parser.useScanner(XMLUni::fgWFScanner);
+
+// Specify other parser features, e.g.
+parser.setDoNamespaces(true);
+</source>
+
+
+ </s3>
+
+ <s3 title="DGXMLScanner">
+
+ <p>
+ The DGXMLScanner handles XML documents with DOCTYPE information. It
does not do any
+ XMLSchema processing, which means that any schema specific attributes
(e.g. schemaLocation),
+ will be treated as normal element attributes. Setting schema grammar
specific features/properties
+ will have no effect on its behavior (e.g. setDoSchema(true) is
ignored).
+ </p>
+
+<source>
+// Create a SAX parser
+SAXParser parser;
+
+// Specify scanner name
+parser.useScanner(XMLUni::fgDGScanner);
+
+// Specify other parser features, e.g.
+parser.setLoadExternalDTD(true);
+</source>
+
+ </s3>
+
+ <s3 title="SGXMLScanner">
+
+ <p>
+ The SGXMLScanner handles XML documents with XML schema grammar
information.
+ If the XML document contains a DOCTYPE, it will be ignored. Namespace
and
+ schema processing features are on by default, and setting them to off
has
+ not effect.
+ </p>
+
+<source>
+// Create a SAX2 parser
+SAX2XMLReader* parser = XMLReaderFactory::createXMLReader();
+
+// Specify scanner name
+parser->setProperty(XMLUni::fgXercesScannerName, XMLUni::fgSGScanner);
+
+// Specify other parser features, e.g.
+parser->setFeature(XMLUni::fgXercesSchemaFullChecking, false);
+</source>
+
+ </s3>
+
+ <s3 title="IGXMLScanner">
+
+ <p>
+ The IGXMLScanner is an integrated scanner and handles XML documents
with DTD and/or
+ XML schema grammar. This is the default scanner used by the various
parsers if no
+ scanner is specified.
+ </p>
+
+<source>
+// Create a DOMBuilder parser
+DOMBuilder *parser =
((DOMImplementationLS*)impl)->createDOMBuilder(DOMImplementationLS::MODE_SYNCHRONOUS,
0);
+
+// Specify scanner name - This is optional as IGXMLScanner is the default
+parser->setProperty(XMLUni::fgXercesScannerName, XMLUni::fgIGScanner);
+
+// Specify other parser features, e.g.
+parser->setFeature(XMLUni::fgDOMNamespaces, doNamespaces);
+parser->setFeature(XMLUni::fgXercesSchema, doSchema);
+</source>
+
+ </s3>
+
+ </s2>
</s1>
1.24 +63 -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.23
retrieving revision 1.24
diff -u -r1.23 -r1.24
--- program-dom.xml 3 Jan 2003 20:10:29 -0000 1.23
+++ program-dom.xml 6 Jan 2003 21:19:42 -0000 1.24
@@ -548,6 +548,18 @@
</table>
<p/>
+ <anchor name="CalculateSrcOffset"/>
+ <table>
+ <tr><th colspan="2"><em>void setCalculateSrcOfs(const
bool)</em></th></tr>
+ <tr><th><em>true:</em></th><td> Enable src offset calculation.
</td></tr>
+ <tr><th><em>false:</em></th><td> Disable src offset calculation.
</td></tr>
+ <tr><th><em>default:</em></th><td> false </td></tr>
+ <tr><th><em>note:</em></th><td> If set to true, the user can
inquire about
+ the current src offset within the input source. Setting it to false
(default)
+ improves the performance.</td></tr>
+ </table>
+ <p/>
+
</s3>
<anchor name="XercesDOMProperties"/>
@@ -594,6 +606,25 @@
<p/>
+ <table>
+ <tr><th colspan="2"><em>void useScanner(const XMLCh*
const)</em></th></tr>
+ <tr><th><em>Description</em></th><td> This property allows the user
to specify the name of
+ the XMLScanner to use for scanning XML documents. If
not specified, the default
+ scanner "IGXMLScanner" is used.</td></tr>
+ <tr><th><em>Value</em></th><td> The recognized scanner names are:
<br/>
+ 1."WFXMLScanner" - scanner that performs
well-formedness checking only.<br/>
+ 2. "DGXMLScanner" - scanner that handles XML documents
with DTD grammar information.<br/>
+ 3. "SGXMLScanner" - scanner that handles XML documents
with XML schema grammar information.<br/>
+ 4. "IGXMLScanner" - scanner that handles XML documents
with DTD or/and XML schema grammar information.<br/>
+ Users can use the predefined constants defined in
XMLUni directly or a string that matches the value of
+ one of those constants.</td></tr>
+ <tr><th><em>Value Type</em></th><td> XMLCh* </td></tr>
+ <tr><th><em>note: </em></th><td> See <jump
href="program-others.html#UseSpecificScanner">Use Specific Scanner</jump>
+ for more programming details. </td></tr>
+ </table>
+
+ <p/>
+
</s3>
</s2>
@@ -1098,6 +1129,18 @@
</table>
<p/>
+ <anchor name="CalculateSrcOffset"/>
+ <table>
+ <tr><th
colspan="2"><em>http://apache.org/xml/features/calculate-src-ofs</em></th></tr>
+ <tr><th><em>true:</em></th><td> Enable src offset calculation.
</td></tr>
+ <tr><th><em>false:</em></th><td> Disable src offset calculation.
</td></tr>
+ <tr><th><em>default:</em></th><td> false </td></tr>
+ <tr><th><em>note:</em></th><td> If set to true, the user can
inquire about
+ the current src offset within the input source. Setting it to false
(default)
+ improves the performance.</td></tr>
+ </table>
+ <p/>
+
<anchor name="builder-adopts-domdocument"/>
<table>
<tr><th
colspan="2"><em>http://apache.org/xml/features/dom/user-adopts-DOMDocument</em></th></tr>
@@ -1172,6 +1215,26 @@
attribute that may occur in an instance document:
e.g."file_name.xsd". </td></tr>
<tr><th><em>Value Type</em></th><td> XMLCh* </td></tr>
</table>
+ <p/>
+
+ <table>
+ <tr><th
colspan="2"><em>http://apache.org/xml/properties/scannerName</em></th></tr>
+ <tr><th><em>Description</em></th><td> This property allows the user
to specify the name of
+ the XMLScanner to use for scanning XML documents. If
not specified, the default
+ scanner "IGXMLScanner" is used.</td></tr>
+ <tr><th><em>Value</em></th><td> The recognized scanner names are:
<br/>
+ 1."WFXMLScanner" - scanner that performs
well-formedness checking only.<br/>
+ 2. "DGXMLScanner" - scanner that handles XML documents
with DTD grammar information.<br/>
+ 3. "SGXMLScanner" - scanner that handles XML documents
with XML schema grammar information.<br/>
+ 4. "IGXMLScanner" - scanner that handles XML documents
with DTD or/and XML schema grammar information.<br/>
+ Users can use the predefined constants defined in
XMLUni directly or a string that matches the value of
+ one of those constants.</td></tr>
+ <tr><th><em>Value Type</em></th><td> XMLCh* </td></tr>
+ <tr><th><em>note: </em></th><td> See <jump
href="program-others.html#UseSpecificScanner">Use Specific Scanner</jump>
+ for more programming details. </td></tr>
+ </table>
+ <p/>
+
</s4>
</s3>
1.8 +31 -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.7
retrieving revision 1.8
diff -u -r1.7 -r1.8
--- program-deprecateddom.xml 3 Jan 2003 20:10:29 -0000 1.7
+++ program-deprecateddom.xml 6 Jan 2003 21:19:42 -0000 1.8
@@ -550,6 +550,18 @@
</table>
<p/>
+ <anchor name="CalculateSrcOffset"/>
+ <table>
+ <tr><th colspan="2"><em>void setCalculateSrcOfs(const
bool)</em></th></tr>
+ <tr><th><em>true:</em></th><td> Enable src offset calculation.
</td></tr>
+ <tr><th><em>false:</em></th><td> Disable src offset calculation.
</td></tr>
+ <tr><th><em>default:</em></th><td> false </td></tr>
+ <tr><th><em>note:</em></th><td> If set to true, the user can
inquire about
+ the current src offset within the input source. Setting it to false
(default)
+ improves the performance.</td></tr>
+ </table>
+ <p/>
+
<table>
<tr><th colspan="2"><em>void setExternalSchemaLocation(const XMLCh*
const)</em></th></tr>
<tr><th><em>Description</em></th><td> The XML Schema Recommendation
explicitly states that
@@ -582,6 +594,25 @@
<tr><th><em>Value</em></th><td> The syntax is the same as for the
noNamespaceSchemaLocation
attribute that may occur in an instance document:
e.g."file_name.xsd".</td></tr>
<tr><th><em>Value Type</em></th><td> XMLCh* </td></tr>
+ </table>
+
+ <p/>
+
+ <table>
+ <tr><th colspan="2"><em>void useScanner(const XMLCh*
const)</em></th></tr>
+ <tr><th><em>Description</em></th><td> This property allows the user
to specify the name of
+ the XMLScanner to use for scanning XML documents. If
not specified, the default
+ scanner "IGXMLScanner" is used.</td></tr>
+ <tr><th><em>Value</em></th><td> The recognized scanner names are:
<br/>
+ 1."WFXMLScanner" - scanner that performs
well-formedness checking only.<br/>
+ 2. "DGXMLScanner" - scanner that handles XML documents
with DTD grammar information.<br/>
+ 3. "SGXMLScanner" - scanner that handles XML documents
with XML schema grammar information.<br/>
+ 4. "IGXMLScanner" - scanner that handles XML documents
with DTD or/and XML schema grammar information.<br/>
+ Users can use the predefined constants defined in
XMLUni directly or a string that matches the value of
+ one of those constants.</td></tr>
+ <tr><th><em>Value Type</em></th><td> XMLCh* </td></tr>
+ <tr><th><em>note: </em></th><td> See <jump
href="program-others.html#UseSpecificScanner">Use Specific Scanner</jump>
+ for more programming details. </td></tr>
</table>
<p/>
1.41 +17 -1 xml-xerces/c/doc/migration.xml
Index: migration.xml
===================================================================
RCS file: /home/cvs/xml-xerces/c/doc/migration.xml,v
retrieving revision 1.40
retrieving revision 1.41
diff -u -r1.40 -r1.41
--- migration.xml 6 Jan 2003 19:45:18 -0000 1.40
+++ migration.xml 6 Jan 2003 21:19:42 -0000 1.41
@@ -85,7 +85,7 @@
</ul>
<li>Added a non-standard extension
DOMImplementation::loadDOMExceptionMsg to load the
default error message for the corresponding DOMException code.</li>
- <li>XMLUri: Added a constructor and a set method to allow
creating/setting of
+ <li>XMLAttr: Added a constructor and a set method to allow
creating/setting of
XMLAttr using a rawname.</li>
<li>Added XMLUri::getUriText to return the URI as a string
specification.</li>
<li>Add XMLString::fixURI to transform an absolute path filename to
standard URI form.</li>
@@ -98,6 +98,22 @@
http://apache.org/xml/features/standard-uri-conformant</li>
</ul>
<li>Add XMLURL::hasInvalidChar() to indicate if the URL has invalid
char as per RFC standard</li>
+ <li>To allow users to enable/disable src offset calculation,
+ the following are added:</li>
+ <ul>
+ <li>XercesDOMParser/DOMParser/SAXParser:
get/setCalculateSrcOfs</li>
+ <li>and DOMBuilder/SAX2XMLReader will recognize the feature
+ http://apache.org/xml/features/calculate-src-ofst</li>
+ </ul>
+ <li>To allow users to select the scanner when scanning XML documents,
+ the following are added:</li>
+ <ul>
+ <li>XercesDOMParser/DOMParser/SAXParser: useScanner</li>
+ <li>and DOMBuilder/SAX2XMLReader will recognize the property
+ http://apache.org/xml/properties/scannerName</li>
+ </ul>
+ <li>Added getSrcOffset to
XercesDOMParser/DOMParser/SAXParser/DOMBuilder/SAX2XMLReader to
+ allow users to get the current src offset within the input
source.</li>
</ul>
</s4>
---------------------------------------------------------------------
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
