15 files changed, 102 insertions, 102 deletions
diff --git a/docs/adk15notebook/adk15notebook.adoc b/docs/adk15notebook/adk15notebook.adoc
index 9e4594335..29c8b4e66 100644
--- a/docs/adk15notebook/adk15notebook.adoc
+++ b/docs/adk15notebook/adk15notebook.adoc
@@ -1,6 +1,6 @@
 = The AspectJ^TM^ 5 Development Kit Developer's Notebook
-
 :doctype: book
+:leveloffset: +1
 
 _by the AspectJ Team_
 
diff --git a/docs/adk15notebook/annotations.adoc b/docs/adk15notebook/annotations.adoc
index 5fcf74608..24a0d27e5 100644
--- a/docs/adk15notebook/annotations.adoc
+++ b/docs/adk15notebook/annotations.adoc
@@ -1,14 +1,14 @@
-== Annotations
+= Annotations
 
 [[annotations-inJava5]]
-=== Annotations in Java 5
+== Annotations in Java 5
 
 This section provides the essential information about annotations in
 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.
 
-==== Using Annotations
+=== Using Annotations
 
 Java 5 introduces _annotation types_ which can be used to express
 metadata relating to program members in the form of _annotations_.
@@ -55,7 +55,7 @@ Multi-value annotations must use the `member-name=value
 public void someMethod() {...}
 ....
 
-==== Retention Policies
+=== Retention Policies
 
 Annotations can have one of three retention policies:
 
@@ -74,7 +74,7 @@ Local variable annotations are not retained in class files (or at
 runtime) regardless of the retention policy set on the annotation type.
 See JLS 9.6.1.2.
 
-==== Accessing Annotations at Runtime
+=== Accessing Annotations at Runtime
 
 Java 5 supports a new interface, `java.lang.reflect.AnnotatedElement`,
 that is implemented by the reflection classes in Java (`Class`,
@@ -84,7 +84,7 @@ you access to annotations _that have runtime retention_ via the
 annotation types are just regular Java classes, the annotations returned
 by these methods can be queried just like any regular Java object.
 
-==== Annotation Inheritance
+=== Annotation Inheritance
 
 It is important to understand the rules relating to inheritance of
 annotations, as these have a bearing on join point matching based on the
@@ -120,7 +120,7 @@ interfaces never inherits any annotations from the interfaces it
 implements.
 
 [[annotations-aspectmembers]]
-=== Annotating Aspects
+== Annotating Aspects
 
 AspectJ 5 supports annotations on aspects, and on method, field,
 constructor, advice, and inter-type declarations within aspects. Method
@@ -210,14 +210,14 @@ public aspect AnAspect {
 ....
 
 [[annotations-pointcuts-and-advice]]
-=== Join Point Matching based on Annotations
+== Join Point Matching based on Annotations
 
 This section discusses changes to type pattern and signature pattern
 matching in 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.
 
-==== Annotation Patterns
+=== Annotation Patterns
 
 For any kind of annotated element (type, method, constructor, package,
 etc.), an annotation pattern can be used to match against the set of
@@ -254,7 +254,7 @@ Some examples of annotation patterns follow:
   element with an annotation that is declared in the org.xyz package or
   a sub-package. (The parenthesis are required in this example).
 
-==== Type Patterns
+=== Type Patterns
 
 AspectJ 1.5 extends type patterns to allow an optional
 `AnnotationPattern` prefix.
@@ -320,10 +320,10 @@ patterns:
   `@Inherited` annotation.
 
 [[signaturePatterns]]
-==== Signature Patterns
+=== Signature Patterns
 
 [[fieldPatterns]]
-===== Field Patterns
+==== Field Patterns
 
 A `FieldPattern` can optionally specify an annotation-matching pattern
 as the first element:
@@ -365,7 +365,7 @@ annotations that match the pattern. For example:
   `@Classified`.
 
 [[methodPatterns]]
-===== Method and Constructor Patterns
+==== Method and Constructor Patterns
 
 A `MethodPattern` can optionally specify an annotation-matching pattern
 as the first element.
@@ -424,7 +424,7 @@ annotations that match the pattern. For example:
   Matches any method taking at least one parameter, where the parameter
   type has an annotation `@Immutable`.
 
-==== Example Pointcuts
+=== Example Pointcuts
 
 `within(@Secure *)`::
   Matches any join point where the code executing is declared in a type
@@ -448,7 +448,7 @@ annotations that match the pattern. For example:
   is not `Catastrophic`. The format of the `handler` pointcut designator
   in AspectJ 5 is `'handler' '(' OptionalParensTypePattern ')'`.
 
-==== Runtime type matching and context exposure
+=== Runtime type matching and context exposure
 
 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
@@ -617,7 +617,7 @@ be used to match against annotations that have at least class-file
 retention, and if used in the binding form the annotation must have
 runtime retention.
 
-==== Package and Parameter Annotations
+=== Package and Parameter Annotations
 
 _Matching on package annotations is not supported in AspectJ. Support
 for this capability may be considered in a future release._
@@ -677,7 +677,7 @@ The parentheses are grouping @SomeOtherAnnotation with the * to form the
 type pattern for the parameter, then the type @SomeAnnotation will be
 treated as a parameter annotation pattern.
 
-==== Annotation Inheritance and pointcut matching
+=== Annotation Inheritance and pointcut matching
 
 According to the Java 5 specification, non-type annotations are not
 inherited, and annotations on types are only inherited if they have the
@@ -722,7 +722,7 @@ throws clause) is based on the subject of the join point (the method
 actually being called).
 
 [[matchingOnAnnotationValues]]
-==== Matching based on annotation values
+=== Matching based on annotation values
 
 The `if` pointcut designator can be used to write pointcuts that match
 based on the values annotation members. For example:
@@ -735,9 +735,9 @@ pointcut txRequiredMethod(Tx transactionAnnotation) :
 ....
 
 [[annotations-decp]]
-=== Using Annotations with declare statements
+== Using Annotations with declare statements
 
-==== Declare error and declare warning
+=== Declare error and declare warning
 
 Since pointcut expressions in AspectJ 5 support join point matching
 based on annotations, this facility can be exploited when writing
@@ -757,7 +757,7 @@ declare error : call(* org.xyz.model.*.*(..)) &&
                 : "Untrusted code should not call the model classes directly";
 ....
 
-==== declare parents
+=== declare parents
 
 The general form of a `declare parents` statement is:
 
@@ -787,7 +787,7 @@ 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).
 
-==== declare precedence
+=== declare precedence
 
 The general form of a declare precedence statement is:
 
@@ -805,7 +805,7 @@ information as part of the pattern specification. For example:
   security-related aspects take precedence).
 
 [[annotations-declare]]
-=== Declare Annotation
+== Declare Annotation
 
 AspectJ 5 supports a new kind of declare statement,
 `declare annotation`. This takes different forms according to the
@@ -854,6 +854,6 @@ declare @constructor : BankAccount+.new(..) :
   annotation.
 
 [[annotations-itds]]
-=== Inter-type Declarations
+== Inter-type Declarations
 
 An annotation type may not be the target of an inter-type declaration.
diff --git a/docs/adk15notebook/ataspectj.adoc b/docs/adk15notebook/ataspectj.adoc
index 3b4d2ae59..028ef4c85 100644
--- a/docs/adk15notebook/ataspectj.adoc
+++ b/docs/adk15notebook/ataspectj.adoc
@@ -1,8 +1,8 @@
 [[ataspectj]]
-== An Annotation Based Development Style
+= An Annotation Based Development Style
 
 [[ataspectj-intro]]
-=== Introduction
+== Introduction
 
 In addition to the familiar AspectJ code-based style of aspect
 declaration, AspectJ 5 also supports an annotation-based style of aspect
@@ -25,7 +25,7 @@ chapter we introduce the @AspectJ annotations and show how they can be
 used to declare aspects and aspect members.
 
 [[ataspectj-aspects]]
-=== Aspect Declarations
+== Aspect Declarations
 
 Aspect declarations are supported by the
 `org.aspectj.lang.annotation.Aspect` annotation. The declaration:
@@ -59,18 +59,18 @@ is equivalent to...
 public aspect Foo perthis(execution(* abc..*(..))) {}
 ....
 
-==== Limitations
+=== Limitations
 
 Privileged aspects are not supported by the annotation style.
 
 [[ataspectj-pcadvice]]
-=== Pointcuts and Advice
+== Pointcuts and Advice
 
 Pointcut and advice declarations can be made using the
 `Pointcut, Before, After, AfterReturning, AfterThrowing,` and `Around`
 annotations.
 
-==== Pointcuts
+=== Pointcuts
 
 Pointcuts are specified using the `org.aspectj.lang.annotation.Pointcut`
 annotation on a method declaration. The method should have a `void`
@@ -136,7 +136,7 @@ is equivalent to...
 protected abstract pointcut anyCall();
 ....
 
-===== Type references inside @AspectJ annotations
+==== Type references inside @AspectJ annotations
 
 Using the code style, types referenced in pointcut expressions are
 resolved with respect to the imported types in the compilation unit.
@@ -179,7 +179,7 @@ public class Foo {
 }
 ....
 
-===== if() pointcut expressions
+==== if() pointcut expressions
 
 In code style, it is possible to use the `if(...)` poincut to define a
 conditional pointcut expression which will be evaluated at runtime for
@@ -255,7 +255,7 @@ The special forms `if(true)` and `if(false)` can be used in a more
 general way and don't imply that the pointcut method must have a body.
 You can thus write `@Before("somePoincut() && if(false)")` .
 
-==== Advice
+=== Advice
 
 In this section we first discuss the use of annotations for simple
 advice declarations. Then we show how `thisJoinPoint` and its siblings
@@ -485,7 +485,7 @@ above aren't obeyed, then it will unfortunately manifest as a runtime
 error.
 
 [[ataspectj-itds]]
-=== Inter-type Declarations
+== Inter-type Declarations
 
 Inter-type declarations are challenging to support using an annotation
 style. For code style aspects compiled with the _ajc_ compiler, the entire
@@ -521,7 +521,7 @@ The `defaultImpl` attribute of `@DeclareParents` may become deprecated if
 introduce a marker interface.
 
 [[atDeclareParents]]
-==== @DeclareParents
+=== @DeclareParents
 
 Consider the following aspect:
 
@@ -641,7 +641,7 @@ If the interface defines one or more operations, and these are not
 implemented by the target type, an error will be issued during weaving.
 
 [[atDeclareMixin]]
-==== @DeclareMixin
+=== @DeclareMixin
 
 Consider the following aspect:
 
@@ -793,7 +793,7 @@ Any annotations defined on the interface methods are also put upon the
 delegate forwarding methods created in the matched target type.
 
 [[ataspectj-declare]]
-=== Declare statements
+== Declare statements
 
 The previous section on inter-type declarations covered the case of
 `declare parents ...` implements. The 1.5.0 release of AspectJ 5 does not
@@ -865,7 +865,7 @@ static String getMessage() {
 ....
 
 [[ataspectj-aspectof]]
-=== `aspectOf()` and `hasAspect()` methods
+== `aspectOf()` and `hasAspect()` methods
 
 A central part of AspectJ's programming model is that aspects written
 using the code style and compiled using ajc support `aspectOf` and
diff --git a/docs/adk15notebook/autoboxing.adoc b/docs/adk15notebook/autoboxing.adoc
index fa3842950..11803d632 100644
--- a/docs/adk15notebook/autoboxing.adoc
+++ b/docs/adk15notebook/autoboxing.adoc
@@ -1,8 +1,8 @@
 [[autoboxing]]
-== Autoboxing and Unboxing
+= Autoboxing and Unboxing
 
 [[boxing-inJava5]]
-=== Autoboxing and Unboxing in Java 5
+== Autoboxing and Unboxing in Java 5
 
 Java 5 (and hence AspectJ 1.5) supports automatic conversion of
 primitive types (`int`, `float`, `double` etc.) to their object equivalents
@@ -23,7 +23,7 @@ Integer i2 = 5;      // autoboxing
 ....
 
 [[autoboxing-in-aspectj5]]
-=== Autoboxing and Join Point matching in AspectJ 5
+== Autoboxing and Join Point matching in AspectJ 5
 
 Most of the pointcut designators match based on signatures, and hence
 are unaffected by autoboxing. For example, a call to a method
@@ -63,7 +63,7 @@ before(Integer i) : foo(i) {
 ....
 
 [[autoboxing-and-method-dispatch]]
-=== Inter-type method declarations and method dispatch
+== Inter-type method declarations and method dispatch
 
 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
diff --git a/docs/adk15notebook/covariance.adoc b/docs/adk15notebook/covariance.adoc
index 2349bf52c..fdaa6000d 100644
--- a/docs/adk15notebook/covariance.adoc
+++ b/docs/adk15notebook/covariance.adoc
@@ -1,7 +1,7 @@
-== Covariance
+= Covariance
 
 [[covariance-inJava5]]
-=== Covariance in Java 5
+== Covariance in Java 5
 
 Java 5 (and hence AspectJ 5) allows you to narrow the return type in an
 overriding method. For example:
@@ -19,7 +19,7 @@ class B extends A {
 ....
 
 [[covariance-and-join-point-matching]]
-=== Covariant methods and Join Point matching
+== Covariant methods and Join Point matching
 
 The join point matching rules for `call` and `execution` pointcut
 designators are extended to match against covariant methods.
diff --git a/docs/adk15notebook/enumeratedtypes.adoc b/docs/adk15notebook/enumeratedtypes.adoc
index 64a96d2f6..a8e6b20fd 100644
--- a/docs/adk15notebook/enumeratedtypes.adoc
+++ b/docs/adk15notebook/enumeratedtypes.adoc
@@ -1,8 +1,8 @@
 [[enumeratedtypes]]
-== Enumerated Types
+= Enumerated Types
 
 [[enums-in-java5]]
-=== Enumerated Types in Java 5
+== Enumerated Types in Java 5
 
 Java 5 (and hence AspectJ 5) provides explicit support for enumerated
 types. In the simplest case, you can declare an enumerated type as
@@ -24,7 +24,7 @@ Enumerated types in Java 5 all implicitly extend the type
 class.
 
 [[enums-in-aspectj5]]
-=== Enumerated Types in AspectJ 5
+== Enumerated Types in AspectJ 5
 
 AspectJ 5 supports the declaration of enumerated types just as Java 5
 does. Because of the special restrictions Java 5 places around
diff --git a/docs/adk15notebook/generics.adoc b/docs/adk15notebook/generics.adoc
index 8fc99bdbe..404da5514 100644
--- a/docs/adk15notebook/generics.adoc
+++ b/docs/adk15notebook/generics.adoc
@@ -1,14 +1,14 @@
-== Generics
+= Generics
 
 [[generics-inJava5]]
-=== Generics in Java 5
+== Generics in Java 5
 
 This section provides the essential information about generics in Java 5
 needed to understand how generics are treated in AspectJ 5. For a full
 introduction to generics in Java, please see the documentation for the
 Java 5 SDK.
 
-==== Declaring Generic Types
+=== Declaring Generic Types
 
 A generic type is declared with one or more type parameters following
 the type name. By convention formal type parameters are named using a
@@ -57,7 +57,7 @@ Some examples follow:
   with a type that is a subtype of `Number` and that implements
   `Comparable`.
 
-==== Using Generic and Parameterized Types
+=== Using Generic and Parameterized Types
 
 You declare a variable (or a method/constructor argument) of a
 parameterized type by specifying a concrete type specfication for each
@@ -132,7 +132,7 @@ more parameterized interfaces (for example,
 time be a subtype of two interface types which are different
 parameterizations of the same interface.
 
-==== Subtypes, Supertypes, and Assignability
+=== Subtypes, Supertypes, and Assignability
 
 The supertype of a generic type `C` is the type given in the extends
 clause of `C`, or `Object` if no extends clause is present. Given the
@@ -163,7 +163,7 @@ example, `List<String>` can be assigned to a variable of type
 `Collection<?>`, and `List<Double>` can be assigned to a variable of
 type `List<? extends Number>`.
 
-==== Generic Methods and Constructors
+=== Generic Methods and Constructors
 
 A static method may be declared with one or more type parameters as in
 the following declaration:
@@ -186,7 +186,7 @@ in a similar fashion:
 
 The same technique can be used to declare a generic constructor.
 
-==== Erasure
+=== Erasure
 
 Generics in Java are implemented using a technique called _erasure_. All
 type parameter information is erased from the run-time type system.
@@ -196,7 +196,7 @@ of type `List<String>`. A consequence of this is that you cannot at
 runtime ask if an object is an `instanceof` a parameterized type.
 
 [[generics-inAspectJ5]]
-=== Generics in AspectJ 5
+== Generics in AspectJ 5
 
 AspectJ 5 provides full support for all of the Java 5 language features,
 including generics. Any legal Java 5 program is a legal AspectJ 5
@@ -205,7 +205,7 @@ parameterized types in pointcuts, inter-type declarations, and declare
 statements. Parameterized types may freely be used within aspect
 members, and support is also provided for generic _abstract_ aspects.
 
-==== Matching generic and parameterized types in pointcut expressions
+=== Matching generic and parameterized types in pointcut expressions
 
 The simplest way to work with generic and parameterized types in
 pointcut expressions and type patterns is simply to use the raw type
@@ -273,7 +273,7 @@ respectively. The members of the generic type `G` can be matched by a
 signature pattern matching `Object G.myData` and
 `public List G.getAllDataItems()` respectively.
 
-===== Restricting matching using parameterized types
+==== Restricting matching using parameterized types
 
 Pointcut matching can be further restricted to match only given
 parameterizations of parameter types (methods and constructors), return
@@ -337,7 +337,7 @@ The execution of `foo` can be matched by `execution(List foo(List))`,
 `execution(List<Object> foo(List<String>>)` since the erasure of
 `List<T>` is `List` and not `List<Object>`.
 
-===== Generic wildcards and signature matching
+==== Generic wildcards and signature matching
 
 When it comes to signature matching, a type parameterized using a
 generic wildcard is a distinct type. For example, `List<?>` is a very
@@ -365,7 +365,7 @@ class C {
   matches both the execution of `foo` and the execution of `bar` since
   the upper bound of `List<?>` is implicitly `Object`.
 
-===== Treatment of bridge methods
+==== Treatment of bridge methods
 
 Under certain circumstances a Java 5 compiler is required to create
 _bridge methods_ that support the compilation of programs using raw
@@ -422,7 +422,7 @@ Object n = new Integer(5);
 rawType.foo(n);     // call to bridge method that would succeed at runtime
 ....
 
-===== Runtime type matching with this(), target() and args()
+==== Runtime type matching with this(), target() and args()
 
 The `this()`, `target()`, and `args()` pointcut expressions all match
 based on the runtime type of their arguments. Because Java 5 implements
@@ -591,7 +591,7 @@ aspect A {
 }
 ....
 
-===== Binding return values in after returning advice
+==== Binding return values in after returning advice
 
 After returning advice can be used to bind the return value from a
 matched join point. AspectJ 5 supports the use of a parameterized type
@@ -651,7 +651,7 @@ executes on lists _statically determinable_ to be of the right type by
 specifying a return type pattern in the associated pointcut. The
 `@SuppressAjWarnings` annotation can also be used if desired.
 
-===== Declaring pointcuts inside generic types
+==== Declaring pointcuts inside generic types
 
 Pointcuts can be declared in both classes and aspects. A pointcut
 declared in a generic type may use the type variables of the type in
@@ -692,7 +692,7 @@ public aspect A {
 }
 ....
 
-==== Inter-type Declarations
+=== Inter-type Declarations
 
 AspectJ 5 supports the inter-type declaration of generic methods, and of
 members on generic types. For generic methods, the syntax is exactly as
@@ -743,7 +743,7 @@ declare a member on behalf of (say) `Bar<String>`, you can only declare
 members on the generic type `Bar<T>`.
 
 [[declare-parents-java5]]
-==== Declare Parents
+=== Declare Parents
 
 Both generic and parameterized types can be used as the parent type in a
 `declare parents` statement (as long as the resulting type hierarchy
@@ -758,14 +758,14 @@ statement.
   since a type cannot implement multiple parameterizations of the same
   generic interface type.
 
-==== Declare Soft
+=== Declare Soft
 
 It is an error to use a generic or parameterized type as the softened
 exception type in a declare soft statement. Java 5 does not permit a
 generic class to be a direct or indirect subtype of `Throwable` (JLS
 8.1.2).
 
-==== Generic Aspects
+=== Generic Aspects
 
 AspectJ 5 allows an _abstract_ aspect to be declared as a generic type.
 Any concrete aspect extending a generic abstract aspect must extend a
diff --git a/docs/adk15notebook/grammar.adoc b/docs/adk15notebook/grammar.adoc
index 42b0a0fa5..710f98947 100644
--- a/docs/adk15notebook/grammar.adoc
+++ b/docs/adk15notebook/grammar.adoc
@@ -1,9 +1,9 @@
 [[grammar]]
-== A Grammar for the AspectJ 5 Language
+= A Grammar for the AspectJ 5 Language
 
 [source, text]
 ....
-=== type patterns ===
+== type patterns ===
 
 TypePattern :=
     SimpleTypePattern |
@@ -26,13 +26,13 @@ NotStarNamePattern :=
 
 FullyQualifiedName := JavaIdentifierCharacter+ ('.' JavaIdentifierCharacter+)*
 
-=== annotation patterns ===
+== annotation patterns ===
 
 AnnotationPattern := '!'? '@' AnnotationTypePattern AnnotationPattern*
 
 AnnotationTypePattern := FullyQualifiedName | '(' TypePattern ')'
 
-=== signature patterns ===
+== signature patterns ===
 
 -- field --
 
@@ -88,7 +88,7 @@ ConstructorModifiersPattern :=
 
 ConstructorModifier := 'public' | 'private' | 'protected'
 
-=== Pointcuts ===
+== Pointcuts ===
 
 PointcutPrimitive :=
     Call | Execution | Get | Set | Handler |
@@ -174,19 +174,19 @@ PointcutExpression :=
     PointcutExpression '&&' PointcutExpression |
     PointcutExpression '||' PointcutExpression
 
-=== Advice ===
+== Advice ===
 
 to be written...
 
-=== Inter-type Declarations ===
+== Inter-type Declarations ===
 
 to be written...
 
-=== Declare Statements ===
+== Declare Statements ===
 
 to be written...
 
-=== Aspects ===
+== Aspects ===
 
 to be written...
 ....
diff --git a/docs/adk15notebook/index.adoc b/docs/adk15notebook/index.adoc
index 9a69c9e14..3dc473aef 100644
--- a/docs/adk15notebook/index.adoc
+++ b/docs/adk15notebook/index.adoc
@@ -1,6 +1,6 @@
 = The AspectJ^TM^ 5 Development Kit Developer's Notebook
-
 :doctype: book
+:leveloffset: +1
 
 _by the AspectJ Team_
 
diff --git a/docs/adk15notebook/joinpointsignatures.adoc b/docs/adk15notebook/joinpointsignatures.adoc
index 1ed54baa8..eca1b86b5 100644
--- a/docs/adk15notebook/joinpointsignatures.adoc
+++ b/docs/adk15notebook/joinpointsignatures.adoc
@@ -1,5 +1,5 @@
 [[jpsigs]]
-== Join Point Signatures
+= Join Point Signatures
 
 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
@@ -7,7 +7,7 @@ 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.
 
-=== Join Point Matching
+== Join Point Matching
 
 AspectJ supports 11 different kinds of join points. These are the
 `method call, method execution, constructor call, constructor execution, field get,
@@ -48,7 +48,7 @@ describe what the signature(s) of a join point are, and what the
 subjects of join points are.
 
 [[join-point-signatures]]
-=== Join Point Signatures
+== Join Point Signatures
 
 Call, execution, get, and set join points may potentially have multiple
 signatures. All other join points have exactly one signature. The
@@ -88,7 +88,7 @@ has the same id and field type, but the declaring type may vary.
 The following sections examine signatures for these join points in more
 detail.
 
-==== Method call join point signatures
+=== Method call join point signatures
 
 For a call join point where a call is made to a method
 `m(parameter_types)` on a target type `T` (where `T` is the static type
@@ -147,7 +147,7 @@ call `t.m("hello")`. Thus this call join point has four signatures in
 total. Every signature has the same id and parameter types, and a
 different declaring type.
 
-==== Method execution join point signatures
+=== Method execution join point signatures
 
 Join point signatures for execution join points are defined in a similar
 manner to signatures for call join points. Given the hierarchy:
@@ -190,7 +190,7 @@ own declaration of the method. Hence in this example there is no
 signature `R' T.m(String)` as `T` does not provide its own declaration
 of the method.
 
-==== Field get and set join point signatures
+=== Field get and set join point signatures
 
 For a field get join point where an access is made to a field `f` of
 type `F` on a object with declared type `T`, then `F T.f` is a signature
@@ -226,7 +226,7 @@ F T.f
 The signatures for a field set join point are derived in an identical
 manner.
 
-=== Join Point Modifiers
+== Join Point Modifiers
 
 Every join point has a single set of modifiers - these include the
 standard Java modifiers such as `public, private,
@@ -280,11 +280,11 @@ public class Y extends X {
 }
 ....
 
-Then the modifiers for a call to `(Y y) y.doIt()` are simply `{public}`.
-The modifiers for a call to `(X x) x.doIt()` are `{@Foo,protected}`.
+Then the modifiers for a call to `(Y y) y.doIt()` are simply `{ public }`.
+The modifiers for a call to `(X x) x.doIt()` are `{ @Foo, protected }`.
 
 [[join-point-matching-summary]]
-=== Summary of Join Point Matching
+== Summary of Join Point Matching
 
 A join point has potentially multiple signatures, but only one set of
 modifiers. _A kinded primitive pointcut matches a particular join point
diff --git a/docs/adk15notebook/ltw.adoc b/docs/adk15notebook/ltw.adoc
index c6c3e73f4..ddf5af356 100644
--- a/docs/adk15notebook/ltw.adoc
+++ b/docs/adk15notebook/ltw.adoc
@@ -1,8 +1,8 @@
 [[ltw]]
-== Load-Time Weaving
+= Load-Time Weaving
 
 [[ltw-introduction]]
-=== Introduction
+== Introduction
 
 See xref:../devguide/ltw.adoc#ltw[Developer's Guide] for information on
 load-time weaving support in AspectJ 5.
diff --git a/docs/adk15notebook/miscellaneous.adoc b/docs/adk15notebook/miscellaneous.adoc
index a61f704b8..eff35ab7c 100644
--- a/docs/adk15notebook/miscellaneous.adoc
+++ b/docs/adk15notebook/miscellaneous.adoc
@@ -1,8 +1,8 @@
 [[miscellaneous]]
-== Other Changes in AspectJ 5
+= Other Changes in AspectJ 5
 
 [[pointcuts-change]]
-=== Pointcuts
+== Pointcuts
 
 AspectJ 5 is more liberal than AspectJ 1.2.1 in accepting pointcut
 expressions that bind context variables in more than one location. For
@@ -22,7 +22,7 @@ for instance, no join point can be both an execution join point and a
 set join point so the two branches are mutually exclusive.
 
 [[declare-soft-change]]
-=== Declare Soft
+== Declare Soft
 
 The semantics of the `declare soft` statement have been refined in
 AspectJ 5 to only soften exceptions that are not already runtime
diff --git a/docs/adk15notebook/pertypewithin.adoc b/docs/adk15notebook/pertypewithin.adoc
index 32295fc1f..8d8abbb66 100644
--- a/docs/adk15notebook/pertypewithin.adoc
+++ b/docs/adk15notebook/pertypewithin.adoc
@@ -1,5 +1,5 @@
 [[pertypewithin]]
-== The `pertypewithin` Aspect Instantiation Model
+= The `pertypewithin` Aspect Instantiation Model
 
 AspectJ 5 defines a new per-clause type for aspect instantiation:
 `pertypewithin`. Unlike the other per-clauses, `pertypewithin` takes a
diff --git a/docs/adk15notebook/reflection.adoc b/docs/adk15notebook/reflection.adoc
index b39919229..fa7934a90 100644
--- a/docs/adk15notebook/reflection.adoc
+++ b/docs/adk15notebook/reflection.adoc
@@ -1,5 +1,5 @@
 [[reflection]]
-== New Reflection Interfaces
+= New Reflection Interfaces
 
 AspectJ 5 provides a full set of reflection APIs analogous to the
 `java.lang.reflect` package, but fully aware of the AspectJ type system.
@@ -8,7 +8,7 @@ reflection APIs are only supported when running under Java 5 and for
 code compiled by the AspectJ 5 compiler at target level 1.5.
 
 [[reflection_api]]
-=== Using `AjTypeSystem`
+== Using `AjTypeSystem`
 
 The starting point for using the reflection apis is
 `org.aspectj.lang.reflect.AjTypeSystem` which provides the method
diff --git a/docs/adk15notebook/varargs.adoc b/docs/adk15notebook/varargs.adoc
index 3f13ab31a..d45498b85 100644
--- a/docs/adk15notebook/varargs.adoc
+++ b/docs/adk15notebook/varargs.adoc
@@ -1,7 +1,7 @@
-== Varargs
+= Varargs
 
 [[varargs-inJava5]]
-=== Variable-length Argument Lists in Java 5
+== Variable-length Argument Lists in Java 5
 
 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
@@ -15,7 +15,7 @@ public void foo(int i, String... strings) {}
 A method or constructor may take at most one variable length argument,
 and this must always be the last declared argument in the signature.
 
-==== Calling Methods and Constructors with variable-length arguments
+=== Calling Methods and Constructors with variable-length arguments
 
 A _varargs_ method may be called with zero or more arguments in the
 variable argument position. For example, given the definition of `foo`
@@ -49,7 +49,7 @@ foo(7,new String[] {"One String","Two Strings"});
 ....
 
 [[varargs-in-pcds]]
-=== Using Variable-length arguments in advice and pointcut expressions
+== Using Variable-length arguments in advice and pointcut expressions
 
 AspectJ 5 allows variable-length arguments to be used for methods
 declared within aspects, and for inter-type declared methods and
@@ -59,7 +59,7 @@ section.
 AspectJ 5 also allows variable length arguments to be matched by
 pointcut expressions and bound as formals in advice.
 
-==== Matching signatures based on variable length argument types
+=== Matching signatures based on variable length argument types
 
 Recall from the definition of signature patterns given in the chapter on
 annotations (xref:annotations.adoc#signaturePatterns[Signature Patterns]), that `MethodPattern` and
@@ -109,7 +109,7 @@ point for `foo`, but not `bar`. The pointcut
 `execution(* *.*(String[]))` matches the execution join point for `bar`
 but not `foo`.
 
-==== Exposing variable-length arguments as context in pointcuts and advice
+=== Exposing variable-length arguments as context in pointcuts and advice
 
 When a varargs parameter is used within the body of a method, it has an
 array type, as discussed in the introduction to this section. We follow