From afac806d5006584ed3b53bc144cc9191d51e6112 Mon Sep 17 00:00:00 2001
From: PeiYong Zhang <peiyongz@apache.org>
Date: Wed, 5 Jun 2002 15:11:52 +0000
Subject: [PATCH] Documentation updated due to introudction of
DOMWriter/DOMWriterFilter.
git-svn-id: https://svn.apache.org/repos/asf/xerces/c/trunk@173797 13f79535-47bb-0310-9956-ffa450edef68
---
doc/domprint.xml | 75 +++++++++++++++++++++++++++++++++++-------------
1 file changed, 55 insertions(+), 20 deletions(-)
diff --git a/doc/domprint.xml b/doc/domprint.xml
index d4270a70e..e7045dddb 100644
--- a/doc/domprint.xml
+++ b/doc/domprint.xml
@@ -4,47 +4,46 @@
<s1 title="Sample: DOMPrint">
<s2 title="DOMPrint">
- <p>DOMPrint parses an XML file, constructs the DOM tree, and walks
- through the tree printing each element. It thus dumps the XML back
- (output same as SAXPrint).</p>
+ <p>DOMPrint parses an XML file, constructs the DOM tree, and
+ invokes DOMWriter::writeNode() to serialize the resultant
+ DOM tree back to XML stream.
+ </p>
<s3 title="Running DOMPrint">
<p>The DOMPrint sample parses an XML file, using either a validating
or non-validating DOM parser configuration, builds a DOM tree,
- and then walks the tree and outputs the contents of the nodes
- in a 'canonical' format. To run DOMPrint, enter the following:</p>
+ and then invokes DOMWriter::writeNode() to serialize the
+ resultant DOM tree. To run DOMPrint, enter the following:</p>
<source>DOMPrint <XML file></source>
<p>The following parameters may be set from the command line </p>
<source>
Usage:
- DOMPrint [options] <XML file>
+ DOMPrint [options] <XML file>
-This program invokes the DOM parser, and builds the DOM tree.
-It then traverses the DOM tree and prints the contents of the
-tree for the specified XML file.
+This program invokes the DOM parser, and builds the DOM tree
+It then asks the DOMWriter to serialize the DOM tree.
Options:
-e create entity reference nodes. Default is no expansion.
- -u=xxx Handle unrepresentable chars [fail | rep | ref*].
-v=xxx Validation scheme [always | never | auto*].
-n Enable namespace processing. Default is off.
-s Enable schema processing. Default is off.
-f Enable full schema constraint checking. Defaults is off.
- -x=XXX Use a particular encoding for output. Default is
+ -wenc=XXX Use a particular encoding for output. Default is
the same encoding as the input XML file. UTF-8 if
input XML file has not XML declaration.
- -? Show this help.
-
+ -weol=xxx Set the end of line sequence. Default set by DOMWriter.
+ -wscs=xxx Enable/Disable split-cdata-sections. Default on.
+ -wddc=xxx Enable/Disable discard-default-content. Default on.
+ -wflt=xxx Enable/Disable filtering. Default off.
+ -? Show this help
* = Default if not provided explicitly.
-The parser has intrinsic support for the following encodings:
- UTF-8, USASCII, ISO8859-1, UTF-16[BL]E, UCS-4[BL]E,
- WINDOWS-1252, IBM1140, IBM037.
+The parser has intrinsic support for the following encodings:\n"
+ UTF-8, USASCII, ISO8859-1, UTF-16[BL]E, UCS-4[BL]E,\n"
+ WINDOWS-1252, IBM1140, IBM037.\n"
</source>
- <p><em>-u=fail</em> will fail when unrepresentable characters are encountered<br/>
- <em>-u=rep</em> will replace with the substitution character for that codepage<br/>
- <em>-u=ref</em> will report the character as a reference</p>
<p><em>-v=always</em> will force validation<br/>
<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>
@@ -96,9 +95,45 @@ DOMPrint -v=always personal.xml
</person>
</personnel></source>
- <p>Note that DOMPrint does not reproduce the original XML file. DOMPrint and
+ <p>Note that DOMPrint does not reproduce the original XML file. DOMPrint and
SAXPrint produce different results because of the way the two APIs store data
and capture events.</p>
+
+ <p>Application needs to provide its own implementation of
+ DOMErrorHandler (in this sample, the DOMPrintErrorHandler),
+ if it would like to receive notification from the serializer
+ in the case any error occurs during the serialization.
+ </p>
+
+ <p>Application needs to provide its own implementation of
+ DOMWriterFilter (in this sample, the DOMPrintFilter),
+ if it would like to filter out certain part of the DOM
+ representation, but must be aware that thus may render the
+ resultant XML stream invalid.
+ </p>
+
+ <p>Application may choose any combination of characters as the
+ end of line sequence to be used in the resultant XML stream,
+ but must be aware that thus may render the resultant XML
+ stream ill formed.
+ </p>
+
+ <p>Application may choose a particular encoding name in which
+ the output XML stream would be, but must be aware that if
+ characters, unrepresentable in the encoding specified, appearing
+ in markups, may force the serializer to terminate serialization
+ prematurely, and thus no complete serialization would be done.
+ </p>
+
+ <p>Application shall query the serializer first, before set any
+ feature/mode(true, false), or be ready to catch exception if this
+ feature/mode is not supported by the serializer.
+ </p>
+
+ <p>Application needs to clean up the filter, error handler and
+ format target objects created for the serialization.
+ </p>
+
</s3>
</s2>
</s1>
--
GitLab