<?xml version="1.0" encoding="UTF-8"?>

<!--[ Document object description ]-->    
<interface name="Document" inherits="Node" id="i-Document">
  <descr><p>The <code>Document</code> interface represents the entire
      HTML or XML document. Conceptually, it is the <termref def="dt-root-node">root</termref> of the
      document tree, and provides the  primary access to the
      document's data.</p>
    <p>Since elements, text nodes, comments, processing instructions,
      etc. cannot exist outside the context of a <code>Document</code>, the
      <code>Document</code> interface also contains the factory methods needed
      to create these objects. The <code>Node</code> objects created have a
      <code>ownerDocument</code> attribute which associates them with the
      <code>Document</code> within whose context they were created.</p>
  </descr>
  <attribute readonly="yes" name="doctype" type="DocumentType"
    id="ID-B63ED1A31">
    <descr><p>The Document Type Declaration (see <code>DocumentType</code>)
	associated with this document. For HTML documents as well as XML
	documents without a document type declaration this returns
	<code>null</code>. The DOM Level 2 does not support editing the
	Document Type Declaration. <code>docType</code> cannot be
	altered in any way, including through the use of methods inherited from
	the <code>Node</code> interface, such as <code>insertNode</code> or
        <code>removeNode</code>.</p>
    </descr> 
  </attribute>
  <attribute readonly="yes" name="implementation" type="DOMImplementation"
    id="ID-1B793EBA">
    <descr><p>The <code>DOMImplementation</code> object that handles this
	document. A DOM application may use objects from multiple 
        implementations.</p>
    </descr> 
  </attribute>
  
  <attribute readonly="yes" name="documentElement" type="Element"
    id="ID-87CD092">
    <descr><p>This is a <termref def="dt-convenience">convenience</termref> attribute that allows direct
	access to the child node that is the root element of  the
	document. For HTML documents, this is the element with
	the tagName "HTML".</p></descr> 
  </attribute>
  <!-- ********** -->
  <method name="createElement" id="ID-2141741547">
    <descr><p>Creates an element of the type specified. Note that the instance
	returned implements the <code>Element</code> interface, so attributes
	  can be specified directly  on the returned object.</p>
      <p>In addition, if there are known attributes with default values,
	<code>Attr</code> nodes representing them are automatically created and
	attached to the element.</p>
      <p>To create an element with a qualified name and namespace URI, use the
	<code>createElementNS</code> method.</p>
    </descr>
    <parameters>
      <param name="tagName" type="DOMString" attr="in">
	<descr><p>The name of the element type to
	    instantiate. For XML, this is case-sensitive. For HTML, the 
            <code>tagName</code> parameter may be provided in any case, 
            but it must be mapped to the canonical uppercase form by 
            the DOM implementation.
        </p></descr>
      </param>
    </parameters>
    <returns type="Element">
      <descr><p>A new <code>Element</code> object with the
        <code>nodeName</code> attribute set to <code>tagName</code>, and
        <code>localName</code>, <code>prefix</code>, and
        <code>namespaceURI</code> set to <code>null</code>.</p></descr>
    </returns>
    <raises>
      <exception name="DOMException">
        <descr><p>INVALID_CHARACTER_ERR: Raised if the specified name contains
	an illegal character.</p></descr>
      </exception>
    </raises>
  </method>
  
  <!-- ********** -->
  <method name="createDocumentFragment" id="ID-35CB04B5">
    <descr><p>Creates an empty <code>DocumentFragment</code> object.
      </p></descr>
    <parameters>
      <!-- No parameters -->
    </parameters>
    <returns type="DocumentFragment">
      <descr><p>A new <code>DocumentFragment</code>.</p></descr>
    </returns>
    <raises>
      <!-- Throws no exceptions -->
    </raises>
  </method>

  <!-- ********** -->
  <method name="createTextNode" id="ID-1975348127">
    <descr><p>Creates a <code>Text</code> node given the specified
	string.</p></descr> 
    <parameters>
      <param name="data" type="DOMString" attr="in">
	<descr><p>The data for the node.</p></descr>
      </param>
    </parameters>
    <returns type="Text">
      <descr><p>The new <code>Text</code> object.</p></descr>
    </returns>
    <raises>
      <!-- Throws no exceptions -->
    </raises>
  </method>
  <!-- ********** -->
  <method name="createComment" id="ID-1334481328">
    <descr><p>Creates a <code>Comment</code> node given the specified
	string.</p></descr> 
    <parameters>
      <param name="data" type="DOMString" attr="in">
	<descr><p>The data for the node.</p></descr>
      </param>
    </parameters>
    <returns type="Comment">
      <descr><p>The new <code>Comment</code> object.</p></descr>
    </returns>
    <raises>
      <!-- Throws no exceptions -->
    </raises>
  </method>
  <!-- ********** -->
  <method name="createCDATASection" id="ID-D26C0AF8">
    <descr><p>Creates a <code>CDATASection</code> node whose value  is
	the specified string.</p></descr> 
    <parameters>
      <param name="data" type="DOMString" attr="in">
	<descr><p>The data for the <code>CDATASection</code> contents.</p>
	</descr>
      </param>
    </parameters>
    <returns type="CDATASection">
      <descr><p>The new <code>CDATASection</code> object.</p></descr>
    </returns>
    <raises>
      <exception name="DOMException">
        <descr><p>NOT_SUPPORTED_ERR: Raised if this document is an HTML
	document.</p></descr>
      </exception>
    </raises>
  </method>
  <!-- ********** -->
  <method name="createProcessingInstruction" id="ID-135944439">
    <descr><p>Creates a <code>ProcessingInstruction</code> node given
	the specified name and data strings.</p></descr> 
    <parameters>
      <param name="target" type="DOMString" attr="in">
	<descr><p>The target part of the processing instruction.</p></descr>
      </param>
      <param name="data" type="DOMString" attr="in">
	<descr><p>The data for the node.</p></descr>
      </param>
    </parameters>
    <returns type="ProcessingInstruction">
      <descr><p>The new <code>ProcessingInstruction</code> object.</p></descr>
    </returns>
    <raises>
      <exception name="DOMException">
        <descr><p>INVALID_CHARACTER_ERR: Raised if the specified target
	    contains an illegal character.</p>
	<p>NOT_SUPPORTED_ERR: Raised if this document is an HTML document.</p>
	</descr>
      </exception>
    </raises>
  </method>
  <!-- ********** -->
  <method name="createAttribute" id="ID-1084891198">
    <descr><p>Creates an <code>Attr</code> of the given name.
	Note that the <code>Attr</code> instance
	can then be set on an <code>Element</code> using the
	<code>setAttributeNode</code> method. </p>
      <p>To create an attribute with a qualified name and namespace URI, use
	the <code>createAttributeNS</code> method.</p>
    </descr>
    <parameters>
      <param name="name" type="DOMString" attr="in">
	<descr><p>The name of the attribute.</p></descr>
      </param>
    </parameters>
    <returns type="Attr">
      <descr><p>A new <code>Attr</code> object with the <code>nodeName</code>
        attribute set to <code>name</code>, and <code>localName</code>,
        <code>prefix</code>, and <code>namespaceURI</code> set to
        <code>null</code>. The value of the attribute is the empty
          string.</p></descr>
    </returns>
    <raises>
      <exception name="DOMException">
        <descr><p>INVALID_CHARACTER_ERR: Raised if the specified name contains
	an illegal character.</p></descr>
      </exception>
    </raises>
  </method>


  <method name="createEntityReference" id="ID-392B75AE">
    <descr><p>Creates an <code>EntityReference</code> object. In addition, if
	the referenced entity is known, the child list of the
	<code>EntityReference</code> node is made the same as that of the
	corresponding <code>Entity</code> node.</p>
	<note><p>If any descendant of the <code>Entity</code> node has an
	  unbound <termref def='dt-namespaceprefix'>namespace prefix</termref>,
	  the corresponding descendant of the created
	  <code>EntityReference</code> node is also unbound; (its
	  <code>namespaceURI</code> is <code>null</code>). The DOM Level 2 does
	  not support any mechanism to resolve namespace prefixes.</p></note>
    </descr>
    <parameters>
      <param name="name" type="DOMString" attr="in">
	<descr><p>The name of the entity to reference. </p>
        </descr>
      </param>
    </parameters>
    <returns type="EntityReference">
      <descr><p>The new <code>EntityReference</code> object.</p></descr>
    </returns>
    <raises>
      <exception name="DOMException">
	<descr><p>INVALID_CHARACTER_ERR: Raised if the specified name contains
	an illegal character.</p>
	<p>NOT_SUPPORTED_ERR: Raised if this document is an HTML document.</p>
	</descr>
      </exception>
    </raises>
  </method>

  <!-- ********** -->
  <method name="getElementsByTagName" id="ID-A6C9094">
    <descr><p>Returns a <code>NodeList</code> of all the <code>Elements</code>
	with a given tag name in the order in which they are encountered
        in a preorder traversal of the <code>Document</code> tree.
      </p></descr>
    <parameters>
      <param name="tagname" type="DOMString" attr="in">
	<descr><p>The name of the tag to match on. The special value "*"
	    matches all tags.</p></descr>
      </param>
    </parameters>
    <returns type="NodeList">
      <descr><p>A new <code>NodeList</code> object containing
	  all the matched <code>Elements</code>.</p></descr>
    </returns>
    <raises>
      <!-- Throws no exceptions -->
    </raises>
  </method>

  <!-- ****** DOM Level 2 additions ****** -->
  <method name="importNode" id="Core-Document-importNode" since="DOM Level 2">
    <descr>
      <p>Imports a node from another document to this document. The returned
	node has no parent; (<code>parentNode</code> is <code>null</code>). The
	source node is not altered or removed from the original document; this
	method creates a new copy of the source node.</p>

      <p>For all nodes, importing a node creates a node object owned by the
	importing document, with attribute values identical to the source
	node's <code>nodeName</code> and <code>nodeType</code>, plus the
	attributes related to namespaces (<code>prefix</code>,
	<code>localName</code>, and <code>namespaceURI</code>). As in the
	<code>cloneNode</code> operation on a <code>Node</code>, the source
	node is not altered.</p>

      <p>Additional information is copied as appropriate to the
	<code>nodeType</code>, attempting to mirror the behavior expected if a
	fragment of XML or HTML source was copied from one document to another,
	recognizing that the two documents may have different DTDs in the XML
	case. The following list describes the specifics for each type of
	node.

	<glist>
	  <gitem>
	    <label>ATTRIBUTE_NODE</label>

	    <def><p>The <code>ownerElement</code> attribute is set to
                <code>null</code> and the <code>specified</code> flag is set to
		<code>true</code> on the generated <code>Attr</code>. The
		<termref def="dt-descendant">descendants</termref> of the source <code>Attr</code> are recursively
		imported and the resulting nodes reassembled to form the
		corresponding subtree.</p>
	      <p>Note that the <code>deep</code> parameter has no effect on 
		<code>Attr</code> nodes; they always carry their children with
		them when imported.</p>
	    </def>
	  </gitem>
	  <gitem>
	    <label>DOCUMENT_FRAGMENT_NODE</label>
	    <def><p>If the <code>deep</code> option was set to
                <code>true</code>, the <termref def="dt-descendant">descendants</termref> of the source element are
                recursively imported and the resulting nodes reassembled to
                form the corresponding subtree. Otherwise, this simply
                generates an empty <code>DocumentFragment</code>.</p>
	    </def>
	  </gitem>
	  <gitem>
	    <label>DOCUMENT_NODE</label>
	    <def><p><code>Document</code> nodes cannot be imported.</p>
	    </def>
	  </gitem>
	  <gitem>
	    <label>DOCUMENT_TYPE_NODE</label>
	    <def><p><code>DocumentType</code> nodes cannot be imported.</p>
	    </def>
	  </gitem>
	  <gitem>
	    <label>ELEMENT_NODE</label>
	    <def><p><emph>Specified</emph> attribute nodes of the source
		element are imported, and the generated <code>Attr</code> nodes
		are attached to the generated <code>Element</code>. Default
		attributes are <emph>not</emph> copied, though if the document
		being imported into defines default attributes for this element
		name, those are assigned. If the <code>importNode</code>
		<code>deep</code> parameter was set to <code>true</code>, the
		<termref def="dt-descendant">descendants</termref> of the source element are recursively imported
		and the resulting nodes reassembled to form the corresponding
		subtree.</p>
	    </def>
	  </gitem>
	  <gitem>
	    <label>ENTITY_NODE</label>
	    <def><p><code>Entity</code> nodes can be imported, however in the
		current release of the DOM the <code>DocumentType</code> is
		readonly. Ability to add these imported nodes to a
		<code>DocumentType</code> will be considered for addition to a
		future release of the DOM.</p>
	      <p>On import, the <code>publicId</code>, <code>systemId</code>,
		and <code>notationName</code> attributes are copied. If a
		<code>deep</code> import is requested, the <termref def="dt-descendant">descendants</termref> of the
		the source <code>Entity</code> are recursively imported and the
		resulting nodes reassembled to form the corresponding
		subtree.</p>
	    </def>
	  </gitem>
	  <gitem>
	    <label>ENTITY_REFERENCE_NODE</label>
	    <def><p>Only the <code>EntityReference</code> itself is copied,
		even if a <code>deep</code> import is requested, since the
		source and destination documents might have defined the entity
		differently. If the document being imported into provides a
		definition for this entity name, its value is assigned.</p>
	    </def>
	  </gitem>
	  <gitem>
	    <label>NOTATION_NODE</label>
	    <def><p><code>Notation</code> nodes can be imported, however in the
		current release of the DOM the <code>DocumentType</code> is
		readonly. Ability to add these imported nodes to a
		<code>DocumentType</code> will be considered for addition to a
		future release of the DOM.</p>
	      <p>On import, the <code>publicId</code> and
		<code>systemId</code> attributes are copied.</p>
	      <p>Note that the <code>deep</code> parameter has no effect on 
		<code>Notation</code> nodes since they never have any
		children.</p>
	    </def>
	  </gitem>
	  <gitem>
	    <label>PROCESSING_INSTRUCTION_NODE</label>
	    <def><p>The imported node copies its <code>target</code> and
		<code>data</code> values from those of the source node.</p>
	    </def>
	  </gitem>
	  <gitem>
	    <label>TEXT_NODE, CDATA_SECTION_NODE, COMMENT_NODE</label>
	    <def><p>These three types of nodes inheriting from
		<code>CharacterData</code> copy their <code>data</code> and
		<code>length</code> attributes from those of the source
		node.</p>
	    </def>
	  </gitem>
	</glist>
      </p>
    </descr>
    <parameters>
      <param name="importedNode" type="Node" attr="in">
	<descr><p>The node to import.</p></descr>
      </param>
      <param name="deep" type="boolean" attr="in">
	<descr><p>If <code>true</code>, recursively import the subtree
	    under the specified node; if <code>false</code>, import only
	    the node itself, as explained above. This has no effect on
	    <code>Attr</code>, <code>EntityReference</code>, and
	    <code>Notation</code> nodes.</p>
	</descr>
      </param>
    </parameters>
    <returns type="Node">
      <descr><p>The imported node that belongs to this
	  <code>Document</code>.</p></descr>
    </returns>
    <raises>
      <exception name="DOMException">
	<descr><p>NOT_SUPPORTED_ERR: Raised if the type of node being imported
	    is not supported.</p></descr>
      </exception>
    </raises>
  </method>

  <method name="createElementNS" id="ID-DocCrElNS" since="DOM Level 2">
    <descr><p>Creates an element of the given qualified name and namespace
	URI. HTML-only DOM implementations do not need to implement this
	method.</p>
    </descr>
    <parameters>
      <param name="namespaceURI" type="DOMString" attr="in">
	<descr><p>The <termref def='dt-namespaceURI'>namespace URI</termref> of
	    the element to create.</p>
	</descr>
      </param>
      <param name="qualifiedName" type="DOMString" attr="in">
	<descr><p>The <termref def='dt-qualifiedname'>qualified name</termref>
	    of the element type to instantiate.</p>
	</descr>
      </param>
    </parameters>
    <returns type="Element">
      <descr><p>A new <code>Element</code> object with the following
	  attributes:</p>
	<table>
	  <tbody>
	    <tr><th>Attribute</th><th>Value</th></tr>
	    <tr><td><code>Node.nodeName</code></td>
	      <td><code>qualifiedName</code></td>
	    </tr>
	    <tr><td><code>Node.namespaceURI</code></td>
	      <td><code>namespaceURI</code></td></tr>
	    <tr><td><code>Node.prefix</code></td><td>prefix, extracted from
		<code>qualifiedName</code>, or <code>null</code> if there is no
		prefix</td></tr>
	    <tr><td><code>Node.localName</code></td><td><termref
		  def='dt-localname'>local name</termref>, extracted from
		<code>qualifiedName</code></td></tr>
	    <tr><td><code>Element.tagName</code></td>
	      <td><code>qualifiedName</code></td>
	    </tr>
	  </tbody>
	</table>
      </descr>
    </returns>
    <raises>
      <exception name="DOMException">
	<descr><p>INVALID_CHARACTER_ERR: Raised if the specified qualified name
	    contains an illegal character.</p>
	  <p>NAMESPACE_ERR: Raised if the <code>qualifiedName</code> is
	    malformed, if the <code>qualifiedName</code> has a prefix and
	    the <code>namespaceURI</code> is <code>null</code>, or if 
            the <code>qualifiedName</code> has a prefix that
	    is "xml" and the <code>namespaceURI</code> is different
	    from "<loc href='xml-ns;'>xml-ns;</loc>" <bibref
	      ref='Namespaces'/>.</p>
	</descr>
      </exception>
    </raises>
  </method>
  <method name="createAttributeNS" id="ID-DocCrAttrNS" since="DOM Level 2">
    <descr><p>Creates an attribute of the given qualified name and namespace
	URI. HTML-only DOM implementations do not need to implement this
	method.</p>
    </descr>
    <parameters>
      <param name="namespaceURI" type="DOMString" attr="in">
	<descr><p>The <termref def='dt-namespaceURI'>namespace URI</termref> of
	    the attribute to create.</p>
	</descr>
      </param>
      <param name="qualifiedName" type="DOMString" attr="in">
	<descr><p>The <termref def='dt-qualifiedname'>qualified name</termref>
	    of the attribute to instantiate.</p>
	</descr>
      </param>
    </parameters>
    <returns type="Attr">
      <descr><p>A new <code>Attr</code> object with the following
	  attributes:</p>
	<table>
	  <tbody>
	    <tr><th>Attribute</th><th>Value</th></tr>
	    <tr><td><code>Node.nodeName</code></td><td>qualifiedName</td>
	    </tr>
	    <tr><td><code>Node.namespaceURI</code></td>
	      <td><code>namespaceURI</code></td></tr>
	    <tr><td><code>Node.prefix</code></td><td>prefix, extracted from
		<code>qualifiedName</code>, or <code>null</code> if there is no
		prefix</td></tr>
	    <tr><td><code>Node.localName</code></td><td><termref
		  def='dt-localname'>local name</termref>, extracted from
		<code>qualifiedName</code></td></tr>
	    <tr><td><code>Attr.name</code></td>
	      <td><code>qualifiedName</code></td></tr>
	    <tr><td><code>Node.nodeValue</code></td>
	      <td>the empty string</td></tr>
	  </tbody>
	</table>
      </descr>
    </returns>
    <raises>
      <exception name="DOMException">
	<descr><p>INVALID_CHARACTER_ERR: Raised if the specified qualified name
	    contains an illegal character.</p>
	  <p>NAMESPACE_ERR: Raised if the <code>qualifiedName</code> is
	    malformed, if the <code>qualifiedName</code> has a prefix and
	    the <code>namespaceURI</code> is <code>null</code>, if the 
            <code>qualifiedName</code> has a prefix that is
	    "xml" and the <code>namespaceURI</code> is different from
	    "<loc href='xml-ns;'>xml-ns;</loc>", or if the
	    <code>qualifiedName</code> is "xmlns" and the
	    <code>namespaceURI</code> is different from
	    "<loc href='xmlns-ns;'>xmlns-ns;</loc>".</p>
	</descr>
      </exception>
    </raises>
  </method>
  <method name="getElementsByTagNameNS" id="ID-getElBTNNS" since="DOM Level 2">
    <descr><p>Returns a <code>NodeList</code> of all the <code>Elements</code>
	with a given <termref def='dt-localname'>local name</termref> and
	namespace URI in the order in which they are encountered in a
	preorder traversal of the <code>Document</code> tree.</p>
    </descr>
    <parameters>
      <param name="namespaceURI" type="DOMString" attr="in">
	<descr><p>The <termref def='dt-namespaceURI'>namespace URI</termref> of
	    the elements to match on. The special value "*" matches all
	    namespaces.</p>
	</descr>
      </param>
      <param name="localName" type="DOMString" attr="in">
	<descr><p>The <termref def='dt-localname'>local name</termref> of the
	    elements to match on. The special value "*" matches all local
	    names.</p>
	</descr>
      </param>
    </parameters>
    <returns type="NodeList">
      <descr><p>A new <code>NodeList</code> object containing all the matched
	  <code>Elements</code>.</p></descr>
    </returns>
    <raises>
      <!-- Throws no exceptions -->
    </raises>
  </method>
  <method name="getElementById" id="ID-getElBId" since="DOM Level 2">
    <descr><p>Returns the <code>Element</code> whose <code>ID</code>
	is given by <code>elementId</code>. If no such element exists, returns
	<code>null</code>. Behavior is not defined if more than one element has
	this <code>ID</code>.
        <note><p>The DOM implementation must have information that says which
        attributes are of type ID. Attributes with the name "ID" are not of type ID unless
        so defined. Implementations that do not know whether attributes are of type
        ID or not are expected to return <code>null</code>.</p></note></p></descr>
    <parameters>
      <param name="elementId" type="DOMString" attr="in">
	<descr><p>The unique <code>id</code> value for an element.</p></descr>
      </param>
    </parameters>
    <returns type="Element">
      <descr><p>The matching element.</p></descr>
    </returns>
    <raises>
      <!-- Throws no exceptions -->
    </raises>
  </method>
</interface>