aspectj 5 docs update. Signature matching chapter added.

Annotations chapter complete. Varargs, covariance, autoboxing,
and enum chapters complete. Pertypewithin proposal written up.
Generics, new reflection interfaces, and the "miscellaneous" section
still outstanding.

13 files changed, 781 insertions, 191 deletions

diff --git a/docs/adk15ProgGuideDB/adk15notebook.xml b/docs/adk15ProgGuideDB/adk15notebook.xml
index c3ed62924..d3f71630c 100644
--- a/docs/adk15ProgGuideDB/adk15notebook.xml
+++ b/docs/adk15ProgGuideDB/adk15notebook.xml
@@ -10,16 +10,14 @@
 <!ENTITY autoboxing         SYSTEM "autoboxing.xml">
 <!ENTITY covariance         SYSTEM "covariance.xml">
 <!ENTITY varargs            SYSTEM "varargs.xml">
-<!ENTITY pointcutexp        SYSTEM "pointcutexp.xml">
 <!ENTITY pertypewithin      SYSTEM "pertypewithin.xml">
-<!ENTITY getthistargetobj   SYSTEM "getthistargetobj.xml">
-<!ENTITY declaresoft        SYSTEM "declaresoft.xml">
+<!ENTITY miscellaneous      SYSTEM "miscellaneous.xml">
 <!ENTITY reflection         SYSTEM "reflection.xml">
 <!ENTITY grammar            SYSTEM "grammar.xml">]>
 
 <book>
   <bookinfo>
-    <title>The AspectJ<superscript>TM</superscript> Development Kit v1.5 Developer's Notebook</title>
+    <title>The AspectJ<superscript>TM</superscript> 5 Development Kit Developer's Notebook</title>
 
     <authorgroup>
       <author>
@@ -37,8 +35,8 @@
     <abstract>
       <para>
         This guide describes the changes to the AspectJ language
-        in version 1.5. These changes are primarily, but not exclusively,
-        to support Java 5.0 (Tiger) features.
+        and tools in AspectJ 5. These changes are primarily, but not exclusively,
+        to support Java 5 (Tiger) features.
         If you are new to AspectJ, we recommend you start 
         by reading the programming guide.
       </para>
@@ -59,15 +57,13 @@
   &jpsigs;
   &annotations;
   &generics;
-  &enumeratedtypes;
   &autoboxing;
   &covariance;
   &varargs;
-  &pointcutexp;
+  &enumeratedtypes;
   &pertypewithin;
-  &getthistargetobj;
-  &declaresoft;
   &reflection;
+  &miscellaneous;
   &grammar;
 
 </book>
diff --git a/docs/adk15ProgGuideDB/annotations.xml b/docs/adk15ProgGuideDB/annotations.xml
index 30e495c48..f4fa9d95e 100644
--- a/docs/adk15ProgGuideDB/annotations.xml
+++ b/docs/adk15ProgGuideDB/annotations.xml
@@ -7,7 +7,7 @@
 
 	<para>
 		This section provides the essential information about annotations in
-		Java 5 needed to understand how annotations are treated in AspectJ 1.5.
+		Java 5 needed to understand how annotations are treated in AspectJ 5.
 		For a full introduction to annotations in Java, please see the
 		documentation for the Java 5 SDK.
 	</para>
@@ -35,7 +35,8 @@
 	
 		<para>
 			Annotations may be <emphasis>marker annotations</emphasis>,
-			<emphasis>single-valued</emphasis>, or <emphasis>multi-valued</emphasis>.
+			<emphasis>single-valued annotations</emphasis>, or 
+			<emphasis>multi-valued annotations</emphasis>.
 			Annotation types with no members or that provide default values
 			for all members may be used simply as marker annotations, as in
 			the deprecation example above. Single-value annotation types have
@@ -123,7 +124,7 @@
     	
     	<para>
     		Java 5 supports a new interface, 
-    		<literal>java.lang.reflect.AnnotatedElement</literal> that is
+    		<literal>java.lang.reflect.AnnotatedElement</literal>, that is
     		implemented by the reflection classes in Java (<literal>Class</literal>, 
     		<literal>Constructor</literal>,
     		<literal>Field</literal>, <literal>Method</literal>, and 
@@ -180,8 +181,8 @@
     	</para>
     	
     	<para>
-    		<literal>@Inherited</literal> annotations are not inherited by
-    		members (the inheritance only applies to type annotations). A type
+    		<literal>@Inherited</literal> annotations are not inherited when used to
+    		annotate anything other than a type. A type
     		that implements one or more interfaces never inherits any annotations from
     		the interfaces it implements.
     	</para>
@@ -195,7 +196,7 @@
     <title>Annotating Aspects</title>
     
     <para>
-    	AspectJ 1.5 supports annotations on aspects, and on method, field,
+    	AspectJ 5 supports annotations on aspects, and on method, field,
     	constructor, advice, and inter-type declarations within aspects. 
     	Method and advice parameters may also be annotated.
     	Annotations are not permitted on pointcut declarations or on 
@@ -249,7 +250,7 @@
     </para>
 
     <para>
-        AspectJ 1.5 supports a new XLint warning, "the pointcut associated with this
+        AspectJ 5 supports a new XLint warning, "the pointcut associated with this
         advice does not match any join points". The warning is enabled by default and
         will be emitted by the compiler if the pointcut expression associated with an 
         advice statement can be statically determined to not match any join points. The
@@ -270,7 +271,7 @@
   
   <para>
   	This section discusses changes to type pattern and signature pattern matching in
-  	AspectJ 1.5 that support matching join points based on the presence or absence of
+  	AspectJ 5 that support matching join points based on the presence or absence of
   	annotations. We then discuss means of exposing annotation values within the body
   	of advice.
   </para>
@@ -476,7 +477,7 @@
         </varlistentry>
 
         <varlistentry>
-          <term>@Foo (@Goo *) (@Hoo *..*).*</term>
+          <term>@Foo (@Goo *) (@Hoo *).*</term>
           <listitem>
             <para>
             	Matches a field with an annotation <literal>@Foo</literal>, of a type with an 
@@ -578,7 +579,7 @@
             <para>
             	Matches any join point occuring in a type with an <literal>@Secure</literal>
             	annotation. The format of the <literal>within</literal> pointcut designator
-            	in AspectJ 1.5 is <literal>'within' '(' OptionalParensTypePattern ')'</literal>.
+            	in AspectJ 5 is <literal>'within' '(' OptionalParensTypePattern ')'</literal>.
             </para>
           </listitem>
         </varlistentry>
@@ -590,7 +591,7 @@
             	Matches the staticinitialization join point of any type with the
             	<literal>@Persistent</literal> annotation. The format of the 
             	<literal>staticinitialization</literal> pointcut designator
-            	in AspectJ 1.5 is <literal>'staticinitialization' '(' OptionalParensTypePattern ')'</literal>.
+            	in AspectJ 5 is <literal>'staticinitialization' '(' OptionalParensTypePattern ')'</literal>.
             </para>
           </listitem>
         </varlistentry>
@@ -630,7 +631,7 @@
             <para>
                 Matches the handler join point for the handling of any exception that is
                 not <literal>Catastrophic</literal>. The format of the <literal>handler</literal>
-                pointcut designator in AspectJ 1.5 is <literal>'handler' '(' OptionalParensTypePattern ')'</literal>.
+                pointcut designator in AspectJ 5 is <literal>'handler' '(' OptionalParensTypePattern ')'</literal>.
             </para>
           </listitem>
         </varlistentry>
@@ -642,7 +643,7 @@
    <sect2>
   	<title>Runtime type matching and context exposure</title>
 
-    <para>AspectJ 1.5 supports a set of "@" pointcut designators which
+    <para>AspectJ 5 supports a set of "@" pointcut designators which
     can be used both to match based on the presence of an annotation at
     runtime, and to expose the annotation value as context in a pointcut or
     advice definition. These designators are <literal>@args, @this, @target,
@@ -657,7 +658,7 @@
         The <literal>this()</literal>, <literal>target()</literal>, and
         <literal>args()</literal> pointcut designators allow matching based
         on the runtime type of an object, as opposed to the statically 
-        declared type. In AspectJ 1.5, these designators are supplemented
+        declared type. In AspectJ 5, these designators are supplemented
         with three new designators : <literal>@this()</literal> (read, "this
         annotation"), <literal>@target()</literal>, and <literal>@args()</literal>.    
     </para>
@@ -728,6 +729,10 @@
   	<programlisting><![CDATA[
   	pointcut callToClassifiedObject(Classified classificationInfo) :
   	    call(* *(..)) && @target(classificationInfo);
+
+  	pointcut txRequiredMethod(Tx transactionAnnotation) :
+  	    execution(* *(..)) && @this(transactionAnnotation) 
+  	    && if(transactionAnnotation.policy == Tx.Policy.REQUIRED);
 	]]></programlisting>
 
     <para>
@@ -842,9 +847,10 @@
   		
   		InitializationAnnotation := '@initialization' '(' AnnotationNameOrVar ')'
 
-        PreInitializationAnnotation := '@preinitialization' '(' AnnotationNameOrVar ')'
+  		PreInitializationAnnotation := '@preinitialization' '(' AnnotationNameOrVar ')'
+        
+  		StaticInitializationAnnotation := '@staticinitialization' '(' AnnotationNameOrVar ')'
         
-        StaticInitializationAnnotation := '@staticinitialization' '(' AnnotationNameOrVar ')'
     ]]></programlisting>  		
 
    <variablelist>
@@ -904,7 +910,7 @@
           <listitem>
             <para>
             	Matches any initialization join point where the initiating
-            	constructor an annotation of type <literal>@Foo</literal>.
+            	constructor has an annotation of type <literal>@Foo</literal>.
             </para>
           </listitem>
         </varlistentry>
@@ -914,7 +920,7 @@
           <listitem>
             <para>
             	Matches any preinitialization join point where the initiating
-            	constructor an annotation of type <literal>@Foo</literal>.
+            	constructor has an annotation of type <literal>@Foo</literal>.
             </para>
           </listitem>
         </varlistentry>
@@ -932,7 +938,7 @@
     </variablelist>
 
     <para>
-      Access to annotation information on members at a matched join point is available
+      Access to annotation information on members at a matched join point is also available
       through the <literal>getSignature</literal> method of the <literal>JoinPoint</literal>
       and <literal>JoinPoint.StaticPart</literal> interfaces. The <literal>MemberSignature</literal>
       interface is extended with the additional operation 
@@ -967,16 +973,16 @@
           specified directly in method and constructor signature patterns. Because
           this made some pointcut expressions hard to read and understand, we moved
           in favour of the design presented below, which also has its drawbacks. 
-          Matching on package and parameter annotations is one feature likely to be
+          Matching on package and parameter annotations will be
           deferred until after the 1.5.0 release so that we can gain more understanding
           of the kinds of uses AspectJ users are making of annotations in pointcut
           expressions before commiting to any one approach.</emphasis>
       </para>
-      
+
+<!--
       <para>
           Java 5 allows both packages and parameters to be annotated. To allow matching on package and parameter annotations,
-          AspectJ 1.5 introduces the <literal>@package</literal> and <literal>@parameters</literal> pointcut designators. 
-          <emphasis>Note: we could consider deferring implementation of these to a dot release after 1.5.0?</emphasis>
+          AspectJ 5 introduces the <literal>@package</literal> and <literal>@parameters</literal> pointcut designators.           
       </para>
       
   	<programlisting><![CDATA[  	
@@ -1079,10 +1085,10 @@
     This last example will result in a compilation error since <literal>int</literal> is not a 
     valid annotation pattern.
     </para>
-    
-  </sect2>
-
 
+ -->      
+     
+  </sect2>
 
   <sect2>
   	<title>Annotation Inheritance and pointcut matching</title>
@@ -1139,13 +1145,17 @@
   
   <sect2>
     <title>Limitations</title>
-    <para>AspectJ 1.5 allows you to annotate advice, but there is no way to qualify advice execution join point matching based
-    on the presence of annotations.</para>
+    <para>AspectJ 5 allows you to annotate advice, but there is no way to qualify advice execution 
+    join point matching based on the presence of annotations.</para>
     
     <para>
-        It would be useful to be able to match join points based on annotation values, rather than merely the presence of
-        an annotation of a given type. This facility may be supported in a future version of AspectJ, by expanding the
-        definition of <literal>AnnotationPattern</literal>.
+        It would be useful to be able to match join points based on  
+        annotation values, rather than merely the presence of a
+        class-file retention annotation of a given type. This facility may be supported in a future version of AspectJ, by expanding the
+        definition of <literal>AnnotationPattern</literal>. Matching annotation values for
+        annotations with runtime retention can be done by exposing the annotation value
+        as a pointcut parameter and then using an <literal>if</literal> pointcut expression
+        to test the value. 
     </para>
   </sect2>
   
@@ -1160,7 +1170,7 @@
   	<title>Declare error and declare warning</title>
   	
   	<para>
-  	    Since pointcut expressions in AspectJ 1.5 support join point matching based
+  	    Since pointcut expressions in AspectJ 5 support join point matching based
   	    on annotations, this facility can be exploited when writing
   	    <literal>declare warning</literal> and <literal>declare error</literal>
   	    statements. For example:
@@ -1194,7 +1204,7 @@
 	]]></programlisting>
 	
 	<para>
-		Since AspectJ 1.5 supports annotations as part of a type pattern
+		Since AspectJ 5 supports annotations as part of a type pattern
 		specification, it is now possible to match types based on the presence
 		of annotations <emphasis>with either class-file or runtime retention</emphasis>.
 		For example:
@@ -1226,6 +1236,12 @@
 	        
 	    </variablelist>
 
+    <para>An annotation type may not be used as the target of a declare parents
+    statement. If an annotation type is named explicitly as the target of a
+    declare parents statement, a compilation error will result. If an annotation
+    type is matched by a non-explicit type pattern used in a declare parents
+    statement it will be ignored (and an XLint warning issued).</para>
+
   	</sect2>
 
 	<sect2>
@@ -1240,7 +1256,7 @@
 	]]></programlisting>
 
 	<para>
-		AspectJ 1.5 allows the type patterns in the list to include annotation information
+		AspectJ 5 allows the type patterns in the list to include annotation information
 		as part of the pattern specification. For example:
 	</para>	
 
@@ -1262,13 +1278,13 @@
   </sect2>	    
 
   </sect1>
-    
+        
   <!-- ============================== -->
   
   <sect1 id="annotations-declare">
     <title>Declare Annotation</title>
   
-      <para>AspectJ 1.5 supports a new kind of declare statement, <literal>declare annotation</literal>.
+      <para>AspectJ 5 supports a new kind of declare statement, <literal>declare annotation</literal>.
       The general form of a <literal>declare annotation</literal> statement is:
       </para>
 
@@ -1327,5 +1343,11 @@
 
   </sect1>
   
+    <sect1>
+      <title>Inter-type Declarations</title>
+      
+      <para>An annotation type may not be the target of an inter-type declaration.</para>
+    </sect1>  
+  
 </chapter>
 
diff --git a/docs/adk15ProgGuideDB/autoboxing.xml b/docs/adk15ProgGuideDB/autoboxing.xml
index ded805fb0..98c7e7faa 100644
--- a/docs/adk15ProgGuideDB/autoboxing.xml
+++ b/docs/adk15ProgGuideDB/autoboxing.xml
@@ -6,22 +6,95 @@
         <title>Autoboxing and Unboxing in Java 5</title>
         
         <para>
-          Java 5 (and hence AspectJ 1.5) ... . For example:
+          Java 5 (and hence AspectJ 1.5) supports automatic conversion of 
+          primitive types (int, float, double etc.) to their object equivalents
+          (Integer, Float, Double,...) in assignments and method and constructor
+          invocations. This conversion is know as autoboxing.
         </para>
+        
+        <para>Java 5 also supports automatic unboxing, where wrapper types
+        are automatically converted into their primitive equivalents if
+        needed for assignments or method or constructor invocations.</para>
+        
+        <para>For example:</para>
 
 		<programlisting><![CDATA[
+		int i = 0;
+		i = new Integer(5); // auto-unboxing
+		
+		Integer i2 = 5;  // autoboxing
 		]]></programlisting>
         
       </sect1>
       
       <sect1>
-          <title>Autoboxing and Join Point matching in AspectJ 1.5</title>
+          <title>Autoboxing and Join Point matching in AspectJ 5</title>
+          
+          <para>Most of the pointcut designators match based on signatures, and
+          hence are unaffected by autoboxing. For example, a call to a method</para>
+
+   		<programlisting><![CDATA[
+   		public void foo(Integer i);
+   		]]></programlisting>
+    
+         <para>is <emphasis>not</emphasis> matched by a pointcut
+         <literal>call(void foo(int))</literal> since the signature declares
+         a single <literal>Integer</literal> parameter, not an <literal>int</literal>.
+         </para>
+         
+         <para>The <literal>args</literal> pointcut designator is affected by
+         autoboxing since it matches based on the runtime type of the arguments.
+         AspectJ 5 applies autoboxing and unboxing in determining argument matching.
+         In other words, <literal>args(Integer)</literal> will match any join
+         point at which there is a single argument of type <literal>Integer</literal>
+         or of type <literal>int</literal>.</para>
+         
+         <itemizedlist>
+             <listitem>args(Integer) and args(int) are equivalent</listitem>
+             <listitem>args(Float) and args(float) are equivalent</listitem>
+             <listitem>args(Double) and args(double) are equivalent</listitem>
+             <listitem>args(Short) and args(short) are equivalent</listitem>
+             <listitem>args(Byte) and args(byte) are equivalent</listitem>
+             <listitem>args(Long) and args(long) are equivalent</listitem>
+             <listitem>args(Boolean) and args(boolean) are equivalent</listitem>
+         </itemizedlist>
+      
+      <para>
+        Autoboxing and unboxing are also applied when binding pointcut or 
+        advice parameters, for example:   
+      </para>
+
+   		<programlisting><![CDATA[
+   		pointcut foo(int i) : args(i);
+   		
+   		before(Integer i) : foo(i) {
+   		  ...
+   		}
+   		]]></programlisting>
+
       </sect1>
       
       <sect1>
           <title>Inter-type method declarations and method dispatch</title>
+          
+          <para>Autoboxing, unboxing, and also varargs all affect the method
+          dispatch algorithm used in Java 5. In AspectJ 5, the target method
+          of a call is selected according to the following algorithm:</para>
+          
+          <orderedlist>
+              <listitem>Attempt to locate a matching method or inter-type declared
+              method without considering
+              autoboxing, unboxing, or vararg invocations.</listitem>
+              <listitem>If no match is found, try again considering autoboxing
+              and unboxing.</listitem>
+              <listitem>Finally try again considering both autoboxing, unboxing,
+              and varargs.</listitem>
+          </orderedlist>
+          
+          <para>One consequence is that a directly matching inter-type declared
+          method will take precedence over a method declared locally in the 
+          target class but that only matches via autoboxing.</para>
       </sect1>
-      
-  
+        
 </chapter>
 
diff --git a/docs/adk15ProgGuideDB/covariance.xml b/docs/adk15ProgGuideDB/covariance.xml
index 4e1e2f8de..b6b0d7e70 100644
--- a/docs/adk15ProgGuideDB/covariance.xml
+++ b/docs/adk15ProgGuideDB/covariance.xml
@@ -6,7 +6,7 @@
         <title>Covariance in Java 5</title>
         
         <para>
-          Java 5 (and hence AspectJ 1.5) allows you to narrow the return type
+          Java 5 (and hence AspectJ 5) allows you to narrow the return type
           in an overriding method. For example:
         </para>
 
@@ -42,16 +42,30 @@
 		b.whoAreYou();
 		]]></programlisting>
 		
-		<para>Then the call and execution join points for <literal>whoAreYou</literal>
-		are matched as follows:</para>
+		<para>The signatures for the call join point <literal>a.whoAreYou()</literal> are
+		simply:</para>
+
+		<programlisting><![CDATA[
+		A A.whoAreYou()
+		]]></programlisting>
+		
+		<para>The signatures for the call join point <literal>b.whoAreYou()</literal> are:
+		</para>
+
+		<programlisting><![CDATA[
+		A A.whoAreYou()
+		B B.whoAreYou()
+		]]></programlisting>
+		
+		<para>Following the join point matching rules given in <xref linkend="jpsigs"/>,</para>
 		
 		<variablelist>
 
         <varlistentry>
           <term>call(* whoAreYou())</term>
           <listitem>
-            <para>Matches both calls, (since it places no constraint on the
-                return type of the join point signature).
+            <para>Matches both calls, (since each call join point has at least
+            one matching signature).
             </para>
           </listitem>
         </varlistentry>
@@ -59,8 +73,8 @@
         <varlistentry>
           <term>call(* A.whoAreYou())</term>
           <listitem>
-            <para>Matches both calls, (since the original declaring type
-            of <literal>whoAreYou</literal> is <literal>A</literal>).
+            <para>Matches both calls, (since each call join point has at least
+            one matching signature).
             </para>
           </listitem>
         </varlistentry>
@@ -68,9 +82,8 @@
         <varlistentry>
           <term>call(A whoAreYou())</term>
           <listitem>
-            <para>Matches both calls, (since the signature of 
-            <literal>whoAreYou</literal>) in the original declaring type
-            has a return type of <literal>A</literal>).
+            <para>Matches both calls, (since each call join point has at least
+            one matching signature).
             </para>
           </listitem>
         </varlistentry>
@@ -78,9 +91,8 @@
         <varlistentry>
           <term>call(A B.whoAreYou())</term>
           <listitem>
-            <para>Does not match anything - the signature of <literal>whoAreYou</literal>
-            as overriden in <literal>B</literal> has a return type of
-            <literal>B</literal>, not <literal>A</literal>.  A lint warning is
+            <para>Does not match anything - neither of the call join points
+            has a signature matched by this pattern.  A lint warning is
             given for the call <literal>a.whoAreYou()</literal> ("does not match
             because declaring type is A, if match required use target(B)").
             </para>
@@ -91,9 +103,8 @@
           <term>call(A+ B.whoAreYou())</term>
           <listitem>
             <para>Matches the call to <literal>b.whoAreYou()</literal> since
-            the return type <literal>B</literal> in the method signature
-            is matched by the type pattern <literal>A+</literal>. A lint warning is
-            given for the call <literal>a.whoAreYou()</literal> ("does not match
+            the signature pattern matches the signature <literal>B B.whoAreYou()</literal>. 
+            A lint warning is given for the call <literal>a.whoAreYou()</literal> ("does not match
             because declaring type is A, if match required use target(B)").
             </para>
           </listitem>
@@ -102,8 +113,8 @@
         <varlistentry>
           <term>call(B A.whoAreYou())</term>
           <listitem>
-            <para>Does not match anything - there is no method declared in 
-                <literal>A</literal> with a return type of <literal>B</literal>.
+            <para>Does not match anything since neither join point has a 
+            signature matched by this pattern.
             </para>
           </listitem>
         </varlistentry>
@@ -129,52 +140,9 @@
 		<para>The rule for signature matching at call and execution join points
 		is unchanged from AspectJ 1.2: a call or execution pointcut matches if
 		the signature pattern matches at least one of the signatures of the
-		join point, and if the most-specific matched signature is also matched
+		join point, and if the modifiers of the method or constructor are matched
 		by any modifier pattern or annotation pattern that may be present.</para>
 		
-		<para>For a call or execution join point, the signatures of a join point
-		for the call or execution of a method <literal>Rtype T.m(params)</literal>
-		are determined as follows:</para>
-		<itemizedlist>
-		    <listitem>
-		    If <literal>m(params)</literal> is defined in <literal>T</literal>, 
-		    then the signature of <literal>m(params)</literal> in <literal>T</literal> is 
-		    a signature of the join point: <literal>Rtype T.m(params)</literal>. 
-		    If <literal>T</literal> does not
-		    provide its own definition of <literal>m</literal>, then the signature 
-		    <literal>Rtype' T.m(params)</literal>
-		    is a signature of the join point, where <literal>Rtype'</literal> is the return type of
-		    the definition of <literal>m</literal> inherited by <literal>T</literal>.
-            </listitem>
-            <listitem>
-            For each super-type <literal>S</literal> of <literal>T</literal> that is a valid receiver
-            for a call to <literal>m</literal>, then the signature of <literal>m(params)</literal> in 
-            <literal>S</literal> is a signature
-            of the join point: <literal>Rtype S.m(params)</literal>. 
-            If <literal>S</literal> does not provide its
-            own definition of <literal>m</literal>, then the signature 
-            <literal>Rtype' S.m(params)</literal> is a 
-            signature of the join point, where <literal>Rtype'</literal> is the return type of the
-            definition of <literal>m</literal> inherited by <literal>S</literal>.
-            </listitem>
-		</itemizedlist>
-		
-        <para>A call to <literal>b.whoAreYou()</literal> has the join point signatures
-        </para>
-        
-        <itemizedlist>           
-            <listitem>B B.whoAreYou()</listitem>
-            <listitem>A A.whoAreYou()</listitem>
-        </itemizedlist>          
-        
-        <para>Following the rule given, it is easy to see why for example
-        <literal>call(B A.whoAreYou())</literal> does not match anything as 
-        this pattern matches neither of the signatures at the join point. In 
-        contrast, the pointcut expression <literal>call(A+ B.whoAreYou())</literal>
-        does match the call to <literal>b.whoAreYou()</literal> because it matches
-        the second of the signatures at the join point.</para>
-      </sect1>
-      
-  
+		</sect1>
 </chapter>
 
diff --git a/docs/adk15ProgGuideDB/declaresoft.xml b/docs/adk15ProgGuideDB/declaresoft.xml
deleted file mode 100644
index d2bd2869e..000000000
--- a/docs/adk15ProgGuideDB/declaresoft.xml
+++ /dev/null
@@ -1,6 +0,0 @@
-<chapter id="declare soft" xreflabel="Declare Soft">
-
-  <title>Declare Soft</title>
-  
-</chapter>
-
diff --git a/docs/adk15ProgGuideDB/enumeratedtypes.xml b/docs/adk15ProgGuideDB/enumeratedtypes.xml
index ee91689f6..1e56741e0 100644
--- a/docs/adk15ProgGuideDB/enumeratedtypes.xml
+++ b/docs/adk15ProgGuideDB/enumeratedtypes.xml
@@ -2,5 +2,63 @@
 
   <title>Enumerated Types</title>
   
+  <sect1>
+      <title>Enumerated Types in Java 5</title>
+      
+      <para>Java 5 (and hence AspectJ 5) provides explicit support for
+      enumerated types. In the simplest case, you can declare an enumerated
+      type as follows:</para>
+      
+      <programlisting><![CDATA[
+      public enum ProgrammingLanguages {
+       COBOL,C,JAVA,ASPECTJ
+      }
+      ]]></programlisting>
+      
+      <para>Enumerated types are just classes, and they can contain method
+      and field declarations, and may implement interfaces. Enums may only
+      have private constructors, and may not be extended.</para>
+      
+      <para>Enumerated types in Java 5 all implicitly extend the type
+      <literal>java.lang.Enum</literal>. It is illegal to explicitly
+      declare a subtype of this class.</para>
+  </sect1>
+  
+  <sect1>
+      <title>Enumerated Types in AspectJ 5</title>
+      
+      <para>
+      AspectJ 5 supports the declaration of enumerated types just as Java 5
+      does. Because of the special restrictions Java 5 places around enumerated
+      types, AspectJ makes the following additional restrictions:
+      </para>
+      
+      <itemizedlist>
+          <listitem>You can use declare parents to change the super type of
+          an enum.</listitem>
+          <listitem>You cannot use declare parents to declare java.lang.Enum as
+          the parent of any type.</listitem>
+          <listitem>You cannot make inter-type constructor declarations on an
+          enum.</listitem>
+          <listitem>You cannot extend the set of values in an enum via any
+          ITD-like construct.</listitem>
+          <listitem>You cannot make inter-type method or field declarations on 
+          an enum.</listitem>
+          <listitem>You cannot use declare parents to make an enum type implement
+          an interface.</listitem>
+      </itemizedlist>
+      
+      <para>In theory, the last of these two items <emphasis>could</emphasis>
+      be supported. However, AspectJ 5 follows the simple rule that <emphasis>
+      an enum type cannot be the target of an inter-type declaration or declare
+      parents statement</emphasis>. This position may be relaxed in a future
+      version of AspectJ.</para>
+      
+      <para>If an enum is named explicitly as the target of a
+    declare parents statement, a compilation error will result. If an annotation
+    type is matched by a non-explicit type pattern used in a declare parents
+    statement it will be ignored (and an XLint warning issued).</para>
+  </sect1>
+  
 </chapter>
 
diff --git a/docs/adk15ProgGuideDB/getthistargetobj.xml b/docs/adk15ProgGuideDB/getthistargetobj.xml
deleted file mode 100644
index bd5ab9ff1..000000000
--- a/docs/adk15ProgGuideDB/getthistargetobj.xml
+++ /dev/null
@@ -1,6 +0,0 @@
-<chapter id="getthistargetobj" xreflabel="getThisObject() / getTargetObject()">
-
-  <title>getThisObject() / getTargetObject()</title>
-  
-</chapter>
-
diff --git a/docs/adk15ProgGuideDB/grammar.xml b/docs/adk15ProgGuideDB/grammar.xml
index 0a77b9f8f..42a7065d4 100644
--- a/docs/adk15ProgGuideDB/grammar.xml
+++ b/docs/adk15ProgGuideDB/grammar.xml
@@ -1,6 +1,9 @@
-<appendix id="grammar" xreflabel="AspectJ 1.5 Grammar">
+<appendix id="grammar" xreflabel="AspectJ 5 Grammar">
 
-  <title>A Grammar for the AspectJ 1.5 Language</title>
+  <title>A Grammar for the AspectJ 5 Language</title>
   
-</appendix>>
+  Collect together all the grammar fragments scattered throughout this documented
+  and present them as a coherent whole...
+  
+</appendix>
 
diff --git a/docs/adk15ProgGuideDB/joinpointsignatures.xml b/docs/adk15ProgGuideDB/joinpointsignatures.xml
index 0c3473034..fbf59e146 100644
--- a/docs/adk15ProgGuideDB/joinpointsignatures.xml
+++ b/docs/adk15ProgGuideDB/joinpointsignatures.xml
@@ -1,23 +1,212 @@
 <chapter id="jpsigs" xreflabel="Join Point Signatures">
 
   <title>Join Point Signatures</title>
+
+    <para>
+        Many of the extensions to the AspectJ language to address the new features of
+        Java 5 are derived from a simple set of principles for join point
+        matching. In this section, we outline these principles as a foundation
+        for understanding the matching rules in the presence of annotations,
+        generics, covariance, varargs, and autoboxing.
+    </para>
   
-      <para>To understand join point matching for annotations, generics, and
-      covariance, it is first necessary to understand the concepts of
-      join point signatures and join point signature matching, for call and
-      execution join points.</para>
+    <sect1>
+        <title>Join Point Matching</title>
+    
+        <para>AspectJ supports 11 different kinds of join points. These are
+        the <literal>method call, method execution, constructor call,
+        constructor execution, field get, field set, pre-initialization,
+        initialization, static initialization, handler,</literal> and
+        <literal>advice execution</literal> join points.</para>
+        
+        <para>The <emphasis>kinded</emphasis> pointcut designators match
+        based on the kind of a join point. These are the <literal>call,
+        execution, get, set, preinitialization, initialization, 
+        staticinitialization, handler,</literal> and <literal>adviceexecution</literal>
+        designators.</para>
+        
+        <para>A kinded pointcut is written using patterns, some of which 
+        match based on <emphasis>signature</emphasis>, and some of which
+        match based on <emphasis>modifiers</emphasis>. For example, in 
+        the <literal>call</literal> pointcut designator:</para>
+        
+        <programlisting><![CDATA[
+        call(ModifierPattern TypePattern TypePattern.IdPattern(TypePatternList) ThrowsPattern)
+		]]></programlisting>
+		
+		<para>the modifiers matching patterns are <literal>ModifierPattern</literal>
+		and <literal>ThrowsPattern</literal>, and the signature matching patterns
+		are <literal>TypePattern TypePattern.IdPattern(TypePatternList)</literal>.
+		</para>
+		
+		<para>
+		A join point has potentially multiple signatures, but only one set of
+		modifiers. <emphasis>A kinded primitive pointcut matches a particular join point 
+		if and only if</emphasis>:
+		</para>
+		
+		<orderedlist>
+		    <listitem>They are of the same kind</listitem>
+		    <listitem>The signature pattern (exactly) matches at least one 
+		    signature of the join point</listitem>
+		    <listitem>The modifiers pattern matches the modifiers of the
+		    join point</listitem>
+		</orderedlist>
+        
+        <para>These rules make it very easily to quickly determine whether a 
+        given pointcut matches a given join point. In the next two sections,
+        we describe what the signature(s) of a join point are, and what the
+        modifiers of a join point are.</para>
+        
+    </sect1>
   
       <sect1>
-        <title>Join Point Signatures for Call Join Points</title>
+        <title>Join Point Signatures</title>
+        
+        <para>Call and execution join points may potentially have multiple
+        signatures. All other join points have exactly one signature. The
+        following table summarizes the constituent parts of a join point
+        signature for the different kinds of join point.</para>
+        
+        <informaltable>
+        <tgroup cols="7">
+            <thead>
+                <row>
+                    <entry>Join Point Kind</entry>
+                    <entry>Return Type</entry>                
+                    <entry>Declaring Type</entry>                
+                    <entry>Id</entry>                
+                    <entry>Parameter Types</entry>                
+                    <entry>Field Type</entry>                
+                    <entry>Exception Type</entry>                
+                </row>
+            </thead>
+            <tbody>
+                <row>
+                    <entry>Method call</entry>
+                    <entry>+</entry>
+                    <entry>+</entry>
+                    <entry>+</entry>
+                    <entry>+</entry>
+                    <entry></entry>
+                    <entry></entry>
+                </row>
+                <row>
+                    <entry>Method execution</entry>
+                    <entry>+</entry>
+                    <entry>+</entry>
+                    <entry>+</entry>
+                    <entry>+</entry>
+                    <entry></entry>
+                    <entry></entry>
+                </row>
+                <row>
+                    <entry>Constructor call</entry>
+                    <entry></entry>
+                    <entry>+</entry>
+                    <entry></entry>
+                    <entry>+</entry>
+                    <entry></entry>
+                    <entry></entry>
+                </row>
+                <row>
+                    <entry>Constructor execution</entry>
+                    <entry></entry>
+                    <entry>+</entry>
+                    <entry></entry>
+                    <entry>+</entry>
+                    <entry></entry>
+                    <entry></entry>
+                </row>
+                <row>
+                    <entry>Field get</entry>
+                    <entry></entry>
+                    <entry>+</entry>
+                    <entry>+</entry>
+                    <entry></entry>
+                    <entry>+</entry>
+                    <entry></entry>
+                </row>
+                <row>
+                    <entry>Field set</entry>
+                    <entry></entry>
+                    <entry>+</entry>
+                    <entry>+</entry>
+                    <entry></entry>
+                    <entry>+</entry>
+                    <entry></entry>
+                </row>
+                <row>
+                    <entry>Pre-initialization</entry>
+                    <entry></entry>
+                    <entry>+</entry>
+                    <entry></entry>
+                    <entry>+</entry>
+                    <entry></entry>
+                    <entry></entry>
+                </row>
+                <row>
+                    <entry>Initialization</entry>
+                    <entry></entry>
+                    <entry>+</entry>
+                    <entry></entry>
+                    <entry>+</entry>
+                    <entry></entry>
+                    <entry></entry>
+                </row>
+                <row>
+                    <entry>Static initialization</entry>
+                    <entry></entry>
+                    <entry>+</entry>
+                    <entry></entry>
+                    <entry></entry>
+                    <entry></entry>
+                    <entry></entry>
+                </row>
+                <row>
+                    <entry>Handler</entry>
+                    <entry></entry>
+                    <entry></entry>
+                    <entry></entry>
+                    <entry></entry>
+                    <entry></entry>
+                    <entry>+</entry>
+                </row>
+                <row>
+                    <entry>Advice execution</entry>
+                    <entry></entry>
+                    <entry>+</entry>
+                    <entry></entry>
+                    <entry>+</entry>
+                    <entry></entry>
+                    <entry></entry>
+                </row>
+            </tbody>
+        </tgroup>
+        </informaltable>
         
-        <para>A call join point can have more than one signature. For a
-        call pointcut expression to match a given call join point, at
-        least one of the join point signatures must be matched by the
-        pointcut's signature pattern.</para>
+        <para>Note that whilst an advice excetution join point has a
+        signature comprising the declaring type of the advice and the
+        advice parameter types, the <literal>adviceexecution</literal>
+        pointcut designator does not support matching based on this
+        signature.</para>
         
+        <para>The signatures for most of the join point kinds should be
+        self-explanatory, except for method call and execution
+        join points, which can have multiple signatures. Each signature of 
+        a method call or execution join point has the same id and parameter
+        types, but the declaring type and return type (with covariance) may vary.
+        </para>
+        
+        <para>The following sections examine signatures for method call and
+        execution join points in more detail.</para>
+        
+        <sect2>
+            <title>Method call join point signatures</title>
+
         <para>
           For a call join point where a call is made to a method
-          <literal>m(args)</literal> on a target type <literal>T</literal> (where
+          <literal>m(parameter_types)</literal> on a target type <literal>T</literal> (where
           <literal>T</literal> is the static type of the target):
         </para>
 
@@ -27,12 +216,12 @@
 		]]></programlisting>
         
         <para>
-            Then the signature <literal>R(T) T.m(args)</literal> is a signature
+            Then the signature <literal>R(T) T.m(parameter_types)</literal> is a signature
             of the call join point, where <literal>R(T)</literal> is the return
-            type of <literal>m</literal> in <literal>T</literal>, and 
-            <literal>args</literal> represents the types of the arguments to
+            type of <literal>id</literal> in <literal>T</literal>, and 
+            <literal>parameter_types</literal> are the parameter types of
             <literal>m</literal>. If <literal>T</literal> itself does not
-            declare a definition of <literal>m(args)</literal>, then 
+            declare a definition of <literal>m(parameter_types)</literal>, then 
             <literal>R(T)</literal> is the return type in the definition of 
             <literal>m</literal> that <literal>T</literal> inherits. Given the
             call above, and the definition of <literal>T.m</literal>:                      
@@ -51,21 +240,21 @@
           R' m(String s) {...}
         }
         
-		class T extends S { 
+        class T extends S {} 
 		
 		]]></programlisting>
         
         <para>Then <literal>R' T.m(String)</literal> is a signature of the
-        call join point for <literal>t.m("hello")</literal></para>.
+        call join point for <literal>t.m("hello")</literal>.</para>
         
         <para>
             For each ancestor (super-type) <literal>A</literal> of <literal>T</literal>, 
-            if <literal>m(args)</literal> is defined for that super-type, then
-            <literal>R(A) A.m(args)</literal> is a signature of the call join
+            if <literal>m(parameter_types)</literal> is defined for that super-type, then
+            <literal>R(A) A.m(parameter_types)</literal> is a signature of the call join
             point, where <literal>R(A)</literal> is the return type of <literal>
-            m(args)</literal> as defined in <literal>A</literal>, or as inherited
+            m(parameter_types)</literal> as defined in <literal>A</literal>, or as inherited
             by <literal>A</literal> if <literal>A</literal> itself does not
-            provide a definition of <literal>m(args)</literal>.            
+            provide a definition of <literal>m(parameter_types)</literal>.            
         </para>
         
         <para>
@@ -79,21 +268,18 @@
 		]]></programlisting>
         
         <para>are all additional signatures for the call join point arising
-        from the call <literal>t.m("hello")</literal>. Thus the call
-        join point has four signatures in total. Amongst these signatures,
-        we say that the <emphasis>most-specific signature</emphasis> is the
-        signature with the most-specific declaring type - that is, the 
-        signature of the static type of the target of the call 
-        (<literal>R' T.m(String)</literal>) in this case.</para>
+        from the call <literal>t.m("hello")</literal>. Thus this call
+        join point has four signatures in total. Every signature has the same
+        id and parameter types, and a different declaring type.</para>
         
-      </sect1>
+       </sect2>
       
-      <sect1>
-          <title>Join Point Signatures for Execution Join Points</title>
+      <sect2>
+          <title>Method execution join point signatures</title>
           
           <para>Join point signatures for execution join points are defined
           in a similar manner to signatures for call join points. Given the
-          same hierarchy as in the call example in the previous section:
+          hierarchy:
           </para>
 
 
@@ -110,22 +296,191 @@
           R' m(String s) {...}
         }
         
-		class T extends S { 
+        class T extends S { }
+        
+        class U extends T {
+          R' m(String s) {...}
+        }
 		
 		]]></programlisting>
         
         <para>Then the execution join point signatures arising as a result
-        of the call to <literal>t.m("hello")</literal> are: </para>
+        of the call to <literal>u.m("hello")</literal> are: </para>
 
+        <programlisting><![CDATA[
+        R' U.m(String)
+        R' S.m(String)
+        R  P.m(String)
+        R  Q.m(String)
+		]]></programlisting>
+
+        <para>Each signature has the same id and parameter types, and a 
+        different declaring type. There is one signature for each type
+        that provides its own declaration of the method. Hence in this 
+        example there is no signature <literal>R' T.m(String)</literal>
+        as <literal>T</literal> does not provide its own declaration of
+        the method.</para>
 
+      </sect2>
+      
       </sect1>
       
       <sect1>
-          <title>Pointcut matching based on Join Point Signatures</title>
+          <title>Join Point Modifiers</title>
+          
+          <para>Every join point has a single set of modifiers - these include
+          the standard Java modifiers such as <literal>public, private,
+          static, abstract</literal> etc., any annotations, and the throws
+          clauses of methods and constructors.</para>
+          
+          <para>
+          For the different join point kinds, the modifiers are:
+          </para>
+
+          <informaltable>
+           <tgroup cols="2">
+               <thead>
+                   <row>
+                       <entry>Join Point Kind</entry>
+                       <entry>Join Point Modifiers</entry>
+                   </row>
+               </thead>
+               <tbody>
+                   <row>
+                       <entry>Method call</entry>
+                       <entry>The modifiers of the method picked out by Java as
+                       the static target of the method call.</entry>
+                   </row>
+                   <row>
+                       <entry>Method execution</entry>
+                       <entry>The modifiers of the method that is executing.</entry>
+                   </row>
+                   <row>
+                       <entry>Constructor call</entry>
+                       <entry>The modifiers of the constructor being called.</entry>
+                   </row>
+                   <row>
+                       <entry>Constructor execution</entry>
+                       <entry>The modifiers of the constructor executing.</entry>
+                   </row>
+                   <row>
+                       <entry>Field get</entry>
+                       <entry>The modifiers of the field being accessed.</entry>
+                   </row>
+                   <row>
+                       <entry>Field set</entry>
+                       <entry>The modifiers of the field being set.</entry>
+                   </row>
+                   <row>
+                       <entry>Pre-initialization</entry>
+                       <entry>The modifiers of the first constructor executing in
+                       this constructor chain.</entry>
+                   </row>
+                   <row>
+                       <entry>Initialization</entry>
+                       <entry>The modifiers of the first constructor executing in
+                       this constructor chain.</entry>
+                   </row>
+                   <row>
+                       <entry>Static initialization</entry>
+                       <entry>The modifiers of the type being initialized.</entry>
+                   </row>
+                   <row>
+                       <entry>Handler</entry>
+                       <entry>No modifiers.</entry>
+                   </row>
+                   <row>
+                       <entry>Advice execution</entry>
+                       <entry>The modifiers of the advice being executed.</entry>
+                   </row>
+               </tbody>
+           </tgroup>
+          </informaltable>          
+          
+          <para>For example, given the following types</para>
+
+        <programlisting><![CDATA[
+        public class X {        
+          @Foo
+          protected void doIt() {...} 
+        }
+        
+        public class Y extends X {        
+          public void doIt() {...}        
+        }
+		]]></programlisting>
+          
+         <para>Then the modifiers for a call to <literal>(Y y) y.doIt()</literal>
+         are simply <literal>{public}</literal>. The modifiers for a call to
+         <literal>(X x) x.doIt()</literal> are <literal>{@Foo,protected}</literal>.
+         </para>
           
-          <para>Explain signature + modifiers split, plus notion of "most-specific"
-          join point.</para>
       </sect1>
       
+      <sect1>
+          <title>Summary of Join Point Matching</title>
+
+		<para>
+		A join point has potentially multiple signatures, but only one set of
+		modifiers. <emphasis>A kinded primitive pointcut matches a particular join point 
+		if and only if</emphasis>:
+		</para>
+		
+		<orderedlist>
+		    <listitem>They are of the same kind</listitem>
+		    <listitem>The signature pattern (exactly) matches at least one 
+		    signature of the join point</listitem>
+		    <listitem>The modifiers pattern matches the modifiers of the
+		    join point</listitem>
+		</orderedlist>
+
+        <para>Given the hierarchy</para>
+
+        <programlisting><![CDATA[
+        interface Q {
+          R m(String s);
+        }
+        
+        class P implements Q {
+          @Foo
+          public R m(String s) {...}        
+        }
+        
+        class S extends P {
+          @Bar
+          public R' m(String s) {...}
+        }
+        
+        class T extends S {} 
+		
+		]]></programlisting>
+
+        <para>and the program fragment:</para>
+        
+        <programlisting><![CDATA[
+        P p = new P();
+        S s = new S();
+        T t = new T();
+        ...
+        p.m("hello");
+        s.m("hello");
+        t.m("hello");
+		]]></programlisting>
+        
+        <para>
+        The the pointcut <literal>call(@Foo R P.m(String))</literal> matches the
+        call <literal>p.m("hello")</literal> since both the signature and the 
+        modifiers match. It does not match the call <literal>s.m("hello")</literal>
+        because even though the signature pattern matches one of the signatures
+        of the join point, the modifiers pattern does not match the modifiers of
+        the method m in S which is the static target of the call.
+        </para>
+
+        <para>The pointcut <literal>call(R' m(String))</literal> matches the
+        calls <literal>t.m("hello")</literal> and <literal>s.m("hello")</literal>.
+        It does not match the call <literal>p.m("hello")</literal> since the
+        signature pattern does not match any signature for the call join point
+        of m in P.</para>
+      </sect1>
   
 </chapter>
diff --git a/docs/adk15ProgGuideDB/miscellaneous.xml b/docs/adk15ProgGuideDB/miscellaneous.xml
new file mode 100644
index 000000000..ad6ea36c4
--- /dev/null
+++ b/docs/adk15ProgGuideDB/miscellaneous.xml
@@ -0,0 +1,35 @@
+<chapter id="miscellaneous" xreflabel="Miscellaneous Changes">
+
+  <title>Other Changes in AspectJ 5</title>
+  
+  <sect1>
+      <title>Pointcuts</title>
+      
+      <sect2>
+          <title>Binding of formals</title>
+          <para>
+            Binding of formals (cannot bind same formal more than once in a conjunction, 
+            can bind exactly once in each branch of a disjunction, iff the branches are mutually
+            exclusive based on e.g. join point kind).     
+          </para>  
+      </sect2>
+      
+      <sect2>
+          <title>Additional lint warnings</title>
+          <para>
+            Discuss detection of common errors -> warning/error, eg. conjunction of more than one
+            kind of join point. Differing numbers of args in method signature / args / @args /
+            @parameters.
+          </para>
+      </sect2>
+  </sect1>
+  
+  <sect1>
+      <title>Declare Soft</title>
+      <para>
+          Describe change to only soften checked exceptions if we decide to 
+          make it.
+      </para>
+  </sect1>
+</chapter>
+
diff --git a/docs/adk15ProgGuideDB/pertypewithin.xml b/docs/adk15ProgGuideDB/pertypewithin.xml
index e870f10e5..e3f5ec0ae 100644
--- a/docs/adk15ProgGuideDB/pertypewithin.xml
+++ b/docs/adk15ProgGuideDB/pertypewithin.xml
@@ -1,20 +1,126 @@
 <chapter id="pertypewithin" xreflabel="pertypewithin">
 
   <title>The pertypewithin Aspect Instantiation Model</title>
+
+  <para>
+    AspectJ 5 defines a new per-clause type for aspect instantiation: 
+    <literal>pertypewithin</literal>. Unlike the other per-clauses,
+    <literal>pertypewithin</literal> takes a type pattern:  
+  </para>
+  
+  	<programlisting><![CDATA[
+  	PerTypeWithin := 'pertypewithin' '(' OptionalParensTypePattern ')'
+	]]></programlisting>
+  
+  <para>
+      When an aspect is declared using the <literal>pertypewithin</literal>
+      instantiation model, one new aspect instance will be created for each
+      type matched by the associated type pattern.
+  </para>
   
-  <para>This is a placeholder to stimulate discussion around a possible new
-  instantiation model : <literal>pertypewithin(OptionalParensTypePattern)</literal>.
-  The semantics of <literal>pertypewithin</literal> are that a new aspect
-  instance will be created at the <literal>staticinitialization</literal>
-  join point of each type matching the given type pattern.</para>
+  <para>
+      Pertypewithin aspects have <literal>aspectOf</literal> and 
+      <literal>hasAspect</literal> methods with the following signatures:
+  </para>
   
-  <para>Discussion must include motivating use cases. Raise the issue that
-  pertypewithin takes a type pattern, not a pointcut.</para>
+  	<programlisting><![CDATA[
+  	/**
+  	 * return true if this aspect has an instance associated with
+  	 * the given type.
+  	 */
+  	public static boolean hasAspect(Class clazz)
+  	
+  	/**
+  	 * return the instance associated with the given type.
+  	 * Throws NoAspectBoundException if there is no such
+  	 * aspect.
+  	 */
+  	 public static P aspectOf(Class clazz)
+	]]></programlisting>
+  
+   <para>
+       Where <literal>P</literal> is the type of the <literal>pertypewithin</literal>
+       aspect.
+   </para>
+   
+   <para>
+       In common with the other per-clause instantiation models, the execution
+       of any advice declared within a <literal>pertypewithin</literal> aspect
+       is conditional upon an implicit pointcut condition. In this case, that
+       any join point be <literal>within</literal> the type that the executing
+       aspect is an <literal>aspectOf</literal>. For example, given the aspect
+       definition
+   </para>
+
+  	<programlisting><![CDATA[
+  	 public aspect InstanceTracking pertypewithin(org.xyz..*) {
+  	 
+  	   private Set<WeakReference<Object>> instances = new HashSet<WeakReference<Object>>();
+  	   
+  	   after(Object o) returning : execution(new(..)) {
+  	     instances.add(new WeakReference<Object>(o);
+  	   }
+  	 
+  	   public Set<Object> getInstances() {
+  	      Set<Object> result = new HashSet<Object>();
+  	      for(WeakReference<Object> ref : instances) {
+  	          if (ref.get() != null) {
+  	           result.add(ref.get());
+  	          }
+  	      }
+  	      return result;
+  	   }
+  	 }
+	]]></programlisting>
+	
+	<para>
+	    Then one aspect instance will be created for each type within
+	    <literal>org.xyz..*</literal>. For each aspect instance, the
+	    after returning advice will match only the execution of constructors
+	    in the type that the aspect is an instance of. The net result is that
+	    the aspect tracks all known instances of each type within
+	    <literal>org.xyz..*</literal>. To get access to the instances, a
+	    programmer can simply write 
+	    <literal>InstanceTracking.instanceOf(org.xyz.SomeType).getInstances()</literal>.
+	</para>
   
-  <para>We will only do this if we believe we can generate an implementation
-  that is significantly more efficient than hand-coded alternatives.</para>
+    <para>
+        A <literal>pertypewithin</literal> aspect may optionally be declared
+        with a single generic type parameter. In this case, for each type 
+        <literal>T</literal> matched by the type pattern, the aspect instance
+        created will be of type <literal>PerTypeWithinAspect&lt;T&gt;</literal>. 
+        So the previous example could also be written as:
+    </para>
 
-  <para>Need to define aspectOf(Class), hasAspect(Class).</para>
+  	<programlisting><![CDATA[
+  	 public aspect InstanceTracking<T> pertypewithin(org.xyz..*) {
+  	 
+  	   private Set<WeakReference<T>> instances = new HashSet<WeakReference<T>>();
+  	   
+  	   after(T t) returning : execution(new(..)) {
+  	     instances.add(new WeakReference<T>(t);
+  	   }
+  	 
+  	   public Set<T> getInstances() {
+  	      Set<T> result = new HashSet<T>();
+  	      for(WeakReference<T> ref : instances) {
+  	          if (ref.get() != null) {
+  	           result.add(ref.get());
+  	          }
+  	      }
+  	      return result;
+  	   }
+  	 }
+	]]></programlisting>
   
+    <para>
+        The <literal>pertypewithin</literal> aspect instantiation model should
+        be used when the implementation of a crosscutting concern requires that
+        some state be maintained for each type in a set of types. To maintain
+        state for a single type, it is easier to use a static inter-type declared
+        field. Examples of usage include instance tracking, profiling, and the
+        implementation of a common tracing idiom that uses one Logger per 
+        traced class.
+    </para>  
 </chapter>
 
diff --git a/docs/adk15ProgGuideDB/pointcutexp.xml b/docs/adk15ProgGuideDB/pointcutexp.xml
deleted file mode 100644
index be0bddcee..000000000
--- a/docs/adk15ProgGuideDB/pointcutexp.xml
+++ /dev/null
@@ -1,14 +0,0 @@
-<chapter id="pointcutexp" xreflabel="Pointcut Expressions">
-
-  <title>Pointcut Expressions</title>
-  
-  <para>
-    Discuss detection of common errors -> warning/error, eg. conjunction of more than one
-    kind of join point. Differing numbers of args in method signature / args / @args /
-    @parameters. Binding of formals (cannot bind same formal more than once in a conjunction, 
-    can bind exactly once in each branch of a disjunction, iff the branches are mutually
-    exclusive based on e.g. join point kind).     
-  </para>
-  
-</chapter>
-
diff --git a/docs/adk15ProgGuideDB/varargs.xml b/docs/adk15ProgGuideDB/varargs.xml
index ceadfed05..b74064b74 100644
--- a/docs/adk15ProgGuideDB/varargs.xml
+++ b/docs/adk15ProgGuideDB/varargs.xml
@@ -6,7 +6,7 @@
         <title>Variable-length Argument Lists in Java 5</title>
         
         <para>
-          Java 5 (and hence AspectJ 1.5) allows you to specify methods that take a 
+          Java 5 (and hence AspectJ 5) allows you to specify methods that take a 
           variable number of arguments of a specified type. This is achieved using
           an ellipsis (...) in the method signature as shown:    
         </para>
@@ -62,17 +62,17 @@
     <sect1>
         <title>Using Variable-length arguments in advice and pointcut expressions</title>
         
-        <para>AspectJ 1.5 allows variable-length arguments to be used for methods declared within
+        <para>AspectJ 5 allows variable-length arguments to be used for methods declared within
         aspects, and for inter-type declared methods and constructors, in accordance with the rules
         outlined in the previous section.</para>
         
         <para>
-        AspectJ 1.5 also allows variable length arguments to be specified in pointcut expressions and
+        AspectJ 5 also allows variable length arguments to be matched by pointcut expressions and
         bound as formals in advice.
         </para>
         
         <sect2>
-            <title>Matching signatures based on variable length arguments</title>
+            <title>Matching signatures based on variable length argument types</title>
             
             <para>
             Building on the definition of signature patterns given in the chapter on