[Python-checkins] python/dist/src/Doc/lib xmlsaxhandler.tex,1.8,1.9 xmlsaxreader.tex,1.3,1.4

Tue, 25 Jun 2002 10:10:53 -0700

Update of /cvsroot/python/python/dist/src/Doc/lib
In directory usw-pr-cvs1:/tmp/cvs-serv9299/lib

Modified Files:
	xmlsaxhandler.tex xmlsaxreader.tex 
Log Message:
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: xmlsaxhandler.tex
===================================================================
RCS file: /cvsroot/python/python/dist/src/Doc/lib/xmlsaxhandler.tex,v
retrieving revision 1.8
retrieving revision 1.9
diff -C2 -d -r1.8 -r1.9
*** xmlsaxhandler.tex	19 Nov 2001 04:34:50 -0000	1.8
--- xmlsaxhandler.tex	25 Jun 2002 17:10:49 -0000	1.9
***************
*** 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.4
diff -C2 -d -r1.3 -r1.4
*** xmlsaxreader.tex	6 Nov 2001 22:11:34 -0000	1.3
--- xmlsaxreader.tex	25 Jun 2002 17:10:50 -0000	1.4
***************
*** 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}