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.
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 @@
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 @@
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 @@
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.