From c5e2792ab43faa2cdf3dc222e29ddf7bd44ec64a Mon Sep 17 00:00:00 2001 From: Fred Drake Date: Tue, 25 Jun 2002 17:10:50 +0000 Subject: [PATCH] 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. --- Doc/lib/xmlsaxhandler.tex | 44 +++++++++++++++-------------- Doc/lib/xmlsaxreader.tex | 58 ++++++++++++++++++++++++--------------- 2 files changed, 60 insertions(+), 42 deletions(-) diff --git a/Doc/lib/xmlsaxhandler.tex b/Doc/lib/xmlsaxhandler.tex index 952a5631db1..91c6ebce502 100644 --- a/Doc/lib/xmlsaxhandler.tex +++ b/Doc/lib/xmlsaxhandler.tex @@ -193,25 +193,27 @@ appropriate events in the input document: 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 @@ 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. 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 @@ appropriate events in the input document: 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 @@ appropriate events in the input document: 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 e8db5621862..c09fcd63e64 100644 --- a/Doc/lib/xmlsaxreader.tex +++ b/Doc/lib/xmlsaxreader.tex @@ -69,20 +69,27 @@ parser object. \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 @@ Instances of \class{Locator} provide these methods: \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 @@ protocol, and the methods \method{copy()}, \method{get()}, % 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}