updating harness documentation for new features

1 files changed, 40 insertions, 17 deletions

diff --git a/tests/readme-tests-module.html b/tests/readme-tests-module.html
index c67a20bd7..bb47df117 100644
--- a/tests/readme-tests-module.html
+++ b/tests/readme-tests-module.html
@@ -76,8 +76,9 @@ Tests differ in the kind of harness they use and their target.
      </tr>
 </table>
 
-<h3><a name="#harness"></a>Harness</h3>
+<h3><a name="harness"></a>Harness</h3>
    
+<h4><a name="harness-tests"></a>Harness tests</h4>
 These are compiler test cases, the preferred form for
 any compiler tests.  The XML files are test definitions,
 and the subdirectories contain the test sources (many of which
@@ -108,6 +109,25 @@ segregated for convenience as follows:
        These are tests to exercise the test harness itself.
        </li>
 </ul>
+The tests specify most anything one could want to do with
+compile/run variants.  The best summary of the test specification
+format is the <a href="ajcTestSuite.dtd">ajcTestSuite.dtd</a>.
+
+<p>
+To write a new test, evolve an existing example.  See the dtd and/or
+the javadoc for the testing harness implementation in the 
+<code>testing</code> module for more details.
+
+<p>To write a test case for a bug, see 
+  <a href="readme-writing-compiler-tests.html">
+           readme-writing-compiler-tests.html</a>.
+   Many bugs that first present in an IDE or the Ant taskdef
+   are compiler bugs that can be written in this form.
+   We <em>much</em> prefer this automated form over
+   manual steps specified in a bug report.
+
+<h4><a name="harness-runs"></a>Running the harness</h4>
+<p>
 To run the harness, use <code>org.aspectj.testing.drivers.Harness</code>,
 in the <code>testing-drivers</code> module. Since that is the main class
 for the <code>testing-drivers</code> module, you can build and 
@@ -119,27 +139,30 @@ run the harness as follows:
   java -jar ../aj-build/jars/testing-drivers-all.jar ajcTests.xml
 </pre>
  
-For help on harness options, use <code>-help</code>.   
-For more help on options for harness components, see 
+The harness enable you to
+<ul>
+  <li>control output, hiding streams and logging messages</li>
+  <li>select tests using keywords, bug ID's, or titles</li>
+  <li>pass compiler arguments on the harness command line</li>
+  <li>use different compiler wrappers - the command-line compiler,
+      the AJDE IDE support (mostly sans GUI), or 
+      the Ant taskdef support.</li>
+  <li>fork java run steps</li>
+</ul>
+For a listing of harness options, use <code>-help</code>.   
+For a fuller description of harness options and components, see 
   <a href="../testing-drivers/src/org/aspectj/testing/drivers/package.html">
   the package documentation for the harness</a>.
-Note in particular how to select tests using keywords 
-and how compiler arguments can be passed on the harness command line.
-<p>
-To write a new test, evolve an existing example.  See the dtd and/or
-the javadoc for the testing harness implementation in the 
-<code>testing</code> module for more details.
-
-<p>To write a test case for a bug, see 
-  <a href="readme-writing-compiler-tests.html">
-           readme-writing-compiler-tests.html</a>.
            
-<h3><a name="#product"></a>Product</h3>
+<h3><a name="product"></a>Product</h3>
 Product tests target a built distribution or do compiler (argument) 
 testing not supported by the harness.
 Many have been superceded by ant tests.
+To build aspectj with itself, see
+<a href="product/build-aspectj/build.xml">
+         product/build-aspectj/build.xml</a>.
 
-<h3><a name="#ajctest"></a>AjcTest</h3>
+<h3><a name="ajctest"></a>AjcTest</h3>
    <a href="ajctest.xml">ajctest.xml</a>
    is an Ant script that compiles and runs large systems.
    The scripts tell the AjcTest task from the testing module to drive
@@ -150,14 +173,14 @@ Many have been superceded by ant tests.
    <!-- XXX install and correct -->
    
    
-<h3><a name="#jacks"></a>Jacks</h3>
+<h3><a name="jacks"></a>Jacks</h3>
 Jacks is the Jikes compiler test suite available at the 
     <a href="http://www-124.ibm.com/developerworks/oss/cvs/jikes/~checkout~/jacks/jacks.html">
        Jacks project page</a>.
 
 We have a bash script to run it using ajc and javac and compare
        the results.
-<h3><a name="#junit"></a>JUnit</h3>
+<h3><a name="junit"></a>JUnit</h3>
 The JUnit tests should be self-documenting.
 For more information on running them, see
 <a href="../build/readme-build-and-test-aspectj.html">