--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/deprecated/buildtools/buildsystemtools/lib/XML/DOM/Element.pod	Wed Oct 27 16:03:51 2010 +0800
@@ -0,0 +1,189 @@
+=head1 NAME
+
+XML::DOM::Element - An XML element node in XML::DOM
+
+=head1 DESCRIPTION
+
+XML::DOM::Element extends L<XML::DOM::Node>.
+
+By far the vast majority of objects (apart from text) that authors
+encounter when traversing a document are Element nodes. Assume the
+following XML document:
+
+     <elementExample id="demo">
+       <subelement1/>
+       <subelement2><subsubelement/></subelement2>
+     </elementExample>
+
+When represented using DOM, the top node is an Element node for
+"elementExample", which contains two child Element nodes, one for
+"subelement1" and one for "subelement2". "subelement1" contains no
+child nodes.
+
+Elements may have attributes associated with them; since the Element
+interface inherits from Node, the generic Node interface method
+getAttributes may be used to retrieve the set of all attributes for an
+element. There are methods on the Element interface to retrieve either
+an Attr object by name or an attribute value by name. In XML, where an
+attribute value may contain entity references, an Attr object should be
+retrieved to examine the possibly fairly complex sub-tree representing
+the attribute value. On the other hand, in HTML, where all attributes
+have simple string values, methods to directly access an attribute
+value can safely be used as a convenience.
+
+=head2 METHODS
+
+=over 4
+
+=item getTagName
+
+The name of the element. For example, in:
+
+               <elementExample id="demo">
+                       ...
+               </elementExample>
+
+tagName has the value "elementExample". Note that this is
+case-preserving in XML, as are all of the operations of the
+DOM.
+
+=item getAttribute (name)
+
+Retrieves an attribute value by name.
+
+Return Value: The Attr value as a string, or the empty string if that
+attribute does not have a specified or default value.
+
+=item setAttribute (name, value)
+
+Adds a new attribute. If an attribute with that name is
+already present in the element, its value is changed to be
+that of the value parameter. This value is a simple string,
+it is not parsed as it is being set. So any markup (such as
+syntax to be recognized as an entity reference) is treated as
+literal text, and needs to be appropriately escaped by the
+implementation when it is written out. In order to assign an
+attribute value that contains entity references, the user
+must create an Attr node plus any Text and EntityReference
+nodes, build the appropriate subtree, and use
+setAttributeNode to assign it as the value of an attribute.
+
+
+DOMExceptions:
+
+=over 4
+
+=item * INVALID_CHARACTER_ERR
+
+Raised if the specified name contains an invalid character.
+
+=item * NO_MODIFICATION_ALLOWED_ERR
+
+Raised if this node is readonly.
+
+=back
+
+=item removeAttribute (name)
+
+Removes an attribute by name. If the removed attribute has a
+default value it is immediately replaced.
+
+DOMExceptions:
+
+=over 4
+
+=item * NO_MODIFICATION_ALLOWED_ERR
+
+Raised if this node is readonly.
+
+=back
+
+=item getAttributeNode
+
+Retrieves an Attr node by name.
+
+Return Value: The Attr node with the specified attribute name or undef
+if there is no such attribute.
+
+=item setAttributeNode (attr)
+
+Adds a new attribute. If an attribute with that name is
+already present in the element, it is replaced by the new one.
+
+Return Value: If the newAttr attribute replaces an existing attribute
+with the same name, the previously existing Attr node is
+returned, otherwise undef is returned.
+
+DOMExceptions:
+
+=over 4
+
+=item * WRONG_DOCUMENT_ERR
+
+Raised if newAttr was created from a different document than the one that created
+the element.
+
+=item * NO_MODIFICATION_ALLOWED_ERR
+
+Raised if this node is readonly.
+
+=item * INUSE_ATTRIBUTE_ERR
+
+Raised if newAttr is already an attribute of another Element object. The DOM
+user must explicitly clone Attr nodes to re-use them in other elements.
+
+=back
+
+=item removeAttributeNode (oldAttr)
+
+Removes the specified attribute. If the removed Attr has a default value it is
+immediately replaced. If the Attr already is the default value, nothing happens
+and nothing is returned.
+
+Parameters:
+ I<oldAttr>  The Attr node to remove from the attribute list. 
+
+Return Value: The Attr node that was removed.
+
+DOMExceptions:
+
+=over 4
+
+=item * NO_MODIFICATION_ALLOWED_ERR
+
+Raised if this node is readonly.
+
+=item * NOT_FOUND_ERR
+
+Raised if oldAttr is not an attribute of the element.
+
+=back
+
+=head2 Additional methods not in the DOM Spec
+
+=over 4
+
+=item setTagName (newTagName)
+
+Sets the tag name of the Element. Note that this method is not portable
+between DOM implementations.
+
+DOMExceptions:
+
+=over 4
+
+=item * INVALID_CHARACTER_ERR
+
+Raised if the specified name contains an invalid character.
+
+=back
+
+=item check ($checker)
+
+Uses the specified L<XML::Checker> to validate the document.
+NOTE: an XML::Checker must be supplied. The checker can be created in
+different ways, e.g. when parsing a document with XML::DOM::ValParser,
+or with XML::DOM::Document::createChecker().
+See L<XML::Checker> for more info.
+
+=back