summaryrefslogtreecommitdiffstats
path: root/Doc
diff options
context:
space:
mode:
authorAndrew M. Kuchling <amk@amk.ca>2010-07-25 23:23:30 (GMT)
committerAndrew M. Kuchling <amk@amk.ca>2010-07-25 23:23:30 (GMT)
commitea64a6a4ca1ec000f1120362e5362e867fe1f4bb (patch)
treeb295bfa71902bf524d618e1c24852f9641caba5f /Doc
parentbd6c079552c51fbd0a851ca389647549a1d23b57 (diff)
downloadcpython-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.rst33
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 .