to pdguide added XLint list, more control options, debugging pointcuts, and more hand-holding.

1 files changed, 37 insertions, 6 deletions

diff --git a/docs/pdGuideDB/pdguide.xml b/docs/pdGuideDB/pdguide.xml
index dab3070bf..5581d5395 100644
--- a/docs/pdGuideDB/pdguide.xml
+++ b/docs/pdGuideDB/pdguide.xml
@@ -4,6 +4,7 @@
                       "../../lib/docbook/docbook-dtd/docbookx.dtd"
 [
 <!ENTITY messages               SYSTEM "messages.xml">
+<!ENTITY pointcuts              SYSTEM "pointcuts.xml">
 <!ENTITY trace                  SYSTEM "trace.xml">
 <!ENTITY ajcore                 SYSTEM "ajcore.xml">
 <!ENTITY ltwdump                SYSTEM "ltwdump.xml">
@@ -28,16 +29,46 @@
 
     <abstract>
       <para>
-        This guide describes how to gather and interpret information from the AspectJ compiler
-        to diagnosing problems in AspectJ programs, configuring the load-time weaving
-        framework or reporting bugs on Bugzilla. Some information e.g. messages is intended to
-        help you solve coding or configuration problems. Other information is intended to be
-        be used by the AspectJ team when trying to fix bugs.
+          This describes how to configure the AspectJ compiler/weaver to provide
+          information for diagnosing problems in the input programs or in the 
+          compiler/weaver itself.
       </para>
-    </abstract>
+      <para>
+          The AspectJ compiler and weaver can provide lots of information for diagnosing
+          problems in building AspectJ programs.  For problems in the input program,
+          there are a number of default warning and error messages and many 
+          configurable "lint" messages, all of which can be emitted normally, 
+          logged using standard facilities, or intercepted programmatically. 
+          These are discussed in <xref linkend="messages"/>.  Since most errors
+          relate to writing pointcuts incorrectly, there is a section on 
+          <xref linkend="pointcuts"/>.
+      </para>
+      <para>
+          For problems with the compiler/weaver itself, there are three facilities
+          that enable the AspectJ developers to resolve bugs even when it is
+          too hard to deliver a reproducible test case: 
+        <orderedlist>
+            <listitem><para><xref linkend="trace"/> can be enabled to track progress up to the time of a failure;</para></listitem>
+            <listitem><para><xref linkend="ajcore"/> can give a relatively complete picture of the state of 
+          the world at the time of a failure; and </para></listitem>
+            <listitem><para><xref linkend="ltwdump"/> is a way to capture both 
+                input and output classes during load-time weaving.
+          </para></listitem>
+        </orderedlist>
+          </para>
+      <para>
+          This guide describes how to configure messages to get the right information
+          and how to configure traces, dumps, and core files.  Although the compiler/weaver
+          operates in roughly three modes (from the command-line, embedded in an IDE, 
+          and enabled as load-time weaving), the principles are basically the same for 
+          all modes.  The differences lie in how to set up diagnostics and what 
+          information is likely to be relevant.   
+      </para>        
+    </abstract>            
   </bookinfo>
   
   &messages;
+  &pointcuts;
   &ajcore;
   &trace;
   &ltwdump;