diff options
author | Andrew M. Kuchling <amk@amk.ca> | 2010-07-25 23:23:30 (GMT) |
---|---|---|
committer | Andrew M. Kuchling <amk@amk.ca> | 2010-07-25 23:23:30 (GMT) |
commit | ea64a6a4ca1ec000f1120362e5362e867fe1f4bb (patch) | |
tree | b295bfa71902bf524d618e1c24852f9641caba5f /Doc | |
parent | bd6c079552c51fbd0a851ca389647549a1d23b57 (diff) | |
download | cpython-ea64a6a4ca1ec000f1120362e5362e867fe1f4bb.zip cpython-ea64a6a4ca1ec000f1120362e5362e867fe1f4bb.tar.gz cpython-ea64a6a4ca1ec000f1120362e5362e867fe1f4bb.tar.bz2 |
#7637: clarify description of encoding parameter
Diffstat (limited to 'Doc')
-rw-r--r-- | Doc/library/xml.dom.minidom.rst | 33 |
1 files changed, 19 insertions, 14 deletions
diff --git a/Doc/library/xml.dom.minidom.rst b/Doc/library/xml.dom.minidom.rst index 792a8dc..1efa3d9 100644 --- a/Doc/library/xml.dom.minidom.rst +++ b/Doc/library/xml.dom.minidom.rst @@ -136,18 +136,20 @@ module documentation. This section lists the differences between the API and .. method:: Node.toxml(encoding=None) - Return the XML that the DOM represents as a string. + Return a string or byte string containing the XML represented by + the DOM node. - With no argument, the XML header does not specify an encoding, and the result is - Unicode string if the default encoding cannot represent all characters in the - document. Encoding this string in an encoding other than UTF-8 is likely - incorrect, since UTF-8 is the default encoding of XML. - - With an explicit *encoding* [1]_ argument, the result is a byte string in the - specified encoding. It is recommended that this argument is always specified. To - avoid :exc:`UnicodeError` exceptions in case of unrepresentable text data, the - encoding argument should be specified as "utf-8". + With an explicit *encoding* [1]_ argument, the result is a byte + string in the specified encoding. It is recommended that you + always specify an encoding; you may use any encoding you like, but + an argument of "utf-8" is the most common, avoid + :exc:`UnicodeError` exceptions in case of unrepresentable text + data. + With no *encoding* argument, the result is a Unicode string, and the + XML declaration in the resulting string does not specify an + encoding. Encoding this string in an encoding other than UTF-8 is + likely incorrect, since UTF-8 is the default encoding of XML. .. method:: Node.toprettyxml(indent="", newl="", encoding="") @@ -155,7 +157,8 @@ module documentation. This section lists the differences between the API and indentation string and defaults to a tabulator; *newl* specifies the string emitted at the end of each line and defaults to ``\n``. - There's also an *encoding* argument; see :meth:`toxml`. + There's also an *encoding* argument, that behaves like the corresponding + argument of :meth:`toxml`. .. _dom-example: @@ -240,7 +243,9 @@ utility to most DOM users. .. rubric:: Footnotes -.. [#] The encoding string included in XML output should conform to the - appropriate standards. For example, "UTF-8" is valid, but "UTF8" is - not. See http://www.w3.org/TR/2006/REC-xml11-20060816/#NT-EncodingDecl +.. [#] The encoding name included in the XML output should conform to + the appropriate standards. For example, "UTF-8" is valid, but + "UTF8" is not valid in an XML document's declaration, even though + Python accepts it as an encoding name. + See http://www.w3.org/TR/2006/REC-xml11-20060816/#NT-EncodingDecl and http://www.iana.org/assignments/character-sets . |