Added a footnote to each pointing out that for XML output if an encoding

string is given it should conform to the appropriate XML standards---for
example, "UTF-8" is okay, but "UTF8" is not.

3 files changed, 29 insertions, 5 deletions

diff --git a/Doc/library/pyexpat.rst b/Doc/library/pyexpat.rst
index 9a0f914..1d5e6e6 100644
--- a/Doc/library/pyexpat.rst
+++ b/Doc/library/pyexpat.rst
@@ -63,7 +63,7 @@ The :mod:`xml.parsers.expat` module contains two functions:
    must be a string naming the encoding  used by the XML data.  Expat doesn't
    support as many encodings as Python does, and its repertoire of encodings can't
    be extended; it supports UTF-8, UTF-16, ISO-8859-1 (Latin1), and ASCII.  If
-   *encoding* is given it will override the implicit or explicit encoding of the
+   *encoding* [1]_ is given it will override the implicit or explicit encoding of the
    document.
 
    Expat can optionally do XML namespace processing for you, enabled by providing a
@@ -885,3 +885,11 @@ The ``errors`` object has the following attributes:
 .. data:: XML_ERROR_SUSPEND_PE
    :noindex:
 
+
+.. 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
+   and http://www.iana.org/assignments/character-sets .
+
diff --git a/Doc/library/xml.dom.minidom.rst b/Doc/library/xml.dom.minidom.rst
index 3f1d2a4..21b2d6c 100644
--- a/Doc/library/xml.dom.minidom.rst
+++ b/Doc/library/xml.dom.minidom.rst
@@ -141,7 +141,8 @@ module documentation.  This section lists the differences between the API and
       support pretty output.
 
    .. versionchanged:: 2.3
-      For the :class:`Document` node, an additional keyword argument *encoding* can be
+      For the :class:`Document` node, an additional keyword argument
+      *encoding* [1]_ can be
       used to specify the encoding field of the XML header.
 
 
@@ -154,7 +155,7 @@ module documentation.  This section lists the differences between the API and
    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* argument, the result is a byte string in the
+   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".
@@ -172,7 +173,7 @@ module documentation.  This section lists the differences between the API and
    .. versionadded:: 2.1
 
    .. versionchanged:: 2.3
-      the encoding argument; see :meth:`toxml`.
+      the encoding [1]_ argument; see :meth:`toxml`.
 
 The following standard DOM methods have special considerations with
 :mod:`xml.dom.minidom`:
@@ -265,3 +266,9 @@ The following interfaces have no implementation in :mod:`xml.dom.minidom`:
 Most of these reflect information in the XML document that is not of general
 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
+   and http://www.iana.org/assignments/character-sets .
diff --git a/Doc/library/xml.etree.elementtree.rst b/Doc/library/xml.etree.elementtree.rst
index d1d4b6b..e0b9955 100644
--- a/Doc/library/xml.etree.elementtree.rst
+++ b/Doc/library/xml.etree.elementtree.rst
@@ -357,7 +357,7 @@ ElementTree Objects
 .. method:: ElementTree.write(file[, encoding])
 
    Writes the element tree to a file, as XML. *file* is a file name, or a file
-   object opened for writing. *encoding* is the output encoding (default is
+   object opened for writing. *encoding* [1]_ is the output encoding (default is
    US-ASCII).
 
 This is the XML file that is going to be manipulated::
@@ -510,3 +510,12 @@ This is an example of counting the maximum depth of an XML file::
     >>> parser.feed(exampleXml)
     >>> parser.close()
     4
+
+
+.. 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
+   and http://www.iana.org/assignments/character-sets .
+