--- rest25/library/xml.dom.rst	2008-12-19 16:58:07.000000000 +0900
+++ rest262/library/xml.dom.rst	2009-04-07 00:06:53.000000000 +0900
@@ -22,74 +22,72 @@
 have no access to a containing element. When you write a SAX application, you
 need to keep track of your program's position in the document somewhere in your
 own code.  SAX does not do it for you.  Also, if you need to look ahead in the
 XML document, you are just out of luck.
 
 Some applications are simply impossible in an event driven model with no access
 to a tree.  Of course you could build some sort of tree yourself in SAX events,
 but the DOM allows you to avoid writing that code.  The DOM is a standard tree
 representation for XML data.
 
 The Document Object Model is being defined by the W3C in stages, or "levels" in
 their terminology.  The Python mapping of the API is substantially based on the
-DOM Level 2 recommendation.  The mapping of the Level 3 specification, currently
-only available in draft form, is being developed by the `Python XML Special
-Interest Group <http://www.python.org/sigs/xml-sig/>`_ as part of the `PyXML
-package <http://pyxml.sourceforge.net/>`_.  Refer to the documentation bundled
-with that package for information on the current state of DOM Level 3 support.
-
-.. % What if your needs are somewhere between SAX and the DOM?  Perhaps
-.. % you cannot afford to load the entire tree in memory but you find the
-.. % SAX model somewhat cumbersome and low-level.  There is also a module
-.. % called xml.dom.pulldom that allows you to build trees of only the
-.. % parts of a document that you need structured access to.  It also has
-.. % features that allow you to find your way around the DOM.
-.. % See http://www.prescod.net/python/pulldom
+DOM Level 2 recommendation.
+
+.. XXX PyXML is dead...
+.. The mapping of the Level 3 specification, currently
+   only available in draft form, is being developed by the `Python XML Special
+   Interest Group <http://www.python.org/sigs/xml-sig/>`_ as part of the `PyXML
+   package <http://pyxml.sourceforge.net/>`_.  Refer to the documentation bundled
+   with that package for information on the current state of DOM Level 3 support.
+
+.. What if your needs are somewhere between SAX and the DOM?  Perhaps
+   you cannot afford to load the entire tree in memory but you find the
+   SAX model somewhat cumbersome and low-level.  There is also a module
+   called xml.dom.pulldom that allows you to build trees of only the
+   parts of a document that you need structured access to.  It also has
+   features that allow you to find your way around the DOM.
+   See http://www.prescod.net/python/pulldom
 
 DOM applications typically start by parsing some XML into a DOM.  How this is
 accomplished is not covered at all by DOM Level 1, and Level 2 provides only
 limited improvements: There is a :class:`DOMImplementation` object class which
 provides access to :class:`Document` creation methods, but no way to access an
 XML reader/parser/Document builder in an implementation-independent way. There
 is also no well-defined way to access these methods without an existing
 :class:`Document` object.  In Python, each DOM implementation will provide a
 function :func:`getDOMImplementation`. DOM Level 3 adds a Load/Store
 specification, which defines an interface to the reader, but this is not yet
 available in the Python standard library.
 
 Once you have a DOM document object, you can access the parts of your XML
 document through its properties and methods.  These properties are defined in
 the DOM specification; this portion of the reference manual describes the
 interpretation of the specification in Python.
 
 The specification provided by the W3C defines the DOM API for Java, ECMAScript,
 and OMG IDL.  The Python mapping defined here is based in large part on the IDL
 version of the specification, but strict compliance is not required (though
 implementations are free to support the strict mapping from IDL).  See section
-:ref:`dom-conformance`, "Conformance," for a detailed discussion of mapping
-requirements.
+:ref:`dom-conformance` for a detailed discussion of mapping requirements.
 
 
 .. seealso::
 
    `Document Object Model (DOM) Level 2 Specification <http://www.w3.org/TR/DOM-Level-2-Core/>`_
       The W3C recommendation upon which the Python DOM API is based.
 
    `Document Object Model (DOM) Level 1 Specification <http://www.w3.org/TR/REC-DOM-Level-1/>`_
       The W3C recommendation for the DOM supported by :mod:`xml.dom.minidom`.
 
-   `PyXML <http://pyxml.sourceforge.net>`_
-      Users that require a full-featured implementation of DOM should use the PyXML
-      package.
-
    `Python Language Mapping Specification <http://www.omg.org/docs/formal/02-11-05.pdf>`_
       This specifies the mapping from OMG IDL to Python.
 
 
 Module Contents
 ---------------
 
 The :mod:`xml.dom` contains the following functions:
 
 
 .. function:: registerDOMImplementation(name, factory)
 
@@ -128,94 +126,94 @@
 
 .. data:: XML_NAMESPACE
 
    The namespace URI associated with the reserved prefix ``xml``, as defined by
    `Namespaces in XML <http://www.w3.org/TR/REC-xml-names/>`_ (section 4).
 
    .. versionadded:: 2.2
 
 
 .. data:: XMLNS_NAMESPACE
 
    The namespace URI for namespace declarations, as defined by `Document Object
-   Model (DOM) Level 2 Core Specification <http://www.w3.org/TR/DOM-
-   Level-2-Core/core.html>`_ (section 1.1.8).
+   Model (DOM) Level 2 Core Specification
+   <http://www.w3.org/TR/DOM-Level-2-Core/core.html>`_ (section 1.1.8).
 
    .. versionadded:: 2.2
 
 
 .. data:: XHTML_NAMESPACE
 
    The URI of the XHTML namespace as defined by `XHTML 1.0: The Extensible
    HyperText Markup Language <http://www.w3.org/TR/xhtml1/>`_ (section 3.1.1).
 
    .. versionadded:: 2.2
 
 In addition, :mod:`xml.dom` contains a base :class:`Node` class and the DOM
 exception classes.  The :class:`Node` class provided by this module does not
 implement any of the methods or attributes defined by the DOM specification;
 concrete DOM implementations must provide those.  The :class:`Node` class
 provided as part of this module does provide the constants used for the
 :attr:`nodeType` attribute on concrete :class:`Node` objects; they are located
 within the class rather than at the module level to conform with the DOM
 specifications.
 
-.. % Should the Node documentation go here?
+.. Should the Node documentation go here?
 
 
 .. _dom-objects:
 
 Objects in the DOM
 ------------------
 
 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 as simple
 strings.  It is fairly rare that you must do this, however, so this usage is not
 yet documented.
 
-+--------------------------------+---------------------------------+---------------------------------+
-| Interface                      | Section                         | Purpose                         |
-+================================+=================================+=================================+
-| :class:`DOMImplementation`     | :ref:`dom-implementation-       | Interface to the underlying     |
-|                                | objects`                        | implementation.                 |
-+--------------------------------+---------------------------------+---------------------------------+
-| :class:`Node`                  | :ref:`dom-node-objects`         | Base interface for most objects |
-|                                |                                 | in a document.                  |
-+--------------------------------+---------------------------------+---------------------------------+
-| :class:`NodeList`              | :ref:`dom-nodelist-objects`     | Interface for a sequence of     |
-|                                |                                 | nodes.                          |
-+--------------------------------+---------------------------------+---------------------------------+
-| :class:`DocumentType`          | :ref:`dom-documenttype-objects` | Information about the           |
-|                                |                                 | declarations needed to process  |
-|                                |                                 | a document.                     |
-+--------------------------------+---------------------------------+---------------------------------+
-| :class:`Document`              | :ref:`dom-document-objects`     | Object which represents an      |
-|                                |                                 | entire document.                |
-+--------------------------------+---------------------------------+---------------------------------+
-| :class:`Element`               | :ref:`dom-element-objects`      | Element nodes in the document   |
-|                                |                                 | hierarchy.                      |
-+--------------------------------+---------------------------------+---------------------------------+
-| :class:`Attr`                  | :ref:`dom-attr-objects`         | Attribute value nodes on        |
-|                                |                                 | element nodes.                  |
-+--------------------------------+---------------------------------+---------------------------------+
-| :class:`Comment`               | :ref:`dom-comment-objects`      | Representation of comments in   |
-|                                |                                 | the source document.            |
-+--------------------------------+---------------------------------+---------------------------------+
-| :class:`Text`                  | :ref:`dom-text-objects`         | Nodes containing textual        |
-|                                |                                 | content from the document.      |
-+--------------------------------+---------------------------------+---------------------------------+
-| :class:`ProcessingInstruction` | :ref:`dom-pi-objects`           | Processing instruction          |
-|                                |                                 | representation.                 |
-+--------------------------------+---------------------------------+---------------------------------+
++--------------------------------+-----------------------------------+---------------------------------+
+| Interface                      | Section                           | Purpose                         |
++================================+===================================+=================================+
+| :class:`DOMImplementation`     | :ref:`dom-implementation-objects` | Interface to the underlying     |
+|                                |                                   | implementation.                 |
++--------------------------------+-----------------------------------+---------------------------------+
+| :class:`Node`                  | :ref:`dom-node-objects`           | Base interface for most objects |
+|                                |                                   | in a document.                  |
++--------------------------------+-----------------------------------+---------------------------------+
+| :class:`NodeList`              | :ref:`dom-nodelist-objects`       | Interface for a sequence of     |
+|                                |                                   | nodes.                          |
++--------------------------------+-----------------------------------+---------------------------------+
+| :class:`DocumentType`          | :ref:`dom-documenttype-objects`   | Information about the           |
+|                                |                                   | declarations needed to process  |
+|                                |                                   | a document.                     |
++--------------------------------+-----------------------------------+---------------------------------+
+| :class:`Document`              | :ref:`dom-document-objects`       | Object which represents an      |
+|                                |                                   | entire document.                |
++--------------------------------+-----------------------------------+---------------------------------+
+| :class:`Element`               | :ref:`dom-element-objects`        | Element nodes in the document   |
+|                                |                                   | hierarchy.                      |
++--------------------------------+-----------------------------------+---------------------------------+
+| :class:`Attr`                  | :ref:`dom-attr-objects`           | Attribute value nodes on        |
+|                                |                                   | element nodes.                  |
++--------------------------------+-----------------------------------+---------------------------------+
+| :class:`Comment`               | :ref:`dom-comment-objects`        | Representation of comments in   |
+|                                |                                   | the source document.            |
++--------------------------------+-----------------------------------+---------------------------------+
+| :class:`Text`                  | :ref:`dom-text-objects`           | Nodes containing textual        |
+|                                |                                   | content from the document.      |
++--------------------------------+-----------------------------------+---------------------------------+
+| :class:`ProcessingInstruction` | :ref:`dom-pi-objects`             | Processing instruction          |
+|                                |                                   | representation.                 |
++--------------------------------+-----------------------------------+---------------------------------+
 
 An additional section describes the exceptions defined for working with the DOM
 in Python.
 
 
 .. _dom-implementation-objects:
 
 DOMImplementation Objects
 ^^^^^^^^^^^^^^^^^^^^^^^^^
 
 The :class:`DOMImplementation` interface provides a way for applications to
 determine the availability of particular features in the DOM they are using.
@@ -273,30 +271,30 @@
    ``None``. This is a read-only attribute.
 
 
 .. attribute:: Node.attributes
 
    A :class:`NamedNodeMap` of attribute objects.  Only elements have actual values
    for this; others provide ``None`` for this attribute. This is a read-only
    attribute.
 
 
 .. attribute:: Node.previousSibling
 
-   The node that immediately precedes this one with the same parent.  For instance
-   the element with an end-tag that comes just before the *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 ``None``. This is a read-
-   only attribute.
+   The node that immediately precedes this one with the same parent.  For
+   instance the element with an end-tag that comes just before the *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
+   ``None``. This is a read-only attribute.
 
 
 .. attribute:: Node.nextSibling
 
    The node that immediately follows this one with the same parent.  See also
    :attr:`previousSibling`.  If this is the last child of the parent, this
    attribute will be ``None``. This is a read-only attribute.
 
 
 .. attribute:: Node.childNodes
 
    A list of nodes contained within this node. This is a read-only attribute.
@@ -365,26 +363,27 @@
    more than one object can refer to the same node).
 
    .. note::
 
       This is based on a proposed DOM Level 3 API which is still in the "working
       draft" stage, but this particular interface appears uncontroversial.  Changes
       from the W3C will not necessarily affect this method in the Python DOM interface
       (though any new W3C API for this would also be supported).
 
 
 .. method:: Node.appendChild(newChild)
 
-   Add a new child node to this node at the end of the list of children, returning
-   *newChild*.
+   Add a new child node to this node at the end of the list of
+   children, returning *newChild*. If the node was already in
+   in the tree, it is removed first.
 
 
 .. method:: Node.insertBefore(newChild, refChild)
 
    Insert a new child node before an existing child.  It must be the case that
    *refChild* is a child of this node; if not, :exc:`ValueError` is raised.
    *newChild* is returned. If *refChild* is ``None``, it inserts *newChild* at the
    end of the children's list.
 
 
 .. method:: Node.removeChild(oldChild)
 
@@ -509,25 +508,25 @@
    notation names defined more than once, only the first definition is provided
    (others are ignored as required by the XML recommendation).  This may be
    ``None`` if the information is not provided by the parser, or if no notations
    are defined.
 
 
 .. _dom-document-objects:
 
 Document Objects
 ^^^^^^^^^^^^^^^^
 
 A :class:`Document` represents an entire XML document, including its constituent
-elements, attributes, processing instructions, comments etc.  Remeber that it
+elements, attributes, processing instructions, comments etc.  Remember that it
 inherits properties from :class:`Node`.
 
 
 .. attribute:: Document.documentElement
 
    The one and only root element of the document.
 
 
 .. method:: 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
@@ -603,25 +602,25 @@
 
 .. attribute:: Element.tagName
 
    The element type name.  In a namespace-using document it may have colons in it.
    The value is a string.
 
 
 .. method:: Element.getElementsByTagName(tagName)
 
    Same as equivalent method in the :class:`Document` class.
 
 
-.. method:: Element.getElementsByTagNameNS(tagName)
+.. method:: Element.getElementsByTagNameNS(namespaceURI, localName)
 
    Same as equivalent method in the :class:`Document` class.
 
 
 .. method:: Element.hasAttribute(name)
 
    Returns true if the element has an attribute named by *name*.
 
 
 .. method:: Element.hasAttributeNS(namespaceURI, localName)
 
    Returns true if the element has an attribute named by *namespaceURI* and
@@ -644,26 +643,26 @@
    Return the value of the attribute named by *namespaceURI* and *localName* as a
    string. If no such attribute exists, an empty string is returned, as if the
    attribute had no value.
 
 
 .. method:: Element.getAttributeNodeNS(namespaceURI, localName)
 
    Return an attribute value as a node, given a *namespaceURI* and *localName*.
 
 
 .. method:: Element.removeAttribute(name)
 
-   Remove an attribute by name.  No exception is raised if there is no matching
-   attribute.
+   Remove an attribute by name.  If there is no matching attribute, a
+   :exc:`NotFoundErr` is raised.
 
 
 .. method:: Element.removeAttributeNode(oldAttr)
 
    Remove and return *oldAttr* from the attribute list, if present. If *oldAttr* is
    not present, :exc:`NotFoundErr` is raised.
 
 
 .. method:: Element.removeAttributeNS(namespaceURI, localName)
 
    Remove an attribute by name.  Note that it uses a localName, not a qname.  No
    exception is raised if there is no matching attribute.
@@ -898,38 +897,38 @@
 
 
 .. exception:: NotSupportedErr
 
    Raised when the implementation does not support the requested type of object or
    operation.
 
 
 .. exception:: NoDataAllowedErr
 
    This is raised if data is specified for a node which does not support data.
 
-   .. % XXX  a better explanation is needed!
+   .. XXX  a better explanation is needed!
 
 
 .. exception:: NoModificationAllowedErr
 
    Raised on attempts to modify an object where modifications are not allowed (such
    as for read-only nodes).
 
 
 .. exception:: SyntaxErr
 
    Raised when an invalid or illegal string is specified.
 
-   .. % XXX  how is this different from InvalidCharacterErr ???
+   .. XXX  how is this different from InvalidCharacterErr?
 
 
 .. exception:: WrongDocumentErr
 
    Raised when a node is inserted in a different document than it currently belongs
    to, and the implementation does not support migrating the node from one document
    to the other.
 
 The exception codes defined in the DOM recommendation map to the exceptions
 described above according to this table:
 
 +--------------------------------------+---------------------------------+
@@ -993,54 +992,54 @@
 +------------------+-------------------------------------------+
 | ``int``          | ``IntegerType``                           |
 +------------------+-------------------------------------------+
 | ``long int``     | ``IntegerType``                           |
 +------------------+-------------------------------------------+
 | ``unsigned int`` | ``IntegerType``                           |
 +------------------+-------------------------------------------+
 
 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 ``None``, which may be accepted or
-provided by the implementation whenever :keyword:`null` is allowed by the API.
+The IDL ``null`` value is mapped to ``None``, which may be accepted or
+provided by the implementation whenever ``null`` is allowed by the API.
 
 
 .. _dom-accessor-methods:
 
 Accessor Methods
 ^^^^^^^^^^^^^^^^
 
 The mapping from OMG IDL to Python defines accessor functions for IDL
-:keyword:`attribute` declarations in much the way the Java mapping does.
+``attribute`` declarations in much the way the Java mapping does.
 Mapping the IDL declarations ::
 
    readonly attribute string someValue;
             attribute string anotherValue;
 
 yields three accessor functions:  a "get" method for :attr:`someValue`
 (:meth:`_get_someValue`), and "get" and "set" methods for :attr:`anotherValue`
 (:meth:`_get_anotherValue` and :meth:`_set_anotherValue`).  The mapping, in
 particular, does not require that the IDL attributes are accessible as normal
 Python attributes:  ``object.someValue`` is *not* required to work, and may
 raise an :exc:`AttributeError`.
 
 The Python DOM API, however, *does* require that normal attribute access work.
 This means that the typical surrogates generated by Python IDL compilers are not
 likely to work, and wrapper objects may be needed on the client if the DOM
 objects are accessed via CORBA. While this does require some additional
 consideration for CORBA DOM clients, the implementers with experience using DOM
 over CORBA from Python do not consider this a problem.  Attributes that are
-declared :keyword:`readonly` may not restrict write access in all DOM
+declared ``readonly`` may not restrict write access in all DOM
 implementations.
 
 In the Python DOM API, accessor functions are not required.  If provided, 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.
+"Set" accessors should never be provided for ``readonly`` attributes.
 
 The IDL definitions do not fully embody the requirements of the W3C DOM API,
 such as the notion of certain objects, such as the return value of
 :meth:`getElementsByTagName`, being "live".  The Python DOM API does not require
 implementations to enforce such requirements.
 
