From 43da35de7bfbdbcba26d7d4226835cc718c2de7d Mon Sep 17 00:00:00 2001 From: Mark Summerfield Date: Mon, 17 Mar 2008 08:28:15 +0000 Subject: 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. --- Doc/library/pyexpat.rst | 10 +++++++++- Doc/library/xml.dom.minidom.rst | 13 ++++++++++--- Doc/library/xml.etree.elementtree.rst | 11 ++++++++++- 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 . + -- cgit v0.12