More AsciiDoc formatting improvements (WIP)

Signed-off-by: Alexander Kriegisch <Alexander@Kriegisch.name>

4 files changed, 117 insertions, 50 deletions

diff --git a/docs/pdGuideDB/messages.adoc b/docs/pdGuideDB/messages.adoc
index 277a4f472..efff9be24 100644
--- a/docs/pdGuideDB/messages.adoc
+++ b/docs/pdGuideDB/messages.adoc
@@ -1,3 +1,4 @@
+[[messages]]
 == Messages
 
 [[messages-introduction]]
@@ -18,9 +19,9 @@ summarizes some of the more relevant messages.
 The compiler offers `-verbose`, `-warning`, and `-XLint` options when
 invoked using the command-line, Ant, or embedded in an IDE. All options
 are listed in the AspectJ Development Environment Guide sections for
-xref:../devguide/ajc-ref.html[Ajc] and
-xref:../devguide/antTasks-iajc.html[Ant Tasks]. The
-xref:../devguide/ltw.html[Load-time Weaving] section describes how to
+xref:../devGuideDB/ajc.adoc#ajc[Ajc] and
+xref:../devGuideDB/antsupport.adoc#antTasks[Ant Tasks]. The
+xref:../devGuideDB/ltw.adoc#ltw[Load-time Weaving] section describes how to
 use XML configuration files and system properties to pass options to the
 weaver. (You can also pass options to the weaver using system properties
 in build- time weaving.) The `-verbose` option has the effect of
@@ -37,9 +38,9 @@ compiler and weaver messages.
 The tables below list some options, System Properties (for LTW only) and
 Java 5 annotations used to control AspectJ messages. The method of
 configuration depends on your environment so please refer to the
-relevant documentation for xref:../devguide/ajc-ref.html[ajc],
-xref:../devguide/antTasks.html[Ant] or
-xref:../devguide/ltw-configuration.html#weaver-options[LTW].
+relevant documentation for xref:../devGuideDB/ajc.adoc[ajc],
+xref:../devGuideDB/antsupport.adoc#antTasks[Ant] or
+xref:../devGuideDB/ltw.adoc#weaver-options[LTW].
 
 [cols=",",options="header",]
 |===
@@ -58,9 +59,9 @@ output .class files.)
 
 |`messageHolderClass`/ `-XmessageHolderClass:` |In Ant tasks and LTW
 respectively specify the class to receive all messages. See
-xref:../devguide/antTasks-iajc.html#antTasks-iajc-options[iajc task
+xref:../devGuideDB/antsupport.adoc#antTasks-iajc-options[iajc task
 options] or
-xref:../devguide/ltw-configuration.html#weaver-options[Weaver Options].
+xref:../devGuideDB/ltw.adoc#weaver-options[Weaver Options].
 |===
 
 [cols=",",options="header",]
diff --git a/docs/pdGuideDB/pdguide.adoc b/docs/pdGuideDB/pdguide.adoc
new file mode 100644
index 000000000..dcbcfc331
--- /dev/null
+++ b/docs/pdGuideDB/pdguide.adoc
@@ -0,0 +1,50 @@
+= The AspectJ^TM^ Problem Diagnosis Guide
+
+:doctype: book
+
+_by the AspectJ Team_
+
+_Copyright (c) 2006 IBM Corporation and others. 2006 Contributors. All rights reserved._
+
+This guide describes how to configure the AspectJ compiler/weaver to provide
+information for diagnosing problems in the input programs, the
+compiler/weaver or its configuration.
+
+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, as well as many
+configurable "lint" messages, all of which can be emitted normally,
+logged using standard facilities, or intercepted programmatically.
+These are discussed in xref:messages.adoc#messages[Messages]. Since most errors
+relate to writing pointcuts incorrectly, there is a section on
+xref:pointcuts.adoc#pointcuts[Debugging Pointcuts].
+
+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:
+
+* xref:trace.adoc#trace[Tracing] can be enabled to track progress up to the time of a failure;
+* xref:ajcore.adoc#ajcore[AspectJ Core Files] can give a relatively complete picture of the state of
+  the world at the time of a failure; and
+* xref:ltwdump.adoc#ltwdump[Dumping classes during load-time weaving] is a way to capture both input and output classes during load-time weaving.
+
+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.
+
+////
+ATTENTION: Please do not remove blank lines in between 'include::' statements. Otherwise, section numbers in the
+table of contents (TOC) can be wrong and the first section of each document missing completely.
+////
+include::messages.adoc[Messages]
+
+include::pointcuts.adoc[Debugging Pointcuts]
+
+include::trace.adoc[Tracing]
+
+include::ajcore.adoc[AspectJ Core Files]
+
+include::ltwdump.adoc[Dumping classes during load-time weaving]
diff --git a/docs/pdGuideDB/pdguide.xml b/docs/pdGuideDB/pdguide.xml
index 08af6fe28..619f54052 100644
--- a/docs/pdGuideDB/pdguide.xml
+++ b/docs/pdGuideDB/pdguide.xml
@@ -22,7 +22,7 @@
 
       <legalnotice>
         <para>Copyright (c) 2006 IBM Corporation and others.
-         2006 Contributors.  
+         2006 Contributors.
          All rights reserved.
         </para>
       </legalnotice>
@@ -30,28 +30,28 @@
     <abstract>
       <para>
           This guide describes how to configure the AspectJ compiler/weaver to provide
-          information for diagnosing problems in the input programs, the 
+          information for diagnosing problems in the input programs, the
           compiler/weaver or its configuration.
       </para>
       <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, as well as many 
-          configurable "lint" messages, all of which can be emitted normally, 
-          logged using standard facilities, or intercepted programmatically. 
+          there are a number of default warning and error messages, as well as 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 
+          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: 
+          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 
+            <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 
+            <listitem><para><xref linkend="ltwdump"/> is a way to capture both
                 input and output classes during load-time weaving.
           </para></listitem>
         </orderedlist>
@@ -59,14 +59,14 @@
       <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>            
+          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;
@@ -74,4 +74,3 @@
   &ltwdump;
 
 </book>
-
diff --git a/docs/pdGuideDB/pointcuts.adoc b/docs/pdGuideDB/pointcuts.adoc
index 66e133e65..7f17ae94b 100644
--- a/docs/pdGuideDB/pointcuts.adoc
+++ b/docs/pdGuideDB/pointcuts.adoc
@@ -16,17 +16,23 @@ compile-time, can save a lot of time.
 [[pointcuts-debugging]]
 === Debugging pointcuts
 
-Go at it top-down and then bottom-up. Top-down, draft significant
+Go at it top-down and then bottom-up.
+
+==== Top-down
+
+Top-down, draft significant
 aspects by first writing the comments to specify responsibilities.
-Advice responsibility usually takes the form, "When X, do Y." Pointcut
-responsibility for "When X" often takes the form, "When [join points]
-[in locations] [are ...]". These []'s often translate to named pointcuts
-(like `libraryCalls() && within(Client) && args(Context)`) which form a
-semantic bridge to the plain-text meaning in a comment (e.g., `// when
-the client passes only context into the library`). This gets you to a
+Advice responsibility usually takes the form, _"When X, do Y"_. Pointcut
+responsibility for _"When X"_ often takes the form, _"When [join points]
+[in locations] [are ...]"_. These __[]__'s often translate to named pointcuts
+like `libraryCalls() && within(Client) && args(Context)`, which form a
+semantic bridge to the plain-text meaning in a comment, e.g. `// when
+the client passes only context into the library`. This gets you to a
 point where you can debug the parts of the pointcut independently.
 
-Bottom up (to build each part), consider each primitive pointcut
+==== Bottom-up
+
+Bottom-up (to build each part), consider each primitive pointcut
 designator (PCD), then the composition, and then any implicit
 constraints:
 
@@ -43,7 +49,7 @@ each join point? This translates to `this()`, `target()`, `args()`,
 . Are there any advice or implementation limitations at issue? This
 involves knowing the few constraints on AspectJ imposed by Java bytecode
 as listed in the AspectJ Programming Guide section on
-xref:../progguide/implementation.html[Implementation Notes].
+xref:../progGuideDB/implementation.adoc#implementation[Implementation Notes].
 
 It's much faster to iterate a pointcut at compile-time using declare
 warning (even better, some errors are identified at parse-time in the
@@ -53,42 +59,52 @@ listed above). If compiles themselves take too long because of all the
 AspectJ weaving, then try to only include the debugging aspect with the
 prototype pointcut, and limit the scope using `within(..)`.
 
-Some mistakes in primitive pointcuts:
+=== Common pointcut mistakes
+
+There are some typical types of mistakes developers make when designing pointcuts.
+Here are a few examples:
+
+==== Mistakes in primitive pointcuts
 
 * `this(Foo) && execution(static * *(..))`: There is no `this` in a
 static context, so `this()` or `target()` should not be used in a static
 context or when targetting a static context (respectively). This happens
-most often when you want to say things like "all calls to Foo from Bar"
-and you only pick out calls to instance methods of Foo or you try to
-pick out calls from static methods of Bar.
+most often when you want to say things like "all calls to `Foo` from ``Bar``"
+and you only pick out calls to instance methods of `Foo` or you try to
+pick out calls from static methods of `Bar`.
+
 * `target(Foo) && call(new(..)`: This will never match. In
 constructor-call join points, there is no target because the object has
 not been created yet.
+
 * `call(* Foo.*(..))`: `Foo` refers to the compile-time type of the
 invoking reference, not the implementing class. In Java before 1.4, the
 compile-time type was rendered as the defining type, not the reference
 type; this was corrected in 1.4 (as shown when using ajc with the -1.4
 flag) Most people should use `target(Foo) && call(...)`.
-* `execution(* Foo.bar(..))`: An execution join point for Foo is always
-within Foo, so this won't pick out any overrides of bar(..). Use
+
+* `execution(* Foo.bar(..))`: An execution join point for `Foo` is always
+within `Foo`, so this won't pick out any overrides of `bar(..)`. Use
 `target(Foo) && execution(* bar(..))` for instance methods.
+
 * `within(Foo)`: anonymous types are not known at weave-time to be
 within the lexically-enclosing type (a limitation of Java bytecode).
 
-Some mistakes in composition:
+==== Mistakes in composition
 
 * `call(* foo(Bar, Foo)) && args(Foo)`: This will never match. The
 parameters in `args(..)` are position-dependent, so `args(Foo)` only
 picks out join points where there is only one argument possible, of type
-Foo. Use the indeterminate-arguments operator '..' as needed, e.g.,
+Foo. Use the indeterminate-arguments operator `..` as needed, e.g.,
 `args(Foo, ..)`.
+
 * `call(* foo()) && execution(* foo())`: This will never match. Each
 pointcut must be true at each join point matched. For a union of
-different kinds of join points (here, call or execution), use '||'.
-E.g., to match both method-call and field-get join points, use `call(*
-...) || get(...)`.
+different kinds of join points (here, call or execution), use `||`.
+E.g., to match both method-call and field-get join points, use
+`call(* ...) || get(...)`.
 
-Some mistakes in implicit advice constraints:
+==== Mistakes in implicit advice constraints
 
 * `after () returning (Foo foo) : ...`: after advice can bind the
 returned object or exception thrown. That effectively acts like
@@ -96,18 +112,19 @@ returned object or exception thrown. That effectively acts like
 based on the runtime type of the bound object, even though it is not
 explicitly part of the pointcut.
 
-Some mistakes in implementation requirements:
+==== Mistakes in implementation requirements
 
-* `ajc` has to control the code for a join point in order to implement
-the join point. This translates to an implicit `within(\{code under the
+* _ajc_ has to control the code for a join point in order to implement
+the join point. This translates to an implicit `within({code under the
 control of the compiler})` for all join points, with additional caveat
 for some join points. Take exception handlers, for example: there is no
 way to be sure from the bytecode where the original handler ends, so
-`ajc` can't implement after advice on handler join points. (Since these
+_ajc_ can't implement after advice on handler join points. (Since these
 are on a per-join-point basis, they should be considered for each
 corresponding primitive pointcut designator.) Unlike the mistakes with
 the primitive PCDs above, the compiler will emit an error for these
 caveats.
+
 * `call(@SuperAnnotation Subclass.meth()`: Annotations are not inherited
 by default, so e.g., if the pointcut specifies an annotation, then
 subclass implementations of that method will not be matched.