[Python-checkins] python/dist/src/Doc/lib xmlsax.tex,1.4,1.4.6.1 xmlsaxhandler.tex,1.8,1.8.6.1 xmlsaxreader.tex,1.3,1.3.8.1
fdrake@users.sourceforge.net
fdrake@users.sourceforge.net
Tue, 25 Jun 2002 10:18:50 -0700
Update of /cvsroot/python/python/dist/src/Doc/lib
In directory usw-pr-cvs1:/tmp/cvs-serv12658/lib
Modified Files:
Tag: release22-maint
xmlsax.tex xmlsaxhandler.tex xmlsaxreader.tex
Log Message:
[Backport of recent changes to the SAX documentation.]
Add more links to the "See also" section for the xml.sax package.
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.
Index: xmlsax.tex
===================================================================
RCS file: /cvsroot/python/python/dist/src/Doc/lib/xmlsax.tex,v
retrieving revision 1.4
retrieving revision 1.4.6.1
diff -C2 -d -r1.4 -r1.4.6.1
*** xmlsax.tex 10 Dec 2001 18:10:37 -0000 1.4
--- xmlsax.tex 25 Jun 2002 17:18:47 -0000 1.4.6.1
***************
*** 60,64 ****
classes, but applications may use implementations which do not inherit
from the provided classes. The \class{InputSource}, \class{Locator},
! \class{AttributesImpl}, \class{AttributesNSImpl}, and
\class{XMLReader} interfaces are defined in the module
\refmodule{xml.sax.xmlreader}. The handler interfaces are defined in
--- 60,64 ----
classes, but applications may use implementations which do not inherit
from the provided classes. The \class{InputSource}, \class{Locator},
! \class{Attributes}, \class{AttributesNS}, and
\class{XMLReader} interfaces are defined in the module
\refmodule{xml.sax.xmlreader}. The handler interfaces are defined in
***************
*** 118,121 ****
--- 118,130 ----
documentation. Links to implementations and historical
information are also available.}
+
+ \seemodule{xml.sax.handler}{Definitions of the interfaces for
+ application-provided objects.}
+
+ \seemodule{xml.sax.saxutils}{Convenience functions for use in SAX
+ applications.}
+
+ \seemodule{xml.sax.xmlreader}{Definitions of the interfaces for
+ parser-provided objects.}
\end{seealso}
Index: xmlsaxhandler.tex
===================================================================
RCS file: /cvsroot/python/python/dist/src/Doc/lib/xmlsaxhandler.tex,v
retrieving revision 1.8
retrieving revision 1.8.6.1
diff -C2 -d -r1.8 -r1.8.6.1
*** xmlsaxhandler.tex 19 Nov 2001 04:34:50 -0000 1.8
--- xmlsaxhandler.tex 25 Jun 2002 17:18:48 -0000 1.8.6.1
***************
*** 194,216 ****
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.
! 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.
\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.
\end{methoddesc}
--- 194,218 ----
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 \method{startPrefixMapping()} and
! \method{endPrefixMapping()} events supply the information to the
! application to expand prefixes in those contexts itself, if
! necessary.
! 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 \method{endElement()} event,
! but the order of \method{endPrefixMapping()} events is not otherwise
! guaranteed.
\end{methoddesc}
***************
*** 220,226 ****
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
keep a copy of the attributes. To keep a copy of the attributes,
use the \method{copy()} method of the \var{attrs} object.
--- 222,229 ----
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
! 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.
***************
*** 231,235 ****
The \var{name} parameter contains the name of the element type, just
! as with the startElement event.
\end{methoddesc}
--- 234,238 ----
The \var{name} parameter contains the name of the element type, just
! as with the \method{startElement()} event.
\end{methoddesc}
***************
*** 240,245 ****
\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
--- 243,249 ----
\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
! \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
Index: xmlsaxreader.tex
===================================================================
RCS file: /cvsroot/python/python/dist/src/Doc/lib/xmlsaxreader.tex,v
retrieving revision 1.3
retrieving revision 1.3.8.1
diff -C2 -d -r1.3 -r1.3.8.1
*** xmlsaxreader.tex 6 Nov 2001 22:11:34 -0000 1.3
--- xmlsaxreader.tex 25 Jun 2002 17:18:48 -0000 1.3.8.1
***************
*** 70,87 ****
\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
instantiated by readers; \var{attrs} must be a dictionary-like
! object.
\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.
\end{classdesc}
--- 70,94 ----
\begin{classdesc}{AttributesImpl}{attrs}
! 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 containing a mapping from attribute names to attribute
! values.
\end{classdesc}
\begin{classdesc}{AttributesNSImpl}{attrs, qnames}
! 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}
***************
*** 289,313 ****
! \subsection{AttributesImpl Objects \label{attributes-impl-objects}}
! \class{AttributesImpl} objects implement a portion of the mapping
! protocol, and 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}{}
Return the number of attributes.
\end{methoddesc}
! \begin{methoddesc}[AttributesImpl]{getNames}{}
Return the names of the attributes.
\end{methoddesc}
! \begin{methoddesc}[AttributesImpl]{getType}{name}
Returns the type of the attribute \var{name}, which is normally
\code{'CDATA'}.
\end{methoddesc}
! \begin{methoddesc}[AttributesImpl]{getValue}{name}
Return the value of attribute \var{name}.
\end{methoddesc}
--- 296,320 ----
! \subsection{The \class{Attributes} Interface \label{attributes-objects}}
! \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}[Attributes]{getLength}{}
Return the number of attributes.
\end{methoddesc}
! \begin{methoddesc}[Attributes]{getNames}{}
Return the names of the attributes.
\end{methoddesc}
! \begin{methoddesc}[Attributes]{getType}{name}
Returns the type of the attribute \var{name}, which is normally
\code{'CDATA'}.
\end{methoddesc}
! \begin{methoddesc}[Attributes]{getValue}{name}
Return the value of attribute \var{name}.
\end{methoddesc}
***************
*** 317,337 ****
! \subsection{AttributesNSImpl Objects \label{attributes-ns-impl-objects}}
! \begin{methoddesc}[AttributesNSImpl]{getValueByQName}{name}
Return the value for a qualified name.
\end{methoddesc}
! \begin{methoddesc}[AttributesNSImpl]{getNameByQName}{name}
Return the \code{(\var{namespace}, \var{localname})} pair for a
qualified \var{name}.
\end{methoddesc}
! \begin{methoddesc}[AttributesNSImpl]{getQNameByName}{name}
Return the qualified name for a \code{(\var{namespace},
\var{localname})} pair.
\end{methoddesc}
! \begin{methoddesc}[AttributesNSImpl]{getQNames}{}
Return the qualified names of all attributes.
\end{methoddesc}
--- 324,351 ----
! \subsection{The \class{AttributesNS} Interface \label{attributes-ns-objects}}
! 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}[AttributesNS]{getNameByQName}{name}
Return the \code{(\var{namespace}, \var{localname})} pair for a
qualified \var{name}.
\end{methoddesc}
! \begin{methoddesc}[AttributesNS]{getQNameByName}{name}
Return the qualified name for a \code{(\var{namespace},
\var{localname})} pair.
\end{methoddesc}
! \begin{methoddesc}[AttributesNS]{getQNames}{}
Return the qualified names of all attributes.
\end{methoddesc}