From fbd32bf69da246a1c90b12520a56fd0d20ae6091 Mon Sep 17 00:00:00 2001
From: Mehdi Achour <didou@php.net>
Date: Sun, 19 Dec 2004 22:16:44 +0000
Subject: [PATCH] Use a valid docbook example file with a public DTD attached
 and update DOMXpath->query() example Also document DOMDocument->valid() and
 validateOnParse (as we have a valid dtd :) )

git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@175096 c90b9560-bf6c-de11-be94-00142212c4b1
---
 .../functions/dom-domdocument-validate.xml    | 35 ++++++++-
 .../dom/functions/dom-domxpath-query.xml      | 30 ++++---
 reference/dom/reference.xml                   | 78 +++++++++++--------
 3 files changed, 98 insertions(+), 45 deletions(-)

diff --git a/reference/dom/functions/dom-domdocument-validate.xml b/reference/dom/functions/dom-domdocument-validate.xml
index 6377f994fb..5604920d41 100644
--- a/reference/dom/functions/dom-domdocument-validate.xml
+++ b/reference/dom/functions/dom-domdocument-validate.xml
@@ -1,5 +1,5 @@
 <?xml version="1.0" encoding="iso-8859-1"?>
-<!-- $Revision: 1.4 $ -->
+<!-- $Revision: 1.5 $ -->
   <refentry id="function.dom-domdocument-validate">
    <refnamediv>
     <refname>DOMDocument->validate</refname>
@@ -18,8 +18,39 @@
      </methodsynopsis>
     </classsynopsis>
     <para>
-     Validates the document based on its DTD.
+     Validates the document based on its DTD. &return.success;
+     If the document have no DTD attached, this method will return &false;.
     </para>
+    <para>
+     You can also use the <literal>validateOnParse</literal> property of 
+     <classname>DOMDocument</classname> to make a DTD validation.
+    </para>
+    <example>
+     <title>Example of DTD validation</title>
+     <programlisting role="php">
+<![CDATA[
+<?php
+$dom = new DOMDocument;
+$dom->Load('book.xml');
+if ($dom->validate()) {
+    echo "This document is valid!\n";	
+}
+?>
+]]>
+     </programlisting>
+     <para>
+      You can also validate your XML file while loading it:
+     </para>
+     <programlisting role="php">
+<![CDATA[
+<?php
+$dom = new DOMDocument;
+$dom->validateOnParse = true;
+$dom->Load('book.xml');
+?>
+]]>
+     </programlisting>
+    </example>
     <para>
      See also <link linkend="function.dom-domdocument-schemavalidate">DOMDocument->schemaValidate()</link>, 
      <link linkend="function.dom-domdocument-schemavalidatesource">DOMDocument->schemaValidateSource()</link>, 
diff --git a/reference/dom/functions/dom-domxpath-query.xml b/reference/dom/functions/dom-domxpath-query.xml
index 6afde732f1..a2af115e77 100644
--- a/reference/dom/functions/dom-domxpath-query.xml
+++ b/reference/dom/functions/dom-domxpath-query.xml
@@ -1,5 +1,5 @@
 <?xml version="1.0" encoding="iso-8859-1"?>
-<!-- $Revision: 1.6 $ -->
+<!-- $Revision: 1.7 $ -->
   <refentry id="function.dom-domxpath-query">
    <refnamediv>
     <refname>DOMXPath->query</refname>
@@ -25,23 +25,28 @@
     </para>
     <para>
      <example>
-      <title>Getting all entries begining with "b"</title>
+      <title>Getting all the english books</title>
       <programlisting role="php">
 <![CDATA[
 <?php
 
 $doc = new DOMDocument;
-$doc->Load('chapter.xml');
+
+// We don't want to bother with white spaces
+$doc->preserveWhiteSpace = false;
+
+$doc->Load('book.xml');
 
 $xpath = new DOMXPath($doc);
 
-// We starts from the root element 
-$query = '//chapter/para/informaltable/tgroup/tbody/row/entry[substring(., 1, 1) = "b"]';
+// We starts from the root element
+$query = '//book/chapter/para/informaltable/tgroup/tbody/row/entry[. = "en"]';
 
 $entries = $xpath->query($query);
 
 foreach ($entries as $entry) {
-   echo 'cell: ' . $entry->nodeValue . "\n";
+    echo "Found {$entry->previousSibling->previousSibling->nodeValue}," .
+         " by {$entry->previousSibling->nodeValue}\n";
 }
 ?>
 ]]>
@@ -49,8 +54,8 @@ foreach ($entries as $entry) {
       &example.outputs;
       <screen>
 <![CDATA[
-cell: b1
-cell: b3
+Found The Grapes of Wrath, by John Steinbeck
+Found The Pearl, by John Steinbeck
 ]]>
       </screen>
      </example>
@@ -68,19 +73,22 @@ cell: b3
 <?php
 
 $doc = new DOMDocument;
-$doc->Load('chapter.xml');
+$doc->preserveWhiteSpace = false;
+
+$doc->Load('book.xml');
 
 $xpath = new DOMXPath($doc);
 
 $tbody = $doc->getElementsByTagName('tbody')->item(0);
 
 // our query is relative to the tbody node
-$query = 'row/entry[substring(., 1, 1) = "b"]';
+$query = 'row/entry[. = "en"]';
 
 $entries = $xpath->query($query, $tbody);
 
 foreach ($entries as $entry) {
-   echo 'cell: ' . $entry->nodeValue . "\n";
+    echo "Found {$entry->previousSibling->previousSibling->nodeValue}," .
+         " by {$entry->previousSibling->nodeValue}\n";
 }
 ?>
 ]]>
diff --git a/reference/dom/reference.xml b/reference/dom/reference.xml
index 66921093fe..14632506bb 100644
--- a/reference/dom/reference.xml
+++ b/reference/dom/reference.xml
@@ -1,5 +1,5 @@
 <?xml version="1.0" encoding="iso-8859-1"?>
-<!-- $Revision: 1.7 $ -->
+<!-- $Revision: 1.8 $ -->
  <reference id="ref.dom">
   <title>DOM Functions</title>
   <titleabbrev>DOM</titleabbrev>
@@ -1097,44 +1097,58 @@
     &reftitle.examples;
     <para>
      Many examples in this reference require an XML file. We will use the 
-     <filename>chapter.xml</filename> that contains the following:
+     <filename>book.xml</filename> that contains the following:
     </para>
     <para>
      <example>
       <title>chapter.xml</title>
       <programlisting role="xml">
 <![CDATA[
-<?xml version="1.0" standalone="yes"?>
-<!DOCTYPE chapter SYSTEM '/share/sgml/Norman_Walsh/db3xml10/db3xml10.dtd'
-[ <!ENTITY sp "spanish">
+<?xml version="1.0" encoding="iso-8859-1"?>
+<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
+ "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" [
 ]>
-<chapter language="en">
- <title language="en">Title</title>
- <para language="ge">
-  &amp;sp;
-  <!-- comment -->
-  <informaltable ID="findme" language="&amp;sp;">
-   <tgroup cols="3">
-    <tbody>
-     <row>
-      <entry>a1</entry>
-      <entry morerows="1">b1</entry>
-      <entry>c1</entry>
-     </row>
-     <row>
-      <entry>a2</entry>
-      <entry>c2</entry>
-     </row>
-     <row>
-      <entry>a3</entry>
-      <entry>b3</entry>
-      <entry>c3</entry>
-     </row>
-    </tbody>
-   </tgroup>
-  </informaltable>
- </para>
-</chapter>
+<book id="listing">
+ <title>My lists</title>
+ <chapter id="books">
+  <title>My books</title>
+  <para>
+   <informaltable>
+    <tgroup cols="4">
+     <thead>
+      <row>
+       <entry>Title</entry>
+       <entry>Author</entry>
+       <entry>Language</entry>
+       <entry>ISBN</entry>
+      </row>
+     </thead>
+     <tbody>
+      <row>
+       <entry>The Grapes of Wrath</entry>
+       <entry>John Steinbeck</entry>
+       <entry>en</entry>
+       <entry>0140186409</entry>
+      </row>
+      <row>
+       <entry>The Pearl</entry>
+       <entry>John Steinbeck</entry>
+       <entry>en</entry>
+       <entry>014017737X</entry>
+      </row>
+      <row>
+       <entry>Samarcande</entry>
+       <entry>Amine Maalouf</entry>
+       <entry>fr</entry>
+       <entry>2253051209</entry>
+      </row>
+      <!-- TODO: I have a lot of remaining books to add.. -->
+     </tbody>
+    </tgroup>
+   </informaltable>
+  </para>
+ </chapter>
+</book>
 ]]>
       </programlisting>
      </example>