Clarified a couple of issues for the startElement*() handlers:

- the attrs value may be re-used by the parser, so the implementation
  cannot rely on owning the object.
- an element with no namespace encountered in namespace mode will have a URI
  of None, not "" (startElementNS() only).

Fixed a couple of minor markup issues as well.

1 files changed, 18 insertions, 8 deletions

diff --git a/Doc/lib/xmlsaxhandler.tex b/Doc/lib/xmlsaxhandler.tex
index 77ec724..ccb3109 100644
--- a/Doc/lib/xmlsaxhandler.tex
+++ b/Doc/lib/xmlsaxhandler.tex
@@ -200,9 +200,10 @@ appropriate events in the input document:
   Note that start/endPrefixMapping events are not guaranteed to be
   properly nested relative to each-other: all
   \method{startPrefixMapping()} events will occur before the
-  corresponding startElement event, and all \method{endPrefixMapping()}
-  events will occur after the corresponding \method{endElement()} event,
-  but their order is not guaranteed.
+  corresponding \method{startElement()} event, and all
+  \method{endPrefixMapping()} events will occur after the
+  corresponding \method{endElement()} event, but their order is not
+  guaranteed.
 \end{methoddesc}
 
 \begin{methoddesc}[ContentHandler]{endPrefixMapping}{prefix}
@@ -219,7 +220,10 @@ appropriate events in the input document:
   The \var{name} parameter contains the raw XML 1.0 name of the
   element type as a string and the \var{attrs} parameter holds an
   instance of the \class{Attributes} class containing the attributes
-  of the element.
+  of the element.  The object passed as \var{attrs} may be re-used by
+  the parser; holding on to a reference to it is not a reliable way to
+  keep a copy of the attributes.  To keep a copy of the attributes,
+  use the \method{copy()} method of the \var{attrs} object.
 \end{methoddesc}
 
 \begin{methoddesc}[ContentHandler]{endElement}{name}
@@ -233,10 +237,16 @@ appropriate events in the input document:
   Signals the start of an element in namespace mode.
 
   The \var{name} parameter contains the name of the element type as a
-  (uri, localname) tuple, the \var{qname} parameter the raw XML 1.0
-  name used in the source document, and the \var{attrs} parameter
-  holds an instance of the \class{AttributesNS} class containing the
-  attributes of the element.
+  \code{(\var{uri}, \var{localname})} tuple, the \var{qname} parameter
+  contains the raw XML 1.0 name used in the source document, and the
+  \var{attrs} parameter holds an instance of the \class{AttributesNS}
+  class containing the attributes of the element.  If no namespace is
+  associated with the element, the \var{uri} component of \var{name}
+  will be \code{None}.  The object passed as \var{attrs} may be
+  re-used by the parser; holding on to a reference to it is not a
+  reliable way to keep a copy of the attributes.  To keep a copy of
+  the attributes, use the \method{copy()} method of the \var{attrs}
+  object.
 
   Parsers may set the \var{qname} parameter to \code{None}, unless the
   \code{feature_namespace_prefixes} feature is activated.