Talk about interfaces rather than implementation classes where appropriate.
Add hyperlinks to make the documentation on the Attributes and AttributesNS
interfaces more discoverable.
Closes SF bug #484603.
diff --git a/Doc/lib/xmlsaxhandler.tex b/Doc/lib/xmlsaxhandler.tex
index 952a563..91c6ebc 100644
--- a/Doc/lib/xmlsaxhandler.tex
+++ b/Doc/lib/xmlsaxhandler.tex
@@ -193,25 +193,27 @@
There are cases, however, when applications need to use prefixes in
character data or in attribute values, where they cannot safely be
- expanded automatically; the start/endPrefixMapping event supplies
- the information to the application to expand prefixes in those
- contexts itself, if necessary.
+ expanded automatically; the \method{startPrefixMapping()} and
+ \method{endPrefixMapping()} events supply the information to the
+ application to expand prefixes in those contexts itself, if
+ necessary.
- 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 \method{startElement()} event, and all
- \method{endPrefixMapping()} events will occur after the
- corresponding \method{endElement()} event, but their order is not
- guaranteed.
+ Note that \method{startPrefixMapping()} and
+ \method{endPrefixMapping()} events are not guaranteed to be properly
+ nested relative to each-other: all \method{startPrefixMapping()}
+ events will occur before the 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}
End the scope of a prefix-URI mapping.
-
- See \method{startPrefixMapping()} for details. This event will always
- occur after the corresponding endElement event, but the order of
- endPrefixMapping events is not otherwise guaranteed.
+
+ See \method{startPrefixMapping()} for details. This event will
+ always occur after the corresponding \method{endElement()} event,
+ but the order of \method{endPrefixMapping()} events is not otherwise
+ guaranteed.
\end{methoddesc}
\begin{methoddesc}[ContentHandler]{startElement}{name, attrs}
@@ -219,9 +221,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. 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
+ object of the \ulink{\class{Attributes}
+ interface}{attributes-objects.html} containing the attributes 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}
@@ -230,7 +233,7 @@
Signals the end of an element in non-namespace mode.
The \var{name} parameter contains the name of the element type, just
- as with the startElement event.
+ as with the \method{startElement()} event.
\end{methoddesc}
\begin{methoddesc}[ContentHandler]{startElementNS}{name, qname, attrs}
@@ -239,8 +242,9 @@
The \var{name} parameter contains the name of the element type as a
\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
+ \var{attrs} parameter holds an instance of the
+ \ulink{\class{AttributesNS} interface}{attributes-ns-objects.html}
+ 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
diff --git a/Doc/lib/xmlsaxreader.tex b/Doc/lib/xmlsaxreader.tex
index e8db562..c09fcd6 100644
--- a/Doc/lib/xmlsaxreader.tex
+++ b/Doc/lib/xmlsaxreader.tex
@@ -69,20 +69,27 @@
\end{classdesc}
\begin{classdesc}{AttributesImpl}{attrs}
- This is a dictionary-like object which represents the element
- attributes in a \method{startElement()} call. In addition to the
- most useful dictionary operations, it supports a number of other
- methods as described below. Objects of this class should be
+ This is an implementation of the \ulink{\class{Attributes}
+ interface}{attributes-objects.html} (see
+ section~\ref{attributes-objects}). This is a dictionary-like
+ object which represents the element attributes in a
+ \method{startElement()} call. In addition to the most useful
+ dictionary operations, it supports a number of other methods as
+ described by the interface. Objects of this class should be
instantiated by readers; \var{attrs} must be a dictionary-like
- object.
+ object containing a mapping from attribute names to attribute
+ values.
\end{classdesc}
\begin{classdesc}{AttributesNSImpl}{attrs, qnames}
- Namespace-aware variant of attributes, which will be passed to
- \method{startElementNS()}. It is derived from \class{AttributesImpl},
- but understands attribute names as two-tuples of \var{namespaceURI}
- and \var{localname}. In addition, it provides a number of methods
- expecting qualified names as they appear in the original document.
+ Namespace-aware variant of \class{AttributesImpl}, which will be
+ passed to \method{startElementNS()}. It is derived from
+ \class{AttributesImpl}, but understands attribute names as
+ two-tuples of \var{namespaceURI} and \var{localname}. In addition,
+ it provides a number of methods expecting qualified names as they
+ appear in the original document. This class implements the
+ \ulink{\class{AttributesNS} interface}{attributes-ns-objects.html}
+ (see section~\ref{attributes-ns-objects}).
\end{classdesc}
@@ -288,27 +295,27 @@
\end{methoddesc}
-\subsection{AttributesImpl Objects \label{attributes-impl-objects}}
+\subsection{The \class{Attributes} Interface \label{attributes-objects}}
-\class{AttributesImpl} objects implement a portion of the mapping
-protocol, and the methods \method{copy()}, \method{get()},
+\class{Attributes} objects implement a portion of the mapping
+protocol, including the methods \method{copy()}, \method{get()},
\method{has_key()}, \method{items()}, \method{keys()}, and
\method{values()}. The following methods are also provided:
-\begin{methoddesc}[AttributesImpl]{getLength}{}
+\begin{methoddesc}[Attributes]{getLength}{}
Return the number of attributes.
\end{methoddesc}
-\begin{methoddesc}[AttributesImpl]{getNames}{}
+\begin{methoddesc}[Attributes]{getNames}{}
Return the names of the attributes.
\end{methoddesc}
-\begin{methoddesc}[AttributesImpl]{getType}{name}
+\begin{methoddesc}[Attributes]{getType}{name}
Returns the type of the attribute \var{name}, which is normally
\code{'CDATA'}.
\end{methoddesc}
-\begin{methoddesc}[AttributesImpl]{getValue}{name}
+\begin{methoddesc}[Attributes]{getValue}{name}
Return the value of attribute \var{name}.
\end{methoddesc}
@@ -316,22 +323,29 @@
% here already, but documented only for derived class.
-\subsection{AttributesNSImpl Objects \label{attributes-ns-impl-objects}}
+\subsection{The \class{AttributesNS} Interface \label{attributes-ns-objects}}
-\begin{methoddesc}[AttributesNSImpl]{getValueByQName}{name}
+This interface is a subtype of the \ulink{\class{Attributes}
+interface}{attributes-objects.html} (see
+section~\ref{attributes-objects}). All methods supported by that
+interface are also available on \class{AttributesNS} objects.
+
+The following methods are also available:
+
+\begin{methoddesc}[AttributesNS]{getValueByQName}{name}
Return the value for a qualified name.
\end{methoddesc}
-\begin{methoddesc}[AttributesNSImpl]{getNameByQName}{name}
+\begin{methoddesc}[AttributesNS]{getNameByQName}{name}
Return the \code{(\var{namespace}, \var{localname})} pair for a
qualified \var{name}.
\end{methoddesc}
-\begin{methoddesc}[AttributesNSImpl]{getQNameByName}{name}
+\begin{methoddesc}[AttributesNS]{getQNameByName}{name}
Return the qualified name for a \code{(\var{namespace},
\var{localname})} pair.
\end{methoddesc}
-\begin{methoddesc}[AttributesNSImpl]{getQNames}{}
+\begin{methoddesc}[AttributesNS]{getQNames}{}
Return the qualified names of all attributes.
\end{methoddesc}