# [Python-checkins] CVS: python/dist/src/Doc/lib xmldom.tex,1.2,1.3 xmldomminidom.tex,1.1,1.2

Fred L. Drake python-dev@python.org
Wed, 6 Dec 2000 20:47:54 -0800

Update of /cvsroot/python/python/dist/src/Doc/lib
In directory slayer.i.sourceforge.net:/tmp/cvs-serv11629/lib

Modified Files:
xmldom.tex xmldomminidom.tex
Log Message:

Lots of additional information.  Not done, but much better.

Index: xmldom.tex
===================================================================
RCS file: /cvsroot/python/python/dist/src/Doc/lib/xmldom.tex,v
retrieving revision 1.2
retrieving revision 1.3
diff -C2 -r1.2 -r1.3
*** xmldom.tex	2000/11/29 06:10:22	1.2
--- xmldom.tex	2000/12/07 04:47:51	1.3
***************
*** 90,95 ****

The definitive documentation for the DOM is the DOM specification from
! the W3C.  This section lists the properties and methods supported by
! \refmodule{xml.dom.minidom}.

Note that DOM attributes may also be manipulated as nodes instead of
--- 90,94 ----

The definitive documentation for the DOM is the DOM specification from
! the W3C.

Note that DOM attributes may also be manipulated as nodes instead of
***************
*** 99,104 ****
--- 98,109 ----

\begin{tableiii}{l|l|l}{class}{Interface}{Section}{Purpose}
+   \lineiii{DOMImplementation}{\ref{dom-implementation-objects}}
+           {Interface to the underlying implementation.}
\lineiii{Node}{\ref{dom-node-objects}}
{Base interface for most objects in a document.}
+   \lineiii{NodeList}{\ref{dom-nodelist-objects}}
+           {Interface for a sequence of nodes.}
+   \lineiii{DocumentType}{\ref{dom-documenttype-objects}}
+           {Information about the declarations needed to process a document.}
\lineiii{Document}{\ref{dom-document-objects}}
{Object which represents an entire document.}
***************
*** 116,119 ****
--- 121,137 ----

+ \subsubsection{DOMImplementation Objects
+                \label{dom-implementation-objects}}
+
+ The \class{DOMImplementation} interface provides a way for
+ applications to determine the availability of particular features in
+ the DOM they are using.  DOM Level 2 added the ability to create new
+ \class{Document} and \class{DocumentType} objects using the
+ \class{DOMImplementation} as well.
+
+ \begin{methoddesc}[DOMImplementation]{hasFeature}{feature, version}
+ \end{methoddesc}
+
+
\subsubsection{Node Objects \label{dom-node-objects}}

***************
*** 132,136 ****

\begin{memberdesc}[Node]{parentNode}
! The parent of the current node.  \code{None} for the document node.
\end{memberdesc}

--- 150,158 ----

\begin{memberdesc}[Node]{parentNode}
! The parent of the current node, or \code{None} for the document node.
! The value is always a \class{Node} object or \code{None}.  For
! \class{Element} nodes, this will be the parent element, except for the
! root element, in which case it will be the \class{Document} object.
! For \class{Attr} nodes, this is always \code{None}.
\end{memberdesc}

***************
*** 145,154 ****
\var{self} element's start-tag.  Of course, XML documents are made
up of more than just elements so the previous sibling could be text, a
! comment, or something else.
\end{memberdesc}

\begin{memberdesc}[Node]{nextSibling}
The node that immediately follows this one with the same parent.  See
! also \member{previousSibling}.
\end{memberdesc}

--- 167,178 ----
\var{self} element's start-tag.  Of course, XML documents are made
up of more than just elements so the previous sibling could be text, a
! comment, or something else.  If this node is the first child of the
! parent, this attribute will be \code{None}.
\end{memberdesc}

\begin{memberdesc}[Node]{nextSibling}
The node that immediately follows this one with the same parent.  See
! also \member{previousSibling}.  If this is the last child of the
! parent, this attribute will be \code{None}.
\end{memberdesc}

***************
*** 165,173 ****
\end{memberdesc}

\begin{memberdesc}[Node]{nodeName}
Has a different meaning for each node type.  See the DOM specification
for details.  You can always get the information you would get here
from another property such as the \member{tagName} property for
! elements or the \member{name} property for attributes.
\end{memberdesc}

--- 189,204 ----
\end{memberdesc}

+ \begin{memberdesc}[Element]{namespaceURI}
+ The namespace associated with the element name.  This will be a
+ string.
+ \end{memberdesc}
+
\begin{memberdesc}[Node]{nodeName}
Has a different meaning for each node type.  See the DOM specification
for details.  You can always get the information you would get here
from another property such as the \member{tagName} property for
! elements or the \member{name} property for attributes.  For all node
! types, the value of this attribute will be either a string or
! \code{None}.
\end{memberdesc}

***************
*** 214,225 ****
\begin{methoddesc}[Node]{cloneNode}{deep}
Clone this node.  Setting \var{deep} means to clone all child nodes as
! well.

! \strong{Warning:}  Although this method was present in the version of
! \refmodule{xml.dom.minidom} packaged with Python 2.0, it was seriously
! broken.  This has been corrected for subsequent releases.
\end{methoddesc}

\subsubsection{Document Objects \label{dom-document-objects}}

--- 245,334 ----
\begin{methoddesc}[Node]{cloneNode}{deep}
Clone this node.  Setting \var{deep} means to clone all child nodes as
! well.  This returns the clone.
! \end{methoddesc}
!
!
! \subsubsection{NodeList Objects \label{dom-nodelist-objects}}
!
! A \class{NodeList} represents a sequence of nodes.  These objects are
! used in two ways in the DOM Core recommendation:  the
! \class{Element} objects provides one as it's list of child nodes, and
! the \method{getElementsByTagName()} and
! \method{getElementsByTagNameNS()} methods of \class{Node} return
! objects with this interface to represent query results.

! The DOM Level 2 recommendation defines one method and one attribute
! for these objects:
!
! \begin{methoddesc}[NodeList]{item}{i}
!   Return the \var{i}'th item from the sequence, if there is one, or
!   \code{None}.  The index \var{i} is not allowed to be less then zero
!   or greater than or equal to the length of the sequence.
\end{methoddesc}

+ \begin{memberdesc}[NodeList]{length}
+   The number of nodes in the sequence.
+ \end{memberdesc}
+
+ In addition, the Python DOM interface requires that some additional
+ support is provided to allow \class{NodeList} objects to be used as
+ Python sequences.  All \class{NodeList} implementations must include
+ support for \method{__len__()} and \method{__getitem__()}; this allows
+ iteration over the \class{NodeList} in \keyword{for} statements and
+ proper support for the \function{len()} built-in function.
+
+ If a DOM implementation supports modification of the document, the
+ \class{NodeList} implementation must also support the
+ \method{__setitem__()} and \method{__delitem__()} methods.
+
+
+ \subsubsection{DocumentType Objects \label{dom-documenttype-objects}}
+
+ Information about the notations and entities declared by a document
+ (including the external subset if the parser uses it and can provide
+ the information) is available from a \class{DocumentType} object.  The
+ \class{DocumentType} for a document is available from the
+ \class{Document} object's \member{doctype} attribute.
+
+ \class{DocumentType} is a specialization of \class{Node}, and adds the
+ following attributes:
+
+ \begin{memberdesc}[DocumentType]{publicId}
+   The public identifier for the external subset of the document type
+   definition.  This will be a string or \code{None}.
+ \end{memberdesc}
+
+ \begin{memberdesc}[DocumentType]{systemId}
+   The system identifier for the external subset of the document type
+   definition.  This will be a URI as a string, or \code{None}.
+ \end{memberdesc}
+
+ \begin{memberdesc}[DocumentType]{internalSubset}
+   A string giving the complete internal subset from the document.
+ \end{memberdesc}
+
+ \begin{memberdesc}[DocumentType]{name}
+   The name of the root element as given in the \code{DOCTYPE}
+   declaration, if present.  If the was no \code{DOCTYPE} declaration,
+   this will be \code{None}.
+ \end{memberdesc}
+
+ \begin{memberdesc}[DocumentType]{entities}
+   This is a \class{NamedNodeMap} giving the definitions of external
+   entities.  For entity names defined more than once, only the first
+   definition is provided (others are ignored as required by the XML
+   recommendation).  This may be \code{None} if the information is not
+   provided by the parser, or if no entities are defined.
+ \end{memberdesc}
+
+ \begin{memberdesc}[DocumentType]{notations}
+   This is a \class{NamedNodeMap} giving the definitions of notations.
+   For notation names defined more than once, only the first definition
+   is provided (others are ignored as required by the XML
+   recommendation).  This may be \code{None} if the information is not
+   provided by the parser, or if no notations are defined.
+ \end{memberdesc}

+
\subsubsection{Document Objects \label{dom-document-objects}}

***************
*** 233,270 ****

\begin{methoddesc}[Document]{createElement}{tagName}
! Create a new element.  The element is not inserted into the document
! when it is created.  You need to explicitly insert it with one of the
! other methods such as \method{insertBefore()} or
\method{appendChild()}.
\end{methoddesc}

\begin{methoddesc}[Document]{createElementNS}{namespaceURI, tagName}
! Create a new element with a namespace.  The \var{tagName} may have a
! prefix.  The element is not inserted into the document when it is
! created.  You need to explicitly insert it with one of the other
! methods such as \method{insertBefore()} or \method{appendChild()}.
\end{methoddesc}

\begin{methoddesc}[Document]{createTextNode}{data}
! Create a text node containing the data passed as a parameter.  As with
! the other creation methods, this one does not insert the node into the
! tree.
\end{methoddesc}

\begin{methoddesc}[Document]{createComment}{data}
! Create a comment node containing the data passed as a parameter.  As
! with the other creation methods, this one does not insert the node
! into the tree.
\end{methoddesc}

\begin{methoddesc}[Document]{createProcessingInstruction}{target, data}
! Create a processing instruction node containing the \var{target} and
! \var{data} passed as parameters.  As with the other creation methods,
! this one does not insert the node into the tree.
\end{methoddesc}

\begin{methoddesc}[Document]{createAttribute}{name}
! Create an attribute node.  This method does not associate the
! attribute node with any particular element.  You must use
\method{setAttributeNode()} on the appropriate \class{Element} object
to use the newly created attribute instance.
--- 342,380 ----

\begin{methoddesc}[Document]{createElement}{tagName}
! Create and return a new element node.  The element is not inserted
! into the document when it is created.  You need to explicitly insert
! it with one of the other methods such as \method{insertBefore()} or
\method{appendChild()}.
\end{methoddesc}

\begin{methoddesc}[Document]{createElementNS}{namespaceURI, tagName}
! Create and return a new element with a namespace.  The
! \var{tagName} may have a prefix.  The element is not inserted into the
! document when it is created.  You need to explicitly insert it with
! one of the other methods such as \method{insertBefore()} or
! \method{appendChild()}.
\end{methoddesc}

\begin{methoddesc}[Document]{createTextNode}{data}
! Create and return a text node containing the data passed as a
! parameter.  As with the other creation methods, this one does not
! insert the node into the tree.
\end{methoddesc}

\begin{methoddesc}[Document]{createComment}{data}
! Create and return a comment node containing the data passed as a
! parameter.  As with the other creation methods, this one does not
! insert the node into the tree.
\end{methoddesc}

\begin{methoddesc}[Document]{createProcessingInstruction}{target, data}
! Create and return a processing instruction node containing the
! \var{target} and \var{data} passed as parameters.  As with the other
! creation methods, this one does not insert the node into the tree.
\end{methoddesc}

\begin{methoddesc}[Document]{createAttribute}{name}
! Create and return an attribute node.  This method does not associate
! the attribute node with any particular element.  You must use
\method{setAttributeNode()} on the appropriate \class{Element} object
to use the newly created attribute instance.
***************
*** 272,280 ****

\begin{methoddesc}[Document]{createAttributeNS}{namespaceURI, qualifiedName}
! Create an attribute node with a namespace.  The \var{tagName} may have
! a prefix.  This method does not associate the attribute node with any
! particular element. You must use \method{setAttributeNode()} on the
! appropriate \class{Element} object to use the newly created attribute
! instance.
\end{methoddesc}

--- 382,390 ----

\begin{methoddesc}[Document]{createAttributeNS}{namespaceURI, qualifiedName}
! Create and return an attribute node with a namespace.  The
! \var{tagName} may have a prefix.  This method does not associate the
! attribute node with any particular element.  You must use
! \method{setAttributeNode()} on the appropriate \class{Element} object
! to use the newly created attribute instance.
\end{methoddesc}

***************
*** 298,316 ****
\begin{memberdesc}[Element]{tagName}
The element type name.  In a namespace-using document it may have
! colons in it.
\end{memberdesc}

\begin{memberdesc}[Element]{localName}
The part of the \member{tagName} following the colon if there is one,
! else the entire \member{tagName}.
\end{memberdesc}

\begin{memberdesc}[Element]{prefix}
The part of the \member{tagName} preceding the colon if there is one,
! else the empty string.
! \end{memberdesc}
!
! \begin{memberdesc}[Element]{namespaceURI}
! The namespace associated with the tagName.
\end{memberdesc}

--- 408,422 ----
\begin{memberdesc}[Element]{tagName}
The element type name.  In a namespace-using document it may have
! colons in it.  The value is a string.
\end{memberdesc}

\begin{memberdesc}[Element]{localName}
The part of the \member{tagName} following the colon if there is one,
! else the entire \member{tagName}.  The value is a string.
\end{memberdesc}

\begin{memberdesc}[Element]{prefix}
The part of the \member{tagName} preceding the colon if there is one,
! else the empty string.  The value is a string, or \code{None}
\end{memberdesc}

***************
*** 319,322 ****
--- 425,432 ----
\end{methoddesc}

+ \begin{methoddesc}[Element]{getAttributeNode}{attrname}
+ Return the \class{Attr} node for the attribute named by \var{attrname}
+ \end{methoddesc}
+
\begin{methoddesc}[Element]{setAttribute}{attname, value}
Set an attribute value from a string.
***************
*** 440,446 ****
IDL mapping for Python.

\subsubsection{Type Mapping \label{dom-type-mapping}}

- XXX  Explain what a \class{DOMString} maps to...

\subsubsection{Accessor Methods \label{dom-accessor-methods}}
--- 550,574 ----
IDL mapping for Python.

+
\subsubsection{Type Mapping \label{dom-type-mapping}}
+
+ The primitive IDL types used in the DOM specification are mapped to
+ Python types according to the following table.
+
+ \begin{tableii}{l|l}{code}{IDL Type}{Python Type}
+   \lineii{boolean}{\code{IntegerType} (with a value of \code{0} or \code{1})}
+   \lineii{int}{\code{IntegerType}}
+   \lineii{long int}{\code{IntegerType}}
+   \lineii{unsigned int}{\code{IntegerType}}
+ \end{tableii}
+
+ Additionally, the \class{DOMString} defined in the recommendation is
+ mapped to a Python string or Unicode string.  Applications should
+ be able to handle Unicode whenever a string is returned from the DOM.
+
+ The IDL \keyword{null} value is mapped to \code{None}, which may be
+ accepted or provided by the implementation whenever \keyword{null} is
+ allowed by the API.

\subsubsection{Accessor Methods \label{dom-accessor-methods}}
***************
*** 477,479 ****
they should take the form defined by the Python IDL mapping, but
these methods are considered unnecessary since the attributes are
! accessible directly from Python.
--- 605,608 ----
they should take the form defined by the Python IDL mapping, but
these methods are considered unnecessary since the attributes are
! accessible directly from Python.  Set'' accessors should never be
! provided for \keyword{readonly} attributes.

Index: xmldomminidom.tex
===================================================================
RCS file: /cvsroot/python/python/dist/src/Doc/lib/xmldomminidom.tex,v
retrieving revision 1.1
retrieving revision 1.2
diff -C2 -r1.1 -r1.2
*** xmldomminidom.tex	2000/11/29 06:10:22	1.1
--- xmldomminidom.tex	2000/12/07 04:47:51	1.2
***************
*** 262,268 ****
list type, so don't support the official API, but are much more
Pythonic.''
-
- \item \class{NamedNodeMap} is implemented by the class
-       \class{AttributeList}.  This should not impact user code.
\end{itemize}

--- 262,265 ----
***************
*** 274,280 ****
\item DOMTimeStamp

! \item DocumentType (added for Python 2.1)

! \item DOMImplementation (added for Python 2.1)

\item CharacterData
--- 271,277 ----
\item DOMTimeStamp

! \item DocumentType (added in Python 2.1)

! \item DOMImplementation (added in Python 2.1)

\item CharacterData