Author: borisk
Date: Wed Nov 4 14:16:29 2009
New Revision: 832751
URL: http://svn.apache.org/viewvc?rev=832751&view=rev
Log:
Expand setNewLine() documentation (XERCESC-1507).
Modified:
xerces/c/trunk/src/xercesc/dom/DOMLSSerializer.hpp
Modified: xerces/c/trunk/src/xercesc/dom/DOMLSSerializer.hpp
URL:
http://svn.apache.org/viewvc/xerces/c/trunk/src/xercesc/dom/DOMLSSerializer.hpp?rev=832751&r1=832750&r2=832751&view=diff
==============================================================================
--- xerces/c/trunk/src/xercesc/dom/DOMLSSerializer.hpp (original)
+++ xerces/c/trunk/src/xercesc/dom/DOMLSSerializer.hpp Wed Nov 4 14:16:29 2009
@@ -5,9 +5,9 @@
* The ASF licenses this file to You under the Apache License, Version 2.0
* (the "License"); you may not use this file except in compliance with
* the License. You may obtain a copy of the License at
- *
+ *
* http://www.apache.org/licenses/LICENSE-2.0
- *
+ *
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
@@ -272,17 +272,17 @@
class DOMLSOutput;
-class CDOM_EXPORT DOMLSSerializer
+class CDOM_EXPORT DOMLSSerializer
{
protected :
// -----------------------------------------------------------------------
// Hidden constructors
// -----------------------------------------------------------------------
/** @name Hidden constructors */
- //@{
+ //@{
DOMLSSerializer() {};
//@}
-private:
+private:
// -----------------------------------------------------------------------
// Unimplemented constructors and operators
// -----------------------------------------------------------------------
@@ -318,71 +318,71 @@
* The DOMConfiguration object used by the LSSerializer when serializing
a DOM node.
*
* In addition to the parameters recognized in on the
<code>DOMConfiguration</code>
- * interface defined in [DOM Level 3 Core], the
<code>DOMConfiguration</code> objects
- * for <code>DOMLSSerializer</code> add or modify the following
parameters:
+ * interface defined in [DOM Level 3 Core], the
<code>DOMConfiguration</code> objects
+ * for <code>DOMLSSerializer</code> add or modify the following
parameters:
*
* "canonical-form"
* true [optional]
- * Writes the document according to the rules specified in
[Canonical XML]. In addition to
- * the behavior described in "canonical-form" [DOM Level 3 Core],
setting this parameter to
- * true will set the parameters "format-pretty-print",
"discard-default-content", and
- * "xml-declaration", to false. Setting one of those parameters
to true will set this
- * parameter to false. Serializing an XML 1.1 document when
"canonical-form" is true will
+ * Writes the document according to the rules specified in
[Canonical XML]. In addition to
+ * the behavior described in "canonical-form" [DOM Level 3 Core],
setting this parameter to
+ * true will set the parameters "format-pretty-print",
"discard-default-content", and
+ * "xml-declaration", to false. Setting one of those parameters
to true will set this
+ * parameter to false. Serializing an XML 1.1 document when
"canonical-form" is true will
* generate a fatal error.
* false [required] (default)
* Do not canonicalize the output.
*
* "discard-default-content"
* true [required] (default)
- * Use the DOMAttr::getSpecified attribute to decide what
attributes should be discarded.
- * Note that some implementations might use whatever information
available to the implementation
- * (i.e. XML schema, DTD, the DOMAttr::getSpecified attribute,
and so on) to determine what
+ * Use the DOMAttr::getSpecified attribute to decide what
attributes should be discarded.
+ * Note that some implementations might use whatever information
available to the implementation
+ * (i.e. XML schema, DTD, the DOMAttr::getSpecified attribute,
and so on) to determine what
* attributes and content to discard if this parameter is set to
true.
* false [required]
* Keep all attributes and all content.
*
* "format-pretty-print"
* true [optional]
- * Formatting the output by adding whitespace to produce a
pretty-printed, indented,
- * human-readable form. The exact form of the transformations is
not specified by this specification.
- * Pretty-printing changes the content of the document and may
affect the validity of the document,
+ * Formatting the output by adding whitespace to produce a
pretty-printed, indented,
+ * human-readable form. The exact form of the transformations is
not specified by this specification.
+ * Pretty-printing changes the content of the document and may
affect the validity of the document,
* validating implementations should preserve validity.
* false [required] (default)
* Don't pretty-print the result.
*
* "ignore-unknown-character-denormalizations"
* true [required] (default)
- * If, while verifying full normalization when [XML 1.1] is
supported, a character is encountered
- * for which the normalization properties cannot be determined,
then raise a "unknown-character-denormalization"
- * warning (instead of raising an error, if this parameter is not
set) and ignore any possible
+ * If, while verifying full normalization when [XML 1.1] is
supported, a character is encountered
+ * for which the normalization properties cannot be determined,
then raise a "unknown-character-denormalization"
+ * warning (instead of raising an error, if this parameter is not
set) and ignore any possible
* denormalizations caused by these characters.
* false [optional]
- * Report a fatal error if a character is encountered for which
the processor cannot determine the
+ * Report a fatal error if a character is encountered for which
the processor cannot determine the
* normalization properties.
*
* "normalize-characters"
- * This parameter is equivalent to the one defined by
<code>DOMConfiguration</code> in [DOM Level 3 Core].
- * Unlike in the Core, the default value for this parameter is true.
While DOM implementations are not
- * required to support fully normalizing the characters in the
document according to appendix E of [XML 1.1],
+ * This parameter is equivalent to the one defined by
<code>DOMConfiguration</code> in [DOM Level 3 Core].
+ * Unlike in the Core, the default value for this parameter is true.
While DOM implementations are not
+ * required to support fully normalizing the characters in the
document according to appendix E of [XML 1.1],
* this parameter must be activated by default if supported.
*
* "xml-declaration"
* true [required] (default)
- * If a DOMDocument, DOMElement, or DOMEntity node is serialized,
the XML declaration, or text declaration,
- * should be included. The version (DOMDocument::xmlVersion if
the document is a Level 3 document and the
- * version is non-null, otherwise use the value "1.0"), and the
output encoding (see DOMLSSerializer::write
+ * If a DOMDocument, DOMElement, or DOMEntity node is serialized,
the XML declaration, or text declaration,
+ * should be included. The version (DOMDocument::xmlVersion if
the document is a Level 3 document and the
+ * version is non-null, otherwise use the value "1.0"), and the
output encoding (see DOMLSSerializer::write
* for details on how to find the output encoding) are specified
in the serialized XML declaration.
* false [required]
- * Do not serialize the XML and text declarations. Report a
"xml-declaration-needed" warning if this will
- * cause problems (i.e. the serialized data is of an XML version
other than [XML 1.0], or an encoding would
+ * Do not serialize the XML and text declarations. Report a
"xml-declaration-needed" warning if this will
+ * cause problems (i.e. the serialized data is of an XML version
other than [XML 1.0], or an encoding would
* be needed to be able to re-parse the serialized data).
*
* "error-handler"
- * Contains a DOMErrorHandler object. If an error is encountered in
the document, the implementation will call back
- * the DOMErrorHandler registered using this parameter. The
implementation may provide a default DOMErrorHandler
- * object. When called, DOMError::relatedData will contain the
closest node to where the error occurred.
- * If the implementation is unable to determine the node where the
error occurs, DOMError::relatedData will contain
- * the DOMDocument node. Mutations to the document from within an
error handler will result in implementation
+ * Contains a DOMErrorHandler object. If an error is encountered in
the document, the implementation will call back
+ * the DOMErrorHandler registered using this parameter. The
implementation may provide a default DOMErrorHandler
+ * object. When called, DOMError::relatedData will contain the
closest node to where the error occurred.
+ * If the implementation is unable to determine the node where the
error occurs, DOMError::relatedData will contain
+ * the DOMDocument node. Mutations to the document from within an
error handler will result in implementation
* dependent behavior.
*
* @return The pointer to the configuration object.
@@ -403,7 +403,12 @@
* the default to match the usual convention for text files in the
* environment being used. Implementations must choose a default
* sequence that matches one of those allowed by 2.11 "End-of-Line
- * Handling". </dd>
+ * Handling". However, Xerces-C++ always uses LF ('\n') when this
+ * property is set to <code>null</code> since otherwise automatic
+ * translation of '\n' to '\r\n' on Windows for text files would
+ * result in such files containing '\r\r\n'. If you need Windows-style
+ * end of line sequences in your output, consider writing to a file
+ * opened in text mode or explicitly set this property to CR-LF.</dd>
* <dt>CR</dt>
* <dd>The carriage-return character (\#xD).</dd>
* <dt>CR-LF</dt>
@@ -495,7 +500,7 @@
* occured and the failure wasn't canceled by the error handler.
* @since DOM Level 3
*/
- virtual bool writeToURI(const DOMNode* nodeToWrite,
+ virtual bool writeToURI(const DOMNode* nodeToWrite,
const XMLCh* uri) = 0;
/**
* Serialize the specified node as described above in the description of
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
