Thread: SF.net SVN: xmlunit: [185] trunk/xmlunit/src/user-guide/XMLUnit-Java.xml

SourceForge Headquarters 225 Broadway Suite 1600 San Diego, CA 92101 +1 (858) 422-6466

Revision: 185
          http://xmlunit.svn.sourceforge.net/xmlunit/?rev=185&view=rev
Author:   bodewig
Date:     2007-04-14 09:18:35 -0700 (Sat, 14 Apr 2007)

Log Message:
-----------
complete user's guide

Modified Paths:
--------------
    trunk/xmlunit/src/user-guide/XMLUnit-Java.xml

Modified: trunk/xmlunit/src/user-guide/XMLUnit-Java.xml
===================================================================

--- trunk/xmlunit/src/user-guide/XMLUnit-Java.xml	2007-04-14 16:16:11 UTC (rev 184)
+++ trunk/xmlunit/src/user-guide/XMLUnit-Java.xml	2007-04-14 16:18:35 UTC (rev 185)
@@ -39,7 +39,7 @@
     </revhistory>
   </articleinfo>
 
-  <section><title>A Tour of XMLUnit</title>
+  <section id="A Tour of XMLUnit"><title>A Tour of XMLUnit</title>
 
     <para>This first section contains a tour through XMLUnit's
     features, the next sections will cover them in more detail.</para>
@@ -49,7 +49,7 @@
     XMLUnit, but not the only one.  XMLUnit's features can be fully
     used without any dependency on JUnit at all.</para>
 
-    <section><title>What is XMLUnit?</title>
+    <section id="What is XMLUnit?"><title>What is XMLUnit?</title>
 
       <para>XMLUnit enables JUnit-style assertions to be made about
       the content and structure of XML<footnote id="more on
@@ -71,7 +71,7 @@
       generate and the message that the system actually generated. And
       that was the beginning of XMLUnit.</para>
     </section>
-    <section><title>Quick tour</title>
+    <section id="Quick Tour"><title>Quick tour</title>
 
       <para>XMLUnit provides a single JUnit extension class,
       <literal>XMLTestCase</literal>, and a set of supporting classes
@@ -103,7 +103,7 @@
       class).</para>
     </section>
 
-    <section><title>Glossary</title>
+    <section id="Glossary"><title>Glossary</title>
 
       <para>As with many projects some words in XMLUnit have
       particular meanings so here is a quick overview. A
@@ -126,7 +126,7 @@
       unrecoverable differences</emphasis> between them.</para>
     </section>
 
-    <section id="configuring-intro"><title>Configuring XMLUnit</title>
+    <section id="Configuring XMLUnit"><title>Configuring XMLUnit</title>
 
       <para>There are many Java XML parsers available, and XMLUnit
       should work with any JAXP compliant parser library, such as
@@ -174,7 +174,8 @@
 
     </section>
 
-    <section><title>Writing XML comparison tests</title>
+    <section id="Writing XML comparison tests">
+      <title>Writing XML comparison tests</title>
 
       <para>Let's say we have two pieces of XML that we wish to
       compare and assert that they are equal. We could write a simple
@@ -191,7 +192,7 @@
         String myControlXML = "<msg><uuid>0x00435A8C</uuid></msg>";
         String myTestXML = "<msg><localId>2376</localId></msg>";
         assertXMLEqual("Comparing test xml to control xml",
-        myControlXML, myTestXML);
+                       myControlXML, myTestXML);
     }
 }]]></programlisting></example>
 
@@ -232,9 +233,9 @@
         "<struct><boolean>false</boolean><int>3</int></struct>";
     Diff myDiff = new Diff(myControlXML, myTestXML);
     assertTrue("XML similar " + myDiff.toString(),
-    myDiff.similar());
+               myDiff.similar());
     assertTrue("XML identical " + myDiff.toString(),
-    myDiff.identical());
+               myDiff.identical());
 }]]></programlisting></example>
 
       <para>This test fails as two pieces of XML are similar but not
@@ -318,7 +319,7 @@
     Diff myDiff = new Diff(myControlXML, myTestXML);
     myDiff.overrideDifferenceListener(myDifferenceListener);
     assertTrue("test XML matches control skeleton XML",
-    myDiff.similar());
+               myDiff.similar());
 }]]></programlisting></example>
 
       <para>The <literal>DifferenceEngine</literal> class generates
@@ -376,7 +377,7 @@
 
     </section>
 
-    <section id="transform-intro">
+    <section id="Comparing XML Transformations">
       <title>Comparing XML Transformations</title>
 
       <para>XMLUnit can test XSL transformations at a high level using
@@ -422,7 +423,7 @@
 
     </section>
 
-    <section><title>Validation Tests</title>
+    <section id="Validation Tests"><title>Validation Tests</title>
 
       <para>XML parsers that validate a piece of XML against a DTD are
       common, however they rely on a DTD reference being present in
@@ -450,11 +451,11 @@
       <para>Starting with XMLUnit 1.1, the
       <literal>Validator</literal> class can also validate against one
       or more XML Schema definitions.  See <xref
-      linkend="validating-schema"/> for details.</para>
+      linkend="XML Schema Validation"/> for details.</para>
 
     </section>
 
-    <section><title>Xpath Tests</title>
+    <section id="Xpath Tests"><title>Xpath Tests</title>
 
       <para>One of the strengths of XML is the ability to
       programmatically extract specific parts of a document using
@@ -557,7 +558,7 @@
 
     </section>
 
-    <section id="intro-nodetest">
+    <section id="Testing by Tree Walking">
       <title>Testing by Tree Walking</title>
 
       <para>The DOM specification allows a <literal>Document</literal>
@@ -657,9 +658,10 @@
     </section>
   </section>
 
-  <section id="Using"><title>Using XMLUnit</title>
+  <section id="Using XMLUnit">
+    <title>Using XMLUnit</title>
 
-    <section id="requirements">
+    <section id="Requirements">
       <title>Requirements</title>
 
       <para>XMLUnit requires a JAXP compliant XML parser virtually
@@ -691,7 +693,7 @@
       <literal>XMLAssert</literal> classes.</para>
     </section>
 
-    <section id="using-plain">
+    <section id="Basic Usage">
       <title>Basic Usage</title>
 
       <para>XMLUnit consists of a few classes all living in the
@@ -705,7 +707,8 @@
       found in the more specific sections later in this
       document.</para>
 
-      <section><title>Comparing Pieces of XML</title>
+      <section id="Basic: Comparing Pieces of XML">
+        <title>Comparing Pieces of XML</title>
 
         <para>Heart and soul of XMLUnit's comparison engine is
         <literal>DifferenceEngine</literal> but most of the time you
@@ -717,11 +720,11 @@
         of options on the <literal>XMLUnit</literal> class.</para>
 
         <para>More information is available in <xref
-        linkend="Comparing"/>.</para>
+        linkend="Comparing Pieces of XML"/>.</para>
 
       </section>
 
-      <section><title>Validating</title>
+      <section id="Basic: Validating"><title>Validating</title>
 
         <para>All validation happens in the
         <literal>Validator</literal> class.  The default is to
@@ -733,11 +736,11 @@
         affect validation.</para>
 
         <para>More information is available in <xref
-        linkend="Validating"/>.</para>
+        linkend="Validating XML Documents"/>.</para>
 
       </section>
 
-      <section><title>XSLT Transformations</title>
+      <section id="XSLT Transformations"><title>XSLT Transformations</title>
 
         <para>The <literal>Transform</literal> class provides an easy
         to use layer on top of JAXP's transformations.  An instance of
@@ -751,7 +754,7 @@
         There is no detailed sections on transformations since they
         are really only a different way to create input for the rest
         of XMLUnit's machinery.  Examples can be found in <xref
-        linkend="transform-intro"/>.</para>
+        linkend="Comparing XML Transformations"/>.</para>
 
         <para>It is possible to provide a custom
         <literal>javax.xml.transform.URIResolver</literal> via the
@@ -761,7 +764,7 @@
         <literal>XMLUnit.getTransformerFactory</literal>.</para>
       </section>
 
-      <section>
+      <section id="XPath Engine">
         <title>XPath Engine</title>
 
         <para>The central piece of XMLUnit's XPath support is the
@@ -794,10 +797,10 @@
         <literal>String</literal>s.</para>
 
         <para>More information is available in <xref
-        linkend="XPath"/>.</para>
+        linkend="XPath Tests"/>.</para>
       </section>
 
-      <section>
+      <section id="Basic: DOM Tree Walking">
         <title>DOM Tree Walking</title>
 
         <para>To test pieces of XML by traversing the DOM tree you use
@@ -809,11 +812,11 @@
         own.</para>
 
         <para>More information is available in <xref
-        linkend="NodeTest"/>.</para>
+        linkend="DOM Tree Walking"/>.</para>
       </section>
     </section>
 
-    <section id="junit3">
+    <section id="Using XMLUnit With JUnit 3.x">
       <title>Using XMLUnit With JUnit 3.x</title>
 
       <para>Initially XMLUnit was tightly coupled to JUnit and the
@@ -839,7 +842,7 @@
 
     </section>
 
-    <section id="common-config">
+    <section id="Common Configuration Options">
       <title>Common Configuration Options</title>
 
       <section id="JAXP">
@@ -852,7 +855,7 @@
         since the versions shipping with some JDKs are known to
         contain serious bugs.</para>
 
-        <para>As described in <xref linkend="configuring-intro"/>
+        <para>As described in <xref linkend="Configuring XMLUnit"/>
         there are two main approaches to choose the XML parser of XSLT
         transformer: System properties and setters in the
         <literal>XMLUnit</literal> class.</para>
@@ -888,7 +891,7 @@
 
       </section>
 
-      <section id="entityresolver">
+      <section id="EntityResolver">
         <title><literal>EntityResolver</literal></title>
 
         <para>You can provide a custom
@@ -900,7 +903,7 @@
         <literal>setControlEntityResolver</literal> as well.</para>
       </section>
 
-      <section id="element-content-whitespace">
+      <section id="Basic: Element Content Whitespace">
         <title>Element Content Whitespace</title>
 
         <para>Element content whitespace - also known as ignorable
@@ -925,12 +928,12 @@
         validation by default.  It does have an effect when comparing
         pieces of XML, though, since the same flag is used for a
         different purpose as well in that case.  See <xref
-        linkend="comparing-config"/> for more details.</para>
+        linkend="Whitespace Handling"/> for more details.</para>
 
       </section>
     </section>
 
-    <section id="input-choices">
+    <section id="Providing Input to XMLUnit">
       <title>Providing Input to XMLUnit</title>
 
       <para>Most methods in XMLUnit that expect a piece of XML as
@@ -990,9 +993,10 @@
 
   </section>
 
-  <section id="Comparing"><title>Comparing Pieces of XML</title>
+  <section id="Comparing Pieces of XML">
+    <title>Comparing Pieces of XML</title>
 
-    <section id="comparing-basics">
+    <section id="The Difference Engine">
       <title>The Difference Engine</title>
 
       <para>At the center of XMLUnit's support for comparisons is the
@@ -1002,7 +1006,7 @@
       classes (see <xref linkend="Diff"/>).</para>
 
       <para>The <literal>DifferenceEngine</literal> walks two trees of
-      DOM <literal>Node</literal>s, the control and the test tree and
+      DOM <literal>Node</literal>s, the control and the test tree, and
       compares the nodes.  Whenever it detects a difference, it sends
       a message to a configured <literal>DifferenceListener</literal>
       (see <xref linkend="DifferenceListener"/>) and asks a
@@ -1025,15 +1029,16 @@
 
       <para>A <literal>Difference</literal> can be recoverable;
       recoverable <literal>Difference</literal>s make the
-      <literal>Diff</literal> class consider the two pieces of XML
-      similar while non-recoverable <literal>Difference</literal>s
-      render the two pieces different.</para>
+      <literal>Diff</literal> class consider two pieces of XML similar
+      while non-recoverable <literal>Difference</literal>s render the
+      two pieces different.</para>
 
-      <para>The following types of <literal>Difference</literal>s are
-      currently detected (the first two columns refer to the
-      <literal>DifferenceConstants</literal> class):</para>
+      <para>The types of <literal>Difference</literal>s that are
+      currently detected are listed in <xref linkend="docleveldiff"/>
+      to <xref linkend="otherdiff"/> (the first two columns refer to
+      the <literal>DifferenceConstants</literal> class).</para>
 
-      <table frame="all" rules="all" pgwide="1">
+      <table frame="all" rules="all" pgwide="1" id="docleveldiff">
         <title>Document level <literal>Difference</literal>s detected by
         <literal>DifferenceEngine</literal></title>
         <tgroup cols="4">
@@ -1046,7 +1051,7 @@
             <row>
               <entry><literal>ID</literal></entry>
               <entry><literal>Constant</literal></entry>
-              <entry><literal>revoverable</literal></entry>
+              <entry><literal>recoverable</literal></entry>
               <entry align="center">Description</entry>
             </row>
           </thead>
@@ -1068,16 +1073,16 @@
                 root element.</entry>
             </row>
             <row>
+              <entry><literal>DOCTYPE_PUBLIC_ID_ID</literal></entry>
               <entry><literal>DOCTYPE_PUBLIC_ID</literal></entry>
-              <entry><literal>DOCTYPE_PUBLIC_ID</literal></entry>
               <entry><literal>false</literal></entry>
               <entry>Both pieces of XML contain a DOCTYPE declaration
                 but the declarations specify different PUBLIC
                 identifiers.</entry>
             </row>
             <row>
+              <entry><literal>DOCTYPE_SYSTEM_ID_ID</literal></entry>
               <entry><literal>DOCTYPE_SYSTEM_ID</literal></entry>
-              <entry><literal>DOCTYPE_SYSTEM_ID</literal></entry>
               <entry><literal>true</literal></entry>
               <entry>Both pieces of XML contain a DOCTYPE declaration
                 but the declarations specify different SYSTEM
@@ -1088,7 +1093,10 @@
               <entry><literal>NODE_TYPE</literal></entry>
               <entry><literal>false</literal></entry>
               <entry>The test piece of XML contains a different type
-                of node than was expected.</entry>
+              of node than was expected.  This type of difference will
+              also occur if either the root control or test
+              <literal>Node</literal> is <literal>null</literal> while
+              the other is not.</entry>
             </row>
             <row>
               <entry><literal>NAMESPACE_PREFIX_ID</literal></entry>
@@ -1108,7 +1116,7 @@
         </tgroup>
       </table>
 
-      <table frame="all" rules="all" pgwide="1">
+      <table frame="all" rules="all" pgwide="1" id="elementleveldiff">
         <title>Element level <literal>Difference</literal>s detected by
         <literal>DifferenceEngine</literal></title>
         <tgroup cols="4">
@@ -1121,7 +1129,7 @@
             <row>
               <entry><literal>ID</literal></entry>
               <entry><literal>Constant</literal></entry>
-              <entry><literal>revoverable</literal></entry>
+              <entry><literal>recoverable</literal></entry>
               <entry align="center">Description</entry>
             </row>
           </thead>
@@ -1168,13 +1176,20 @@
               <entry><literal>ATTR_SEQUENCE</literal></entry>
               <entry><literal>true</literal></entry>
               <entry>The attributes on an element appear in different
-                order in the two pieces of XML.</entry>
+              order<footnote><para>Note that the order of attributes
+              is not significant in XML, different parsers may return
+              attributes in a different order even if parsing the same
+              XML document.  There is an option to turn this check off
+              - see <xref linkend="Comparing: Configuration"/> - but it is on
+              by default for backwards compatibility
+              reasons</para></footnote> in the two pieces of
+              XML.</entry>
             </row>
           </tbody>
         </tgroup>
       </table>
 
-      <table frame="all" rules="all" pgwide="1">
+      <table frame="all" rules="all" pgwide="1" id="attributeleveldiff">
         <title>Attribute level <literal>Difference</literal>s detected by
         <literal>DifferenceEngine</literal></title>
 
@@ -1188,7 +1203,7 @@
             <row>
               <entry><literal>ID</literal></entry>
               <entry><literal>Constant</literal></entry>
-              <entry><literal>revoverable</literal></entry>
+              <entry><literal>recoverable</literal></entry>
               <entry align="center">Description</entry>
             </row>
           </thead>
@@ -1198,10 +1213,14 @@
               <entry><literal>ATTR_VALUE_EXPLICITLY_SPECIFIED_ID</literal></entry>
               <entry><literal>ATTR_VALUE_EXPLICITLY_SPECIFIED</literal></entry>
               <entry><literal>true</literal></entry>
-              <entry>An attribute that is not required and has a
-              default value according to the content model of the
-              element in question has been specified explicitly in one
-              piece of XML but not in the other.</entry>
+              <entry>An attribute that has a default value according
+              to the content model of the element in question has been
+              specified explicitly in one piece of XML but not in the
+              other.<footnote><para>In order for this difference to be
+              detected the parser must have been in validating mode
+              when the piece of XML was parsed and the DTD or XML
+              Schema must have been available.</para></footnote></entry>
+
             </row>
             <row>
               <entry><literal>ATTR_NAME_NOT_FOUND_ID</literal></entry>
@@ -1221,7 +1240,7 @@
         </tgroup>
       </table>
 
-      <table frame="all" rules="all" pgwide="1">
+      <table frame="all" rules="all" pgwide="1" id="otherdiff">
         <title>Other <literal>Difference</literal>s detected by
         <literal>DifferenceEngine</literal></title>
 
@@ -1235,7 +1254,7 @@
             <row>
               <entry><literal>ID</literal></entry>
               <entry><literal>Constant</literal></entry>
-              <entry><literal>revoverable</literal></entry>
+              <entry><literal>recoverable</literal></entry>
               <entry align="center">Description</entry>
             </row>
           </thead>
@@ -1281,12 +1300,556 @@
         </tgroup>
       </table>
 
-      <para>Note that some of the listed differences may be ignored by
+      <para>Note that some of the differences listed may be ignored by
       the <literal>DifferenceEngine</literal> if certain configuration
       options have been specified.  See <xref
-      linkend="comparing-config"/> for details.</para>
+      linkend="Comparing: Configuration"/> for details.</para>
+
+      <para><literal>DifferenceEngine</literal> passes differences
+      found around as instances of the <literal>Difference</literal>
+      class.  In addition to the type of of difference this class also
+      holds information on the nodes that have been found to be
+      different.  The nodes are described by
+      <literal>NodeDetail</literal> instances that encapsulate the DOM
+      <literal>Node</literal> instance as well as the XPath expression
+      that locates the <literal>Node</literal> inside the given piece
+      of XML.  <literal>NodeDetail</literal> also contains a "value"
+      that provides more information on the actual values that have
+      been found to be different, the concrete interpretation depends
+      on the type of difference as can be seen in <xref
+      linkend="diffvalue"/>.</para>
+
+      <table frame="all" rules="all" pgwide="0" id="diffvalue">
+        <title>Contents of <literal>NodeDetail.getValue()</literal>
+        for <literal>Difference</literal>s</title>
+
+        <tgroup cols="2">
+          <colspec colname="id" align="center"/>
+          <colspec colname="value" align="left"/>
+
+          <thead>
+            <row>
+              <entry><literal>Difference.getId()</literal></entry>
+              <entry align="center"><literal>NodeDetail.getValue()</literal></entry>
+            </row>
+          </thead>
+
+          <tbody>
+            <row>
+              <entry><literal>HAS_DOCTYPE_DECLARATION_ID</literal></entry>
+              <entry><literal>"not null"</literal> if the document has
+              a DOCTYPE declaration, <literal>"null"</literal>
+              otherwise.</entry>
+            </row>
+            <row>
+              <entry><literal>DOCTYPE_NAME_ID</literal></entry>
+              <entry>The name of the root element.</entry>
+            </row>
+            <row>
+              <entry><literal>DOCTYPE_PUBLIC_ID</literal></entry>
+              <entry>The PUBLIC identifier.</entry>
+            </row>
+            <row>
+              <entry><literal>DOCTYPE_SYSTEM_ID</literal></entry>
+              <entry>The SYSTEM identifier.</entry>
+            </row>
+            <row>
+              <entry><literal>NODE_TYPE_ID</literal></entry>
+              <entry>If one node was absent: <literal>"not
+              null"</literal> if the node exists,
+              <literal>"null"</literal> otherwise.  If the node types
+              differ the value will be a string-ified version of
+              <literal>org.w3c.dom.Node.getNodeType()</literal>.</entry>
+            </row>
+            <row>
+              <entry><literal>NAMESPACE_PREFIX_ID</literal></entry>
+              <entry>The Namespace prefix.</entry>
+            </row>
+            <row>
+              <entry><literal>NAMESPACE_URI_ID</literal></entry>
+              <entry>The Namespace URI.</entry>
+            </row>
+            <row>
+              <entry><literal>ELEMENT_TAG_NAME_ID</literal></entry>
+              <entry>The tag name with any Namespace information
+              stripped.</entry>
+            </row>
+            <row>
+              <entry><literal>ELEMENT_NUM_ATTRIBUTES_ID</literal></entry>
+              <entry>The number of attributes present turned into a
+              <literal>String</literal>.</entry>
+            </row>
+            <row>
+              <entry><literal>HAS_CHILD_NODES_ID</literal></entry>
+              <entry><literal>"true"</literal> if the element has
+              child nodes, <literal>"false"</literal>
+              otherwise.</entry>
+            </row>
+            <row>
+              <entry><literal>CHILD_NODELIST_LENGTH_ID</literal></entry>
+              <entry>The number of child nodes present turned into a
+              <literal>String</literal>.</entry>
+            </row>
+            <row>
+              <entry><literal>CHILD_NODELIST_SEQUENCE_ID</literal></entry>
+              <entry>The sequence number of this child node turned into a
+              <literal>String</literal>.</entry>
+            </row>
+            <row>
+              <entry><literal>ATTR_SEQUENCE_ID</literal></entry>
+              <entry>The attribute's name.</entry>
+            </row>
+            <row>
+              <entry><literal>ATTR_VALUE_EXPLICITLY_SPECIFIED_ID</literal></entry>
+              <entry><literal>"true"</literal> if the attribute has
+              been specified, <literal>"false"</literal>
+              otherwise.</entry>
+            </row>
+            <row>
+              <entry><literal>ATTR_NAME_NOT_FOUND_ID</literal></entry>
+              <entry>The attribute's name or <literal>null</literal>.</entry>
+            </row>
+            <row>
+              <entry><literal>ATTR_VALUE_ID</literal></entry>
+              <entry>The attribute's value.</entry>
+            </row>
+            <row>
+              <entry><literal>COMMENT_VALUE_ID</literal></entry>
+              <entry>The actual comment.</entry>
+            </row>
+            <row>
+              <entry><literal>PROCESSING_INSTRUCTION_TARGET_ID</literal></entry>
+              <entry>The processing instruction's target.</entry>
+            </row>
+            <row>
+              <entry><literal>PROCESSING_INSTRUCTION_DATA_ID</literal></entry>
+              <entry>The processing instruction's data.</entry>
+            </row>
+
+            <row>
+              <entry><literal>CDATA_VALUE_ID</literal></entry>
+              <entry>The content of the CDATA section.</entry>
+            </row>
+            <row>
+              <entry><literal>TEXT_VALUE_ID</literal></entry>
+              <entry>The actual text.</entry>
+            </row>
+          </tbody>
+        </tgroup>
+      </table>
+
+      <para>As said in the first paragraph you won't deal with
+      <literal>DifferenceEngine</literal> directly in most cases.  In
+      cases where <literal>Diff</literal> or
+      <literal>DetailedDiff</literal> don't provide what you need
+      you'd create an instance of <literal>DifferenceEngine</literal>
+      passing a <literal>ComparisonController</literal> in the
+      constructor and invoke <literal>compare</literal> with your DOM
+      trees to compare as well as a
+      <literal>DifferenceListener</literal> and
+      <literal>ElementQualifier</literal>.  The listener will be
+      called on any differences while the <literal>control</literal>
+      method is executing.</para>
+
+      <example>
+        <title>Using <literal>DifferenceEngine</literal>
+          Directly</title>
+        <programlisting language="Java"><![CDATA[
+class MyDifferenceListener implements DifferenceListener {
+    private boolean calledFlag = false;
+    public boolean called() { return calledFlag; }
+
+    public int differenceFound(Difference difference) {
+        calledFlag = true;
+        return RETURN_ACCEPT_DIFFERENCE;
+    }
+
+    public void skippedComparison(Node control, Node test) {
+    }
+}
+
+DifferenceEngine engine = new DifferenceEngine(myComparisonController);
+MyDifferenceListener listener = new MyDifferenceListener();
+engine.compare(controlNode, testNode, listener,
+               myElementQualifier);
+System.err.println("There have been "
+                   + (listener.called() ? "" : "no ")
+                   + "differences.");
+]]></programlisting></example>
     </section>
 
+    <section id="ComparisonController">
+      <title><literal>ComparisonController</literal></title>
+
+      <para>The <literal>ComparisonController</literal>'s job is to
+      decide whether a comparison should be halted after a difference
+      has been found.  Its interface is:</para>
+
+      <programlisting language="Java"><![CDATA[
+    /**
+     * Determine whether a Difference that the listener has been notified of
+     *  should halt further XML comparison. Default behaviour for a Diff
+     *  instance is to halt if the Difference is not recoverable.
+     * @see Difference#isRecoverable
+     * @param afterDifference the last Difference passed to <code>differenceFound</code>
+     * @return true to halt further comparison, false otherwise
+     */
+    boolean haltComparison(Difference afterDifference);
+]]></programlisting>
+
+      <para>Whenever a difference has been detected by the
+      <literal>DifferenceEngine</literal> the
+      <literal>haltComparison</literal> method will be called
+      immediately after the <literal>DifferenceListener</literal> has
+      been informed of the difference.  This is true no matter what
+      type of <literal>Difference</literal> has been found or which
+      value the <literal>DifferenceListener</literal> has
+      returned.</para>
+
+      <para>The only implementations of
+      <literal>ComparisonController</literal> that ship with XMLUnit
+      are <literal>Diff</literal> and <literal>DetailedDiff</literal>,
+      see <xref linkend="Diff"/> for details about them.</para>
+
+      <para>A <literal>ComparisonController</literal> that halted the
+      comparison on any non-recoverable difference could be
+      implemented as:</para>
+
+      <example>
+        <title>A Simple
+          <literal>ComparisonController</literal></title>
+        <programlisting language="Java"><![CDATA[
+public class HaltOnNonRecoverable implements ComparisonController {
+    public boolean haltComparison(Difference afterDifference) {
+        return !afterDifference.isRecoverable();
+    }
+}
+]]></programlisting></example>
+    </section>
+
+    <section id="DifferenceListener">
+      <title><literal>DifferenceListener</literal></title>
+
+      <para><literal>DifferenceListener</literal> contains two
+      callback methods that are invoked by the
+      <literal>DifferenceEngine</literal> when differences are
+      detected:</para>
+
+      <programlisting language="Java"><![CDATA[
+    /**
+     * Receive notification that 2 nodes are different.
+     * @param difference a Difference instance as defined in {@link
+     * DifferenceConstants DifferenceConstants} describing the cause
+     * of the difference and containing the detail of the nodes that
+     * differ
+     * @return int one of the RETURN_... constants describing how this
+     * difference was interpreted
+     */
+    int differenceFound(Difference difference);
+
+    /**
+     * Receive notification that a comparison between 2 nodes has been skipped
+     *  because the node types are not comparable by the DifferenceEngine
+     * @param control the control node being compared
+     * @param test the test node being compared
+     * @see DifferenceEngine
+     */
+    void skippedComparison(Node control, Node test);
+]]></programlisting>
+
+      <para><literal>differenceFound</literal> is invoked by
+      <literal>DifferenceEngine</literal> as soon as a difference has
+      been detected.  The return value of that method is completely
+      ignored by <literal>DifferenceEngine</literal>, it becomes
+      important when used together with <literal>Diff</literal>,
+      though (see <xref linkend="Diff"/>).  The return value should be
+      one of the three constants defined in the the
+      <literal>DifferenceListener</literal> interface:</para>
+
+      <programlisting language="Java"><![CDATA[
+    /** 
+     * Standard return value for the <code>differenceFound</code> method.
+     * Indicates that the <code>Difference</code> is interpreted as defined 
+     * in {@link DifferenceConstants DifferenceConstants}.
+     */
+    int RETURN_ACCEPT_DIFFERENCE;
+    /** 
+     * Override return value for the <code>differenceFound</code> method.
+     * Indicates that the nodes identified as being different should be 
+     * interpreted as being identical.
+     */
+    int RETURN_IGNORE_DIFFERENCE_NODES_IDENTICAL;
+    /** 
+     * Override return value for the <code>differenceFound</code> method.
+     * Indicates that the nodes identified as being different should be 
+     * interpreted as being similar.
+     */
+    int RETURN_IGNORE_DIFFERENCE_NODES_SIMILAR;
+]]></programlisting>
+
+      <para>The <literal>skippedComparison</literal> method is
+      invoked if the <literal>DifferenceEngine</literal> encounters
+      two <literal>Node</literal>s it cannot compare.  Before invoking
+      <literal>skippedComparison</literal>
+      <literal>DifferenceEngine</literal> will have invoked
+      <literal>differenceFound</literal> with a
+      <literal>Difference</literal> of type
+      <literal>NODE_TYPE</literal>.</para>
+
+      <para>A custom <literal>DifferenceListener</literal> that
+      ignored any DOCTYPE related differences could be written
+      as:</para>
+
+      <example>
+        <title>A <literal>DifferenceListener</literal> that Ignores
+          DOCTYPE Differences</title>
+        <programlisting language="Java"><![CDATA[
+public class IgnoreDoctype implements DifferenceListener {
+    private static final int[] IGNORE = new int[] {
+        DifferenceConstants.HAS_DOCTYPE_DECLARATION_ID,
+        DifferenceConstants.DOCTYPE_NAME_ID,
+        DifferenceConstants.DOCTYPE_PUBLIC_ID_ID,
+        DifferenceConstants.DOCTYPE_SYSTEM_ID_ID
+    };
+
+    static {
+        Arrays.sort(IGNORE);
+    }
+
+    public int differenceFound(Difference difference) {
+        return Arrays.binarySearch(IGNORE, difference.getId()) >= 0
+            ? RETURN_IGNORE_DIFFERENCE_NODES_IDENTICAL
+            : RETURN_ACCEPT_DIFFERENCE;
+    }
+    
+    public void skippedComparison(Node control, Node test) {
+    }
+}
+]]></programlisting></example>
+
+      <para>Apart from <literal>Diff</literal> and
+      <literal>DetailedDiff</literal> XMLUnit ships with an additional
+      implementation of <literal>DifferenceListener</literal>.</para>
+
+      <section id="IgnoreTextAndAttributeValuesDifferenceListener">
+        <title><literal>IgnoreTextAndAttributeValuesDifferenceListener</literal></title>
+
+        <para><literal>IgnoreTextAndAttributeValuesDifferenceListener</literal>
+        doesn't do anything in <literal>skippedComparison</literal>.
+        It "downgrades" <literal>Difference</literal>s of type
+        <literal>ATTR_VALUE</literal>,
+        <literal>ATTR_VALUE_EXPLICITLY_SPECIFIED</literal> and
+        <literal>TEXT_VALUE</literal> to recoverable
+        differences.</para>
+
+        <para>This means if instances of
+        <literal>IgnoreTextAndAttributeValuesDifferenceListener</literal>
+        are used together with <literal>Diff</literal> then two pieces
+        of XML will be considered similar if they have the same basic
+        structure.  They are not considered identical, though.</para>
+
+        <para>Note that the list of ignored differences doesn't cover
+        all textual differences.  You should configure XMLUnit to
+        ignore comments and whitespace and to consider CDATA sections
+        and text nodes to be the same (see <xref
+        linkend="Comparing: Configuration"/>) in order to cover
+        <literal>COMMENT_VALUE</literal> and
+        <literal>CDATA_VALUE</literal> as well.</para>
+
+      </section>
+    </section>
+
+    <section id="ElementQualifier">
+      <title><literal>ElementQualifier</literal></title>
+
+      <para>When <literal>DifferenceEngine</literal> encounters a list
+      of DOM <literal>Element</literal>s as children of another
+      <literal>Element</literal> it will ask the configured
+      <literal>ElementQualifier</literal> which
+      <literal>Element</literal> of the control piece of XML should be
+      compared to which of the test piece.  Its contract is:</para>
+
+      <programlisting language="Java"><![CDATA[
+    /**
+     * Determine whether two elements are comparable
+     * @param control an Element from the control XML NodeList
+     * @param test an Element from the test XML NodeList
+     * @return true if the elements are comparable, false otherwise
+     */
+    boolean qualifyForComparison(Element control, Element test); 
+]]></programlisting>
+
+      <para>For any given <literal>Element</literal> in the control
+      piece of XML <literal>DifferenceEngine</literal> will cycle
+      through the corresponding list of <literal>Element</literal>s in
+      the test piece of XML until
+      <literal>qualifyForComparison</literal> has returned
+      <literal>true</literal> or the test document is
+      exhausted.</para>
+
+      <para>When using <literal>DifferenceEngine</literal> or
+      <literal>Diff</literal> it is completely legal to set the
+      <literal>ElementQualifier</literal> to <literal>null</literal>.
+      In this case any kind of <literal>Node</literal> is compared to
+      the test <literal>Node</literal> that appears at the same
+      position in the sequence.</para>
+
+      <example id="eq-nodelist-example">
+        <title>Example Nodes for <literal>ElementQualifier</literal>
+          (the comments are not part of the example)</title>
+        <programlisting language="XML"><![CDATA[
+<!-- control piece of XML -->
+<parent>
+  <child1/>                        <!-- control node 1 -->
+  <child2/>                        <!-- control node 2 -->
+  <child2 foo="bar">xyzzy</child2> <!-- control node 3 -->
+  <child2 foo="baz"/>              <!-- control node 4 -->
+</parent>
+
+<!-- test piece of XML -->
+<parent>
+  <child2 foo="baz"/>              <!-- test node 1 -->
+  <child1/>                        <!-- test node 2 -->
+  <child2>xyzzy</child2>           <!-- test node 3 -->
+  <child2 foo="bar"/>              <!-- test node 4 -->
+</parent>
+]]></programlisting></example>
+
+      <para>Taking <xref linkend="eq-nodelist-example"/> without any
+      <literal>ElementQualifier</literal>
+      <literal>DifferenceEngine</literal> will compare control node
+      <literal>n</literal> to test node <literal>n</literal> for
+      <literal>n</literal> between 1 and 4.  In many cases this is
+      exactly what is desired, but sometimes
+      <literal><![CDATA[<a><b/><c/></a>]]></literal> should be similar
+      to <literal><![CDATA[<a><c/><b/></a>]]></literal> because the
+      order of elements doesn't matter - this is when you'd use a
+      different <literal>ElementQualifier</literal>.  XMLUnit ships
+      with several implementations.</para>
+
+      <section id="ElementNameQualifier">
+        <title><literal>ElementNameQualifier</literal></title>
+
+        <para>Only <literal>Element</literal>s with the same name -
+        and Namespace URI if present - qualify.</para>
+
+        <para>In <xref linkend="eq-nodelist-example"/> this means
+        control node 1 will be compared to test node 2.  Then control
+        node 2 will be compared to test node 3 because
+        <literal>DifferenceEngine</literal> will start to search for
+        the matching test <literal>Element</literal> at the second
+        test node, the same sequence number the control node is at.
+        Control node 3 is compared to test node 3 as well and control
+        node 4 to test node 4.</para>
+      </section>
+
+      <section id="ElementNameAndAttributeQualifier">
+        <title><literal>ElementNameAndAttributeQualifier</literal></title>
+
+        <para>Only <literal>Element</literal>s with the same name -
+        and Namespace URI if present - as well as the same values for
+        all attributes given in
+        <literal>ElementNameAndAttributeQualifier</literal>'s
+        constructor qualify.</para>
+
+        <para>Let's say <literal>"foo"</literal> has been passed to
+        <literal>ElementNameAndAttributeQualifier</literal>'s
+        constructor when looking at <xref
+        linkend="eq-nodelist-example"/>.  This again means control
+        node 1 will be compared to test node 2 since they do have the
+        same name and no value at all for attribute
+        <literal>"foo"</literal>.  Then control node 2 will be
+        compared to test node 3 - again, no value for
+        <literal>"foo"</literal>.  Control node 3 is compared to test
+        node 4 as they have the same value <literal>"bar"</literal>.
+        Finally control node 4 is compared to test node 1; here
+        <literal>DifferenceEngine</literal> searches from the
+        beginning of the test node list after test node 4 didn't
+        match.</para>
+
+        <para>There are three constructors in
+        <literal>ElementNameAndAttributeQualifier</literal>.  The
+        no-arg constructor creates an instance that compares all
+        attributes while the others will compare a single attribute or
+        a given subset of all attributes.</para>
+      </section>
+
+      <section id="ElementNameAndTextQualifier">
+        <title><literal>ElementNameAndTextQualifier</literal></title>
+
+        <para>Only <literal>Element</literal>s with the same name -
+        and Namespace URI if present - as well as the same text
+        content nested into them qualify.</para>
+
+        <para>In <xref linkend="eq-nodelist-example"/> this means
+        control node 1 will be compared to test node 2 since they both
+        don't have any nested text at all.  Then control node 2 will
+        be compared to test node 4.  Control node 3 is compared to
+        test node 3 since they have the same nested text and control
+        node 4 to test node 4.</para>
+      </section>
+
+      <section id="MultiLevelElementNameAndTextQualifier">
+        <title><literal>org.custommonkey.xmlunit.examples.MultiLevelElementNameAndTextQualifier</literal></title>
+
+        <para>All <literal>ElementQualifier</literal>s seen so far
+        only looked at the <literal>Element</literal>s themselves and
+        not at the structure nested into them at a deeper level.  A
+        frequent user question has been which
+        <literal>ElementQualifier</literal> should be used if the
+        pieces of XML in <xref linkend="htmltable"/> should be
+        considered similar.</para>
+
+        <example id="htmltable">
+          <title>Example for
+          <literal>MultiLevelElementNameAndTextQualifier</literal>
+          (the comments are not part of the example)</title>
+          <programlisting language="HTML"><![CDATA[
+<!-- control -->
+<table>
+  <tr>            <!-- control row 1 -->
+    <td>foo</td>
+  </tr>
+  <tr>            <!-- control row 2 -->
+    <td>bar</td>
+  </tr>
+</table>
+
+<!-- test -->
+<table>
+  <tr>            <!-- test row 1 -->
+    <td>bar</td>
+  </tr>
+  <tr>            <!-- test row 2 -->
+    <td>foo</td>
+  </tr>
+</table>
+]]></programlisting></example>
+
+        <para>At first glance
+        <literal>ElementNameAndTextQualifier</literal> should work but
+        it doesn't.  When <literal>DifferenceEngine</literal>
+        processed the children of <literal>table</literal> it would
+        compare control row 1 to test row 1 since both
+        <literal>tr</literal> elements have the same name and both
+        have no textual content at all.</para>
+
+        <para>What is needed in this case is an
+        <literal>ElementQualifier</literal> that looks at the element's
+        name, as well as the name of the first child element and the
+        text nested into that first child element.  This is what
+        <literal>MultiLevelElementNameAndTextQualifier</literal> does.
+        <literal>MultiLevelElementNameAndTextQualifier</literal>'s
+        constructor expects a single argument which is the nesting
+        level of the expected text.  If you use an argument of 1,
+        <literal>MultiLevelElementNameAndTextQualifier</literal> is
+        identical to <literal>ElementNameAndTextQualifier</literal>.
+        In <xref linkend="htmltable"/> a value of 2 would be
+        needed.</para>
+      </section>
+
+    </section>
+
     <section id="Diff">
       <title><literal>Diff</literal> and
       <literal>DetailedDiff</literal></title>
@@ -1301,34 +1864,319 @@
       is what <literal>Diff</literal> does) and finding all
       differences between them (this is what
       <literal>DetailedDiff</literal> does).</para>
-    </section>
 
-    <section id="ElementQualifier">
-      <title><literal>ElementQualifier</literal></title>
-    </section>
+      <para><literal>DetailedDiff</literal> is a subclass of
+      <literal>Diff</literal> and can only be constructed by creating
+      a <literal>Diff</literal> instance first.</para>
 
-    <section id="DifferenceListener">
-      <title><literal>DifferenceListener</literal></title>
-    </section>
+      <para>The major difference between them is their implementation
+      of the <literal>ComparisonController</literal> interface:
+      <literal>DetailedDiff</literal> will never stop the comparison
+      since it wants to collect all differences.
+      <literal>Diff</literal> in turn will halt the comparison as soon
+      as the first <literal>Difference</literal> is found that is not
+      recoverable.  In addition <literal>DetailedDiff</literal>
+      collects all <literal>Difference</literal>s in a list and
+      provides access to it.</para>
 
-    <section id="ComparisonController">
-      <title><literal>ComparisonController</literal></title>
+      <para>By default <literal>Diff</literal> will consider two
+      pieces of XML as identical if no differences have been found at
+      all, similar if all differences that have been found have been
+      recoverable (see <xref linkend="docleveldiff"/> to <xref
+      linkend="otherdiff"/>) and different as soon as any
+      non-recoverable difference has been found.</para>
+
+      <para>It is possible to specify a
+      <literal>DifferenceListener</literal> to <literal>Diff</literal>
+      using the <literal>overrideDifferenceListener</literal> method.
+      In this case each <literal>Difference</literal> will be
+      evaluated by the passed in
+      <literal>DifferenceListener</literal>.  By returning
+      <literal>RETURN_IGNORE_DIFFERENCE_NODES_IDENTICAL</literal> the
+      custom listener can make <literal>Diff</literal> ignore the
+      difference completely.  Likewise any
+      <literal>Difference</literal> for which the custom listener
+      returns
+      <literal>RETURN_IGNORE_DIFFERENCE_NODES_SIMILAR</literal> will
+      be treated as if the <literal>Difference</literal> was
+      recoverable.</para>
+
+      <para>There are several overloads of the <literal>Diff</literal>
+      constructor that allow you to specify your piece of XML in many
+      ways.  There are overloads that accept additional
+      <literal>DifferenceEngine</literal> and
+      <literal>ElementQualifier</literal> arguments.  Passing in a
+      <literal>DifferenceEngine</literal> of your own is the only way
+      to use a <literal>ComparisonController</literal> other than
+      <literal>Diff</literal>.</para>
+
+      <para>Note that <literal>Diff</literal> and
+      <literal>DetailedDiff</literal> use
+      <literal>ElementNameQualifier</literal> as their default
+      <literal>ElementQualifier</literal>.  This is different from
+      <literal>DifferenceEngine</literal> which defaults to no
+      <literal>ElementQualifier</literal> at all.</para>
+
+      <para>To use a custom <literal>ElementQualifier</literal> you
+      can also use the <literal>overrideElementQualifier</literal>
+      method.  Use this with an argument of <literal>null</literal> to
+      unset the default <literal>ElementQualifier</literal> as
+      well.</para>
+
+      <para>To compare two pieces of XML you'd create a
+      <literal>Diff</literal> instance from those two pieces and
+      invoke <literal>identical</literal> to check that there have
+      been no differences at all and <literal>similar</literal> to
+      check that any difference, if any, has been recoverable.  If the
+      pieces are identical they are also similar.  Likewise if they
+      are not similar they can't be identical either.</para>
+
+      <example>
+        <title>Comparing Two Pieces of XML Using
+        <literal>Diff</literal></title>
+        <programlisting language="Java"><![CDATA[
+Diff d = new Diff("<a><b/><c/></a>", "<a><c/><b/></a>");
+assertFalse(d.identical()); // CHILD_NODELIST_SEQUENCE Difference
+assertTrue(d.similar());
+]]></programlisting></example>
+
+      <para>The result of the comparison is cached in
+      <literal>Diff</literal>, repeated invocations of
+      <literal>identical</literal> or <literal>similar</literal> will
+      not reevaluate the pieces of XML.</para>
+
+      <para><literal>DetailedDiff</literal> provides only a single
+      constructor that expects a <literal>Diff</literal> as argument.
+      Don't use <literal>DetailedDiff</literal> if all you need to
+      know is whether two pieces of XML are identical/similar - use
+      <literal>Diff</literal> directly since its short-cut
+      <literal>ComparisonController</literal> implementation will save
+      time in this case.</para>
+
+      <example>
+        <title>Finding All Differences Using
+        <literal>DetailedDiff</literal></title>
+        <programlisting language="Java"><![CDATA[
+Diff d = new Diff("<a><b/><c/></a>", "<a><c/><b/></a>");
+DetailedDiff dd = new DetailedDiff(d);
+dd.overrideElementQualifier(null);
+assertFalse(dd.similar());
+List l = dd.getAllDifferences();
+assertEquals(2, l.size()); // expected <b/> but was <c/> and vice versa
+]]></programlisting></example>
+
     </section>
 
-    <section id="comparing-junit3">
+    <section id="Comparing: JUnit 3">
       <title>JUnit 3.x Convenience Methods</title>
+
+      <para><literal>XMLAssert</literal> and
+      <literal>XMLTestCase</literal> contain quite a few overloads of
+      methods for comparing two pieces of XML.</para>
+
+      <para>The method's names use the word <literal>Equal</literal>
+      to mean the same as <literal>similar</literal> in the
+      <literal>Diff</literal> class (or throughout this guide).  So
+      <literal>assertXMLEqual</literal> will assert that only
+      recoverable differences have been encountered where
+      <literal>assertXMLNotEqual</literal> asserts that some
+      differences have been non-recoverable.
+      <literal>assertXMLIdentical</literal> asserts that there haven't
+      been any differences at all while
+      <literal>assertXMLNotIdentical</literal> asserts that there have
+      been differences (recoverable or not).</para>
+
+      <para>Most of the overloads of <literal>assertXMLEqual</literal>
+      just provide different means to specify the pieces of XML as
+      <literal>String</literal>s, <literal>InputSource</literal>s,
+      <literal>Reader</literal>s<footnote><para>See <xref
+      linkend="Providing Input to XMLUnit"/> for some advice on choosing your input
+      format.</para></footnote> or <literal>Document</literal>s.  For each
+      method there is a version that takes an additional
+      <literal>err</literal> argument which is used to create the
+      message if the assertion fails.</para>
+
+      <para>If you don't need any control over the
+      <literal>ElementQualifier</literal> or
+      <literal>DifferenceListener</literal> used by
+      <literal>Diff</literal> these methods will save some boilerplate
+      code.  If <literal>CONTROL</literal> and <literal>TEST</literal>
+      are pieces of XML represented as one of the supported inputs
+      then</para>
+
+      <programlisting language="Java"><![CDATA[
+Diff d = new Diff(CONTROL, TEST);
+assertTrue("expected pieces to be similar, " + d.toString(),
+           d.similar());
+]]></programlisting>
+
+      <para>and</para>
+
+      <programlisting language="Java"><![CDATA[
+assertXMLEqual("expected pieces to be similar", CONTROL, TEST);
+]]></programlisting>
+
+      <para>are equivalent.</para>
+
+      <para>If you need more control over the <literal>Diff</literal>
+      instance there is a version of <literal>assertXMLEqual</literal>
+      (and <literal>assertXMLIdentical</literal>) that accepts a
+      <literal>Diff</literal> instance as its argument as well as a
+      <literal>boolean</literal> indicating whether you expect the
+      <literal>Diff</literal> to be <literal>similar</literal>
+      (<literal>identical</literal>) or not.</para>
+
+      <para><literal>XMLTestCase</literal> contains a couple of
+      <literal>compareXML</literal> methods that really are only
+      shortcuts to <literal>Diff</literal>'s constructors.</para>
+
+      <para>There is no way to use <literal>DifferenceEngine</literal>
+      or <literal>DetailedDiff</literal> directly via the convenience
+      methods.</para>
+
     </section>
 
-    <section id="comparing-config">
+    <section id="Comparing: Configuration">
       <title>Configuration Options</title>
+
+      <para>Unless you are using <literal>Document</literal> or
+      <literal>DOMSource</literal> overrides when specifying your
+      pieces of XML, XMLUnit will use the configured XML parsers (see
+      <xref linkend="JAXP"/>) and <literal>EntityResolver</literal>s
+      (see <xref linkend="EntityResolver"/>).  There configuration
+      options to use different settings for the control and test
+      pieces of XML.</para>
+
+      <para>In addition some of the other configuration settings may
+      lead to XMLUnit using the configured XSLT transformer (see <xref
+      linkend="JAXP"/>) under the covers.</para>
+
+      <section id="Whitespace Handling">
+        <title>Whitespace Handling</title>
+
+        <para>Two different configuration options affect how XMLUnit
+        treats whitespace in comparisons:</para>
+
+        <itemizedlist>
+
+          <listitem>Element Content Whitespace (see <xref
+          linkend="Basic: Element Content Whitespace"/>)
+
+            <para>If XMLUnit has been configured to ignore element
+            content whitespace it will trim any text nodes found by
+            the parser.  This means that there won't appear to be any
+            textual content in element <literal>&lt;foo&gt;</literal>
+            for the following example.  If you don't set
+            <literal>XMLUnit.setIgnoreWhitespace</literal> there would
+            be textual content consisting of a new line
+            character.</para>
+
+            <programlisting language="XML"><![CDATA[
+<foo>
+</foo>
+]]></programlisting>
+
+            <para>At the same time the following two
+            <literal>&lt;foo&gt;</literal> elements will be considered
+            identical if the option has been enabled, though.</para>
+
+            <programlisting language="XML"><![CDATA[
+<foo>bar</foo>
+<foo> bar </foo>
+]]></programlisting>
+
+            <para>When this option is set to <literal>true</literal>,
+            <literal>Diff</literal> will use the XSLT transformer
+            under the covers.</para>
+          </listitem>
+
+          <listitem>"Normalizing" Whitespace
+
+            <para>If you set
+            <literal>XMLUnit.setNormalizeWhitespace</literal> to true
+            then XMLUnit will replace any kind of whitespace found in
+            character content with a SPACE character and collapse
+            consecutive whitespace characters to a single SPACE.  It
+            will also trim the resulting character content on both
+            ends.</para>
+
+            <para>The following two <literal>&lt;foo&gt;</literal>
+            elements will be considered identical if the option has
+            been set:</para>
+
+            <programlisting language="XML"><![CDATA[
+<foo>bar baz</foo>
+<foo> bar
+            baz</foo>
+]]></programlisting>
+
+            <para>Note that this is not related to "normalizing" the
+            document as a whole (see <xref
+            linkend="Normalizing Documents"/>).</para>
+
+          </listitem> 
+
+        </itemizedlist>
+      </section>
+
+      <section id="Normalizing Documents">
+        <title>"Normalizing" <literal>Document</literal>s</title>
+
+        <para>"Normalize" in this context corresponds to the
+        <literal>normalize</literal> method in DOM's
+        <literal>Document</literal> class.  It is the process of
+        merging adjacent <literal>Text</literal> nodes and is not
+        related to "normalizing whitespace" as described in the
+        previous section.</para>
+
+        <para>Usually you don't need to care about this option since
+        the XML parser is required to normalize the
+        <literal>Document</literal> when creating it.  The only reason
+        you may want to change the option via
+        <literal>XMLUnit.setNormalize</literal> is that your
+        <literal>Document</literal> instances have not been created by
+        an XML parser but rather been put together in memory using the
+        DOM API directly.</para>
+      </section>
+
+      <section id="Ignoring Comments">
+        <title>Ignoring Comments</title>
+
+        <para>Using <literal>XMLUnit.setIgnoreComments</literal> you
+        can make XMLUnit's difference engine ignore comments
+        completely.</para>
+
+        <para>When this option is set to <literal>true</literal>,
+        <literal>Diff</literal> will use the XSLT transformer under
+        the covers.</para>
+      </section>
+
+      <section id="Treating CDATA Sections and Text Nodes Alike">
+        <title>Treating CDATA Sections and Text Nodes Alike</title>
+
+        <para>It is not always necessary to know whether a text has
+        been put into a CDATA section or not.  Using
+        <literal>XMLUnit.setIgnoreDiffBetweenTextAndCDATA</literal>
+        you can make XMLUnit consider the following two pieces of XML
+        identical:</para>
+
+        <programlisting language="XML"><![CDATA[
+<foo>&lt;bar&gt;</foo>
+]]></programlisting>
+        <programlisting language="XML">
+&lt;foo>&lt;![CDATA[&lt;bar&gt;]]&gt;&lt;/foo>
+</programlisting>
+      </section>
+
     </section>
 
   </section>
 
-  <section id="Validating"><title>Validating XML documents</title>
+  <section id="Validating XML Documents">
+    <title>Validating XML Documents</title>
 
-    <section id="validating-basics">
-      <title>The <literal>Validator</literal> class</title>
+    <section id="The Validator Class">
+      <title>The <literal>Validator</literal> Class</title>
 
       <para>The <literal>Validator</literal> class encapsulates
       XMLUnit's validation support.  It will use the
@@ -1346,7 +2194,7 @@
       multiple) Schema(s) as well.  Schema validation requires an XML
       parser that supports it, of course.</para>
 
-      <section id="validating-dtd">
+      <section id="DTD Validation">
         <title>DTD Validation</title>
       </section>
 
@@ -1357,12 +2205,12 @@
       object using one of the single argument constructors.</para>
 
       <example>
-        <title>Validating against the DTD defined in
+        <title>Validating Against the DTD Defined in
           <literal>DOCTYPE</literal></title>
         <programlisting language="Java"><![CDATA[
 InputSource is = new InputSource(new FileInputStream(myXmlDocument));
 Validator v = new Validator(is);
-bool isValid = v.isValid();
+boolean isValid = v.isValid();
 ]]></programlisting></example>
 
       <para>If the piece of XML doesn't contain any
@@ -1379,14 +2227,14 @@
       can be resolved by your parser.</para>
 
       <example>
-        <title>Validating a piece of XML that doesn't contain a
+        <title>Validating a Piece of XML that doesn't Contain a
         <literal>DOCTYPE</literal></title>
         <programlisting language="Java"><![CDATA[
 InputSource is = new InputSource(new FileInputStream(myXmlDocument));
 Validator v = new Validator(is,
-                            (new File(myDTD)).toURI().toURL(),
+                            (new File(myDTD)).toURI().toURL().toString(),
                             myPublicId);
-bool isValid = v.isValid();
+boolean isValid = v.isValid();
 ]]></programlisting></example>
 
       <para>If the piece of XML already has the correct
@@ -1401,12 +2249,12 @@
           <literal>systemId</literal>.
 
       <example>
-        <title>Validating against a local DTD</title>
+        <title>Validating Against a Local DTD</title>
         <programlisting language="Java"><![CDATA[
 InputSource is = new InputSource(new FileInputStream(myXmlDocument));
 Validator v = new Validator(is,
-                            (new File(myDTD)).toURI().toURL());
-bool isValid = v.isValid();
+                            (new File(myDTD)).toURI().toURL().toString());
+boolean isValid = v.isValid();
 ]]></programlisting></example>
         </listitem>
 
@@ -1416,22 +2264,22 @@
           Validator.
 
           <para>This approach would allow you to use an OASIS
-          catalog<footnote><ulink
-          url="http://www.oasis-open.org/committees/download.php/14809/xml-catalogs.html">http://www.oasis-open.org/committees/download.php/14809/xml-catalogs.html</ulink></footnote>
+          catalog<footnote><para><ulink
+          url="http://www.oasis-open.org/committees/download.php/14809/xml-catalogs.html">http://www.oasis-open.org/committees/download.php/14809/xml-catalogs.html</ulink></para></footnote>
           in conjunction with the Apache XML Resolver
-          library<footnote><ulink
-          url="http://xml.apache.org/commons/components/resolver/index.html">http://xml.apache.org/commons/components/resolver/index.html</ulink></footnote>
+          library<footnote><para><ulink
+          url="http://xml.apache.org/commons/components/resolver/index.html">http://xml.apache.org/commons/components/resolver/index.html</ulink></para></footnote>
           to resolve the DTD location as well as the location of any
      ...
 
[truncated message content]

Thread: SF.net SVN: xmlunit: [185] trunk/xmlunit/src/user-guide/XMLUnit-Java.xml

XMLUnit provides assertions that help testing code that produces XML.

xmlunit-commits