From 6cb6357d10f6cbac5c6a6fd8f298d85d87433071 Mon Sep 17 00:00:00 2001
From: Mehdi Achour <didou@php.net>
Date: Sun, 29 Aug 2004 18:54:42 +0000
Subject: [PATCH] added documentation and examples, fixed protos

git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@167576 c90b9560-bf6c-de11-be94-00142212c4b1
---
 .../domxml/functions/DomAttribute-name.xml    |  4 +-
 .../domxml/functions/DomAttribute-value.xml   | 37 ++++++++++++-
 .../domxml/functions/DomDocument-add-root.xml | 10 ++--
 .../functions/DomDocument-html-dump-mem.xml   | 25 ++++++---
 .../domxml/functions/DomDocument-xinclude.xml | 54 ++++++++++++++++++-
 .../domxml/functions/DomDocumentType-name.xml | 24 ++++++++-
 .../functions/DomDocumentType-system-id.xml   | 12 +++--
 .../DomElement-get-attribute-node.xml         | 37 +++++++++++--
 .../functions/DomElement-get-attribute.xml    | 40 +++++++++++---
 .../functions/DomElement-has-attribute.xml    | 35 ++++++++++--
 .../functions/DomElement-set-attribute.xml    |  9 ++--
 .../domxml/functions/DomElement-tagname.xml   | 34 ++++++++++--
 reference/domxml/functions/domxml-version.xml | 27 ++++++++--
 13 files changed, 301 insertions(+), 47 deletions(-)

diff --git a/reference/domxml/functions/DomAttribute-name.xml b/reference/domxml/functions/DomAttribute-name.xml
index 539dcac1fe..ef4fb386c9 100644
--- a/reference/domxml/functions/DomAttribute-name.xml
+++ b/reference/domxml/functions/DomAttribute-name.xml
@@ -1,5 +1,5 @@
 <?xml version="1.0" encoding="iso-8859-1"?>
-<!-- $Revision: 1.5 $ -->
+<!-- $Revision: 1.6 $ -->
 <!-- splitted from ./en/functions/domxml.xml, last change in rev 1.38 -->
   <refentry id='function.domattribute-name'>
    <refnamediv>
@@ -18,7 +18,7 @@
      This function returns the name of the attribute.
     </para>
     <para>
-     See also <function>domattribute_value</function>.
+     See also <function>domattribute_value</function> for an example.
     </para>
    </refsect1>
   </refentry>
diff --git a/reference/domxml/functions/DomAttribute-value.xml b/reference/domxml/functions/DomAttribute-value.xml
index 06856828d5..7b88f8b2d1 100644
--- a/reference/domxml/functions/DomAttribute-value.xml
+++ b/reference/domxml/functions/DomAttribute-value.xml
@@ -1,5 +1,5 @@
 <?xml version="1.0" encoding="iso-8859-1"?>
-<!-- $Revision: 1.5 $ -->
+<!-- $Revision: 1.6 $ -->
 <!-- splitted from ./en/functions/domxml.xml, last change in rev 1.38 -->
   <refentry id='function.domattribute-value'>
    <refnamediv>
@@ -17,6 +17,41 @@
     <para>
      This function returns the value of the attribute.
     </para>
+    <para>
+     <example>
+      <title>Getting all the attributes of a node</title>
+      <programlisting role="php">
+<![CDATA[
+<?php
+
+include("example.inc");
+
+if (!$dom = domxml_open_mem($xmlstr)) {
+     echo "Error while parsing the document\n";
+     exit;
+}
+
+$root = $dom->document_element();
+$attrs = $root->attributes();
+
+echo 'Attributes of ' . $root->node_name() . "\n";
+foreach ($attrs as $attribute) {
+     echo ' - ' . $attribute->name . ' : ' . $attribute->value . "\n";
+}
+
+?>
+
+]]>
+      </programlisting>
+      &example.outputs;
+      <screen>
+<![CDATA[
+Attributes of chapter
+ - language : en
+]]>
+      </screen>
+     </example>
+    </para>
     <para>
      See also <function>domattribute_name</function>.
     </para>
diff --git a/reference/domxml/functions/DomDocument-add-root.xml b/reference/domxml/functions/DomDocument-add-root.xml
index ce756fd2d0..cbef39a2f0 100644
--- a/reference/domxml/functions/DomDocument-add-root.xml
+++ b/reference/domxml/functions/DomDocument-add-root.xml
@@ -1,5 +1,5 @@
 <?xml version="1.0" encoding="iso-8859-1"?>
-<!-- $Revision: 1.4 $ -->
+<!-- $Revision: 1.5 $ -->
 <!-- splitted from ./en/functions/domxml.xml, last change in rev 1.6 -->
   <refentry id="function.domdocument-add-root">
    <refnamediv>
@@ -11,7 +11,7 @@
    <refsect1>
     <title>Description</title>
      <methodsynopsis>
-      <type>resource</type><methodname>DomDocument->add_root</methodname>
+      <type>object</type><methodname>DomDocument->add_root</methodname>
       <methodparam><type>string</type><parameter>name</parameter></methodparam>
      </methodsynopsis>
     &warn.experimental.func;
@@ -26,9 +26,9 @@
 <![CDATA[
 <?php
 $doc = domxml_new_doc("1.0");
-$root = $doc->add_root("HTML");
-$head = $root->new_child("HEAD", "");
-$head->new_child("TITLE", "Hier der Titel");
+$root = $doc->add_root("html");
+$head = $root->new_child("head", "");
+$head->new_child("title", "Hier der Titel");
 echo htmlentities($doc->dump_mem());
 ?>
 ]]>
diff --git a/reference/domxml/functions/DomDocument-html-dump-mem.xml b/reference/domxml/functions/DomDocument-html-dump-mem.xml
index 519a91d465..a7d6eaeab7 100644
--- a/reference/domxml/functions/DomDocument-html-dump-mem.xml
+++ b/reference/domxml/functions/DomDocument-html-dump-mem.xml
@@ -1,5 +1,5 @@
 <?xml version="1.0" encoding="iso-8859-1"?>
-<!-- $Revision: 1.5 $ -->
+<!-- $Revision: 1.6 $ -->
 <!-- splitted from ./en/functions/domxml.xml, last change in rev 1.6 -->
   <refentry id="function.domdocument-html-dump-mem">
    <refnamediv>
@@ -25,21 +25,32 @@
       <programlisting role="php">
 <![CDATA[
 <?php
+
+// Creates the document
 $doc = domxml_new_doc("1.0");
-$root = $doc->create_element("HTML");
+
+$root = $doc->create_element("html");
 $root = $doc->append_child($root);
-$head = $doc->create_element("HEAD");
+
+$head = $doc->create_element("head");
 $head = $root->append_child($head);
-$title = $doc->create_element("TITLE");
+
+$title = $doc->create_element("title");
 $title = $head->append_child($title);
+
 $text = $doc->create_text_node("This is the title");
 $text = $title->append_child($text);
-echo "<PRE>";
-echo htmlentities($doc->html_dump_mem());
-echo "</PRE>";
+
+echo $doc->html_dump_mem();
 ?>
 ]]>
       </programlisting>
+      &example.outputs;
+      <screen role="xml">
+<![CDATA[
+<html><head><title>This is the title</title></head></html>
+]]>
+      </screen>
      </example>
     </para>
     <para>
diff --git a/reference/domxml/functions/DomDocument-xinclude.xml b/reference/domxml/functions/DomDocument-xinclude.xml
index 5678dd0450..d3fb5fa717 100644
--- a/reference/domxml/functions/DomDocument-xinclude.xml
+++ b/reference/domxml/functions/DomDocument-xinclude.xml
@@ -1,5 +1,5 @@
 <?xml version="1.0" encoding="iso-8859-1"?>
-<!-- $Revision: 1.4 $ -->
+<!-- $Revision: 1.5 $ -->
   <refentry id="function.domdocument-xinclude">
    <refnamediv>
     <refname>DomDocument->xinclude</refname>
@@ -14,8 +14,58 @@
         <void/>
      </methodsynopsis>
     &warn.experimental.func;
-    &warn.undocumented.func;
+    <para>
+     This function substitutes XIncludes in a DomDocument object.
+    </para>
+    <para>
+     <example>
+      <title>Substitu</title>
+      <programlisting role="php">
+<![CDATA[
+<?php
 
+// include.xml contains :
+// <child>test</child> 
+
+$xml = '<?xml version="1.0"?>
+<root xmlns:xi="http://www.w3.org/2001/XInclude">
+  <xi:include href="include.xml">
+    <xi:fallback>
+      <error>xinclude: include.xml not found</error>
+    </xi:fallback>
+  </xi:include>
+</root>';
+
+$domxml = domxml_open_mem($xml);
+$domxml->xinclude();
+
+echo $domxml->dump_mem();
+
+?>                 
+]]>
+      </programlisting>
+      &example.outputs;
+      <screen role="xml">
+<![CDATA[
+<?xml version="1.0"?>
+<root xmlns:xi="http://www.w3.org/2001/XInclude">
+  <child>test</child>
+</root>
+]]>
+      </screen>
+      <para>
+       If <filename>include.xml</filename> doesn't exist, you'll see:
+      </para>
+      <screen role="xml">
+<![CDATA[
+<?xml version="1.0"?>
+<root xmlns:xi="http://www.w3.org/2001/XInclude">
+  <error>xinclude:dom.xml not found</error>
+</root>
+]]>
+      </screen>
+     </example>
+    </para>
    </refsect1>
   </refentry>
 
diff --git a/reference/domxml/functions/DomDocumentType-name.xml b/reference/domxml/functions/DomDocumentType-name.xml
index d960a4258b..d0a65f35a6 100644
--- a/reference/domxml/functions/DomDocumentType-name.xml
+++ b/reference/domxml/functions/DomDocumentType-name.xml
@@ -1,5 +1,5 @@
 <?xml version="1.0" encoding="iso-8859-1"?>
-<!-- $Revision: 1.3 $ -->
+<!-- $Revision: 1.4 $ -->
 <!-- splitted from ./en/functions/domxml.xml, last change in rev 1.38 -->
   <refentry id='function.domdocumenttype-name'>
    <refnamediv>
@@ -17,6 +17,28 @@
     <para>
      This function returns the name of the document type.
     </para>
+    <para>
+     <example>
+      <title>Getting the document type's name</title>
+      <programlisting role="php">
+<![CDATA[
+<?php
+
+include("example.inc");
+
+if (!$dom = domxml_open_mem($xmlstr)) {
+    echo "Error while parsing the document\n";
+    exit;
+}
+
+$doctype = $dom->doctype();
+echo $doctype->name(); // chapter
+
+?>
+]]>
+      </programlisting>
+     </example>
+    </para>
    </refsect1>
   </refentry>
 
diff --git a/reference/domxml/functions/DomDocumentType-system-id.xml b/reference/domxml/functions/DomDocumentType-system-id.xml
index 576f0fa9e7..d6901f31b5 100644
--- a/reference/domxml/functions/DomDocumentType-system-id.xml
+++ b/reference/domxml/functions/DomDocumentType-system-id.xml
@@ -1,11 +1,11 @@
 <?xml version="1.0" encoding="iso-8859-1"?>
-<!-- $Revision: 1.4 $ -->
+<!-- $Revision: 1.5 $ -->
 <!-- splitted from ./en/functions/domxml.xml, last change in rev 1.38 -->
   <refentry id='function.domdocumenttype-system-id'>
    <refnamediv>
     <refname>DomDocumentType->system_id</refname>
     <refpurpose>
-     Returns system id of document type
+     Returns the system id of document type
     </refpurpose>
    </refnamediv>
    <refsect1>
@@ -18,8 +18,6 @@
      Returns the system id of the document type.
     </para>
     <para>
-     The following example echos
-     '/share/sgml/Norman_Walsh/db3xml10/db3xml10.dtd'.
      <example>
       <title>Retrieving the system id</title>
       <programlisting role="php">
@@ -37,6 +35,12 @@ echo $doctype->system_id();
 ?>
 ]]>
       </programlisting>
+      &example.outputs;
+      <screen>
+<![CDATA[
+/share/sgml/Norman_Walsh/db3xml10/db3xml10.dtd
+]]>
+      </screen>
      </example>
     </para>
    </refsect1>
diff --git a/reference/domxml/functions/DomElement-get-attribute-node.xml b/reference/domxml/functions/DomElement-get-attribute-node.xml
index 08f472d8e6..ebf6363e2b 100644
--- a/reference/domxml/functions/DomElement-get-attribute-node.xml
+++ b/reference/domxml/functions/DomElement-get-attribute-node.xml
@@ -1,21 +1,50 @@
 <?xml version="1.0" encoding="iso-8859-1"?>
-<!-- $Revision: 1.3 $ -->
+<!-- $Revision: 1.4 $ -->
 <!-- splitted from ./en/functions/domxml.xml, last change in rev 1.27 -->
   <refentry id='function.domelement-get-attribute-node'>
    <refnamediv>
     <refname>DomElement->get_attribute_node</refname>
     <refpurpose>
-     Returns value of attribute
+     Returns the node of the given attribute
     </refpurpose>
    </refnamediv>
    <refsect1>
     <title>Description</title>
     <methodsynopsis>
      <type>object</type><methodname>DomElement->get_attribute_node</methodname>
-     <methodparam><type>object</type><parameter>attr</parameter></methodparam>
+     <methodparam><type>string</type><parameter>name</parameter></methodparam>
     </methodsynopsis>
     <para>
-     &warn.undocumented.func;
+     Returns the node of the attribute named <parameter>name</parameter>
+     in the current element. The <parameter>name</parameter> parameter is
+     case sensitive.
+    </para>
+    <para>
+     If no attribute with given name is found, &false; is returned.
+    </para>
+    <para>
+     <example>
+      <title>Getting an attribute node</title>
+      <programlisting role="php">
+<![CDATA[
+<?php
+
+include("example.inc");
+
+if (!$dom = domxml_open_mem($xmlstr)) {
+    echo "Error while parsing the document\n";
+    exit;
+}
+
+$root = $dom->document_element();
+if ($attribute = $root->get_attribute_node('language')) {
+    echo 'Language is: ' . $attribute->value() . "\n";
+}
+
+?>
+]]>
+      </programlisting>
+     </example>
     </para>
    </refsect1>
   </refentry>
diff --git a/reference/domxml/functions/DomElement-get-attribute.xml b/reference/domxml/functions/DomElement-get-attribute.xml
index 9d92076d86..ab9b438059 100644
--- a/reference/domxml/functions/DomElement-get-attribute.xml
+++ b/reference/domxml/functions/DomElement-get-attribute.xml
@@ -1,26 +1,50 @@
 <?xml version="1.0" encoding="iso-8859-1"?>
-<!-- $Revision: 1.5 $ -->
+<!-- $Revision: 1.6 $ -->
 <!-- splitted from ./en/functions/domxml.xml, last change in rev 1.28 -->
   <refentry id='function.domelement-get-attribute'>
    <refnamediv>
     <refname>DomElement->get_attribute</refname>
     <refpurpose>
-     Returns value of attribute
+     Returns the value of the given attribute
     </refpurpose>
    </refnamediv>
    <refsect1>
     <title>Description</title>
     <methodsynopsis>
-     <type>object</type><methodname>DomElement->get_attribute</methodname>
+     <type>string</type><methodname>DomElement->get_attribute</methodname>
      <methodparam><type>string</type><parameter>name</parameter></methodparam>
     </methodsynopsis>
     <para>
-     Returns the attribute with name <parameter>name</parameter> of the
-     current node.
+     Returns the value of the attribute named <parameter>name</parameter>
+     in the current node. The <parameter>name</parameter> parameter is case
+     sensitive.
     </para>
-     <para>
-     (PHP &gt;= 4.3 only) If no attribute with given name is found, an empty
-     string is returned.
+    <para>
+     Since PHP 4.3, if no attribute with given <parameter>name</parameter> is
+     found, an empty string is returned.
+    </para>
+    <para>
+     <example>
+      <title>Getting the value of an attribute</title>
+      <programlisting role="php">
+<![CDATA[
+<?php
+
+include("example.inc");
+
+if (!$dom = domxml_open_mem($xmlstr)) {
+    echo "Error while parsing the document\n";
+    exit;
+}
+
+// get chapter
+$root = $dom->document_element();
+echo $root->get_attribute('language')); // en
+
+?>
+]]>
+      </programlisting>
+     </example>
     </para>
     <para>
      See also <function>domelement_set_attribute</function>
diff --git a/reference/domxml/functions/DomElement-has-attribute.xml b/reference/domxml/functions/DomElement-has-attribute.xml
index a4748728d2..e0b77c4be5 100644
--- a/reference/domxml/functions/DomElement-has-attribute.xml
+++ b/reference/domxml/functions/DomElement-has-attribute.xml
@@ -1,11 +1,11 @@
 <?xml version="1.0" encoding="iso-8859-1"?>
-<!-- $Revision: 1.4 $ -->
+<!-- $Revision: 1.5 $ -->
 <!-- splitted from ./en/functions/domxml.xml, last change in rev 1.38 -->
   <refentry id='function.domelement-has-attribute'>
    <refnamediv>
     <refname>DomElement->has_attribute</refname>
     <refpurpose>
-     Checks to see if attribute exists
+     Checks to see if an attribute exists in the current node
     </refpurpose>
    </refnamediv>
    <refsect1>
@@ -15,7 +15,36 @@
      <methodparam><type>string</type><parameter>name</parameter></methodparam>
     </methodsynopsis>
     <para>
-     &warn.undocumented.func;
+     This functions checks to see if an attribute named
+     <parameter>name</parameter> exists in the current node.
+    </para>
+    <para>
+     <example>
+      <title>Testing the existence of an attribute</title>
+      <programlisting role="php">
+<![CDATA[
+<?php
+
+include("example.inc");
+
+if (!$dom = domxml_open_mem($xmlstr)) {
+    echo "Error while parsing the document\n";
+    exit;
+}
+
+$root = $dom->document_element();
+
+$buffer = '<html'
+if ($root->has_attribute('language')) {
+    $buffer .= 'lang="' . $root->get_attribute('language') . '"';
+}
+$buffer .= '>';
+
+?>
+
+]]>
+      </programlisting>
+     </example>
     </para>
    </refsect1>
   </refentry>
diff --git a/reference/domxml/functions/DomElement-set-attribute.xml b/reference/domxml/functions/DomElement-set-attribute.xml
index 9004eee8fa..b06b73ef1e 100644
--- a/reference/domxml/functions/DomElement-set-attribute.xml
+++ b/reference/domxml/functions/DomElement-set-attribute.xml
@@ -1,23 +1,24 @@
 <?xml version="1.0" encoding="iso-8859-1"?>
-<!-- $Revision: 1.6 $ -->
+<!-- $Revision: 1.7 $ -->
 <!-- splitted from ./en/functions/domxml.xml, last change in rev 1.27 -->
   <refentry id='function.domelement-set-attribute'>
    <refnamediv>
     <refname>DomElement->set_attribute</refname>
     <refpurpose>
-     Adds new attribute
+     Sets the value of an attribute
     </refpurpose>
    </refnamediv>
    <refsect1>
     <title>Description</title>
     <methodsynopsis>
-     <type>bool</type><methodname>DomElement->set_attribute</methodname>
+     <type>object</type><methodname>DomElement->set_attribute</methodname>
      <methodparam><type>string</type><parameter>name</parameter></methodparam>
      <methodparam><type>string</type><parameter>value</parameter></methodparam>
     </methodsynopsis>
     <para>
      Sets an attribute with name <parameter>name</parameter> to the given
-     value. If the attribute does not exist, it will be created.
+     <parameter>value</parameter>. If the attribute does not exist, it will
+     be created.
     </para>
     <para>
      <example>
diff --git a/reference/domxml/functions/DomElement-tagname.xml b/reference/domxml/functions/DomElement-tagname.xml
index bc6a4b2fa9..e4103ec8a8 100644
--- a/reference/domxml/functions/DomElement-tagname.xml
+++ b/reference/domxml/functions/DomElement-tagname.xml
@@ -1,11 +1,11 @@
 <?xml version="1.0" encoding="iso-8859-1"?>
-<!-- $Revision: 1.3 $ -->
+<!-- $Revision: 1.4 $ -->
 <!-- splitted from ./en/functions/domxml.xml, last change in rev 1.6 -->
   <refentry id='function.domelement-tagname'>
    <refnamediv>
     <refname>DomElement->tagname</refname>
     <refpurpose>
-     Returns name of element
+     Returns the name of the current element
     </refpurpose>
    </refnamediv>
    <refsect1>
@@ -15,7 +15,35 @@
      <void/>
     </methodsynopsis>
     <para>
-     &warn.undocumented.func;
+     Returns the name of the current node. Calling this function is the same
+     as accessing the <literal>tagname</literal> property, or calling
+     <function>DomElement->node_name</function> of the current node.
+    </para>
+    <para>
+     <example>
+      <title>Getting the node name</title>
+      <programlisting role="php">
+<![CDATA[
+<?php
+
+include("example.inc");
+
+if (!$dom = domxml_open_mem($xmlstr)) {
+    echo "Error while parsing the document\n";
+    exit;
+}
+
+$root = $dom->document_element();
+echo $root->tagname();   // chapter
+echo $root->tagname;     // chapter
+echo $root->node_name(); // chapter
+
+
+?>
+
+]]>
+      </programlisting>
+     </example>
     </para>
    </refsect1>
   </refentry>
diff --git a/reference/domxml/functions/domxml-version.xml b/reference/domxml/functions/domxml-version.xml
index 4ad943fe59..de64f98371 100644
--- a/reference/domxml/functions/domxml-version.xml
+++ b/reference/domxml/functions/domxml-version.xml
@@ -1,11 +1,11 @@
 <?xml version="1.0" encoding="iso-8859-1"?>
-<!-- $Revision: 1.2 $ -->
+<!-- $Revision: 1.3 $ -->
 <!-- splitted from ./en/functions/domxml.xml, last change in rev 1.39 -->
   <refentry id='function.domxml-version'>
    <refnamediv>
     <refname>domxml_version</refname>
     <refpurpose>
-     Get XML library version
+     Gets the XML library version
     </refpurpose>
    </refnamediv>
    <refsect1>
@@ -15,7 +15,28 @@
      <void/>
     </methodsynopsis>
     <para>
-     This function returns the version of the XML library version currently used.
+     This function returns the version of the version of the XML library 
+     currently used.
+    </para>
+    <para>
+     <example>
+      <title><function>domxml_version</function> Example</title>
+      <programlisting role="php">
+<![CDATA[
+<?php
+
+echo domxml_version();
+
+?>
+]]>
+      </programlisting>
+      &example.outputs.similar;
+      <screen>
+<![CDATA[
+20607
+]]>
+      </screen>
+     </example>
     </para>
    </refsect1>
   </refentry>