Always use ":leveloffset: +1" with ":doctype: book"

Headlines per ADOC file should start at level 1, not 2. Adjusting the
level offset for books helps to avoid warnings when including book
chapters, but still allows to also use the chapters as stand-alone
documents.

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

108 files changed, 965 insertions, 948 deletions

diff --git a/docs/LICENSE-AspectJ.adoc b/docs/LICENSE-AspectJ.adoc
index ca18dbede..387a985e5 100644
--- a/docs/LICENSE-AspectJ.adoc
+++ b/docs/LICENSE-AspectJ.adoc
@@ -1,4 +1,4 @@
-== *AspectJ^TM^ Compiler and Core Tools License*
+= AspectJ^TM^ Compiler and Core Tools License
 
 This is a binary-only release. Source code is available from
 https://eclipse.org/aspectj
@@ -7,7 +7,7 @@ The Eclipse Foundation makes available all content in this distribution
 ("Content"). Unless otherwise indicated below, the Content is provided
 to you under the terms and conditions of the Eclipse Public License
 Version v 2.0 ("EPL"). A copy of the EPL is available at
-xref:../../org/documents/epl-2.0/EPL-2.0.txt[https://www.eclipse.org/org/documents/epl-2.0/EPL-2.0.txt].
+link:[https://www.eclipse.org/org/documents/epl-2.0/EPL-2.0.txt].
 For purposes of the EPL, "Program" will mean the Content.
 
 If you did not receive this Content directly from the Eclipse
@@ -17,9 +17,9 @@ use of any object code in the Content. Check the Redistributor's license
 that was provided with the Content. If no such license exists, contact
 the Redistributor. Unless otherwise indicated below, the terms and
 conditions of the EPL still apply to any source code in the Content and
-such source code may be obtained at link:/[https://www.eclipse.org].
+such source code may be obtained at link:[https://www.eclipse.org].
 
-=== Third Party Content
+== Third Party Content
 
 The Content includes items that have been sourced from third parties as
 set out below. If you did not receive this Content directly from the
@@ -27,9 +27,7 @@ Eclipse Foundation, the following is provided for informational purposes
 only, and you should look to the Redistributor's license for terms and
 conditions of use.
 
-__
-
-==== BCEL v5.1
+=== BCEL v5.1
 
 This product contains software developed by the Apache Software
 Foundation (http://www.apache.org/[http://www.apache.org]).
@@ -40,7 +38,7 @@ https://commons.apache.org/bcel/. Source code for the modified version
 of BCEL is available at Eclipse.org in the AspectJ source tree. This
 code is made available under the Apache Software License v1.1
 
-==== ASM v2.2.1
+=== ASM v2.2.1
 
 AspectJ includes a binary version of ASM v2.2.1
 (http://asm.objectweb.org/index.html[http://asm.objectweb.org/]) The
diff --git a/docs/README-AspectJ.adoc b/docs/README-AspectJ.adoc
index c754f3a44..e8905dfcf 100644
--- a/docs/README-AspectJ.adoc
+++ b/docs/README-AspectJ.adoc
@@ -1,8 +1,8 @@
-== AspectJ^TM^
+= AspectJ^TM^
 
 _Version @build.version.long@ released on @build.date@._
 
-=== 1 Contents of this Package
+== 1 Contents of this Package
 
 * the link:bin[`<aspectj install dir>/bin`] directory has scripts for
 ** `ajc`: the compiler for the AspectJ language
@@ -19,7 +19,7 @@ the link:doc/index.html[index] page.
 
 '''''
 
-=== 2 Install Procedure
+== 2 Install Procedure
 
 The AspectJ tool `ajc` is a Java program that can be
 run indirectly from the scripts or directly from `aspectjtools.jar`. The
@@ -62,7 +62,7 @@ create short launch scripts to start ajc easily (section 3).
 
 '''''
 
-=== 3. Running the Tools
+== 3. Running the Tools
 
 If you did not use the automatic installation process or the default
 launch scripts do not work on your system, you may wish to create short
@@ -98,9 +98,9 @@ ____
 '''''
 
 [[configInstructions]]
-=== 4. Configuration Instructions
+== 4. Configuration Instructions
 
-==== 4.1 Adding `<aspectj install dir>/lib/aspectjrt.jar` to your classpath
+=== 4.1 Adding `<aspectj install dir>/lib/aspectjrt.jar` to your classpath
 
 There are several ways to add this jar file to your classpath:
 
@@ -110,7 +110,7 @@ next section for details)
 * always use the "`-classpath aspectjrt.jar`" option when running
 programs compiled with ajc
 
-==== 4.2 [#6.1]#Setting the Environment Variables on Windows#
+=== 4.2 [#6.1]#Setting the Environment Variables on Windows#
 
 The following instructions use the PATH variable as an example, but this
 process is identical for the CLASSPATH variable.
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
diff --git a/docs/developer/IDE.md b/docs/developer/IDE.md
index d34f1c404..fbafbe384 100644
--- a/docs/developer/IDE.md
+++ b/docs/developer/IDE.md
@@ -113,7 +113,7 @@ Guide.
 ### Command line
 
 If you wish to install AspectJ in a separate directory and use it from the command line without any extra build tools,
-feel free to download the **AspectJ installer**. It is and executable JAR installer. It requires Java and possibly admin
+feel free to download the **AspectJ installer**. It is an executable JAR installer, requires Java and possibly admin
 rights, if e.g. under Windows you want to install AspectJ to _C:/Program Files/AspectJ_. You execute it from a command
 prompt via `java -jar installer-<version>.jar` and select your installation options. Then you add `<ASPECTJ_HOME>/bin`
 to your path and are good to go. You can now call tools like the Aspectj compiler `ajc` or the AspectJ documentation
diff --git a/docs/developer/compiler-weaver.adoc b/docs/developer/compiler-weaver.adoc
index ba1b28260..373a67c05 100644
--- a/docs/developer/compiler-weaver.adoc
+++ b/docs/developer/compiler-weaver.adoc
@@ -1,4 +1,8 @@
-== Guide for Developers of the AspectJ Compiler and Weaver
+= Guide for Developers of the AspectJ Compiler and Weaver
+:doctype: book
+:leveloffset: +1
+
+= Guide for Developers of the AspectJ Compiler and Weaver
 
 _Latest (non-license) content update: 2004-02-20 by jhugunin_
 
@@ -36,7 +40,7 @@ weaving API which can be used to implement ClassLoaders that will weave
 advice into classes dynamically as they are loaded by the virtual
 machine.
 
-=== Compiler front-end (org.aspectj.ajdt.core)
+== Compiler front-end (org.aspectj.ajdt.core)
 
 The front-end of the AspectJ compiler is implemented as an extension of
 the Java compiler from eclipse.org. The source-file portion of the
@@ -61,7 +65,7 @@ binding and some AspectJ augmentation
 . For each source file do a deep parse, annotation/analysis, and then
 code generation
 
-==== Top-level parse tree
+=== Top-level parse tree
 
 Let's trace the following example program through the compiler.
 
@@ -96,7 +100,7 @@ When parsed, this program will produce the following tree.
 
 image:images/top-tree.png[image]
 
-==== PointcutDeclaration processing
+=== PointcutDeclaration processing
 
 Let's look more closely at the pointcut declaration:
 
@@ -112,7 +116,7 @@ declaration. The actual pointcut is parsed by the weaver module. This
 parsing happens as part of the shallow parse phase. This is because this
 information might be needed to implement a declare soft.
 
-==== AdviceDeclaration processing
+=== AdviceDeclaration processing
 
 Next we look at the processing for an advice declaration:
 
@@ -138,13 +142,13 @@ advice is still null. This field is not filled in until the second stage
 of the compiler when full parsing is done on each source file as a
 prelude to generating the classfile.
 
-==== Overview of the main classes in org.aspectj.ajdt.core
+=== Overview of the main classes in org.aspectj.ajdt.core
 
 The main classes in this module are shown in the following diagram:
 
 image:images/ajdt-uml.png[image]
 
-=== Weaving back-end (weaver)
+== Weaving back-end (weaver)
 
 This provides all of the weaving functionality. It has very few
 dependencies to keep the code as small as possible for deployment in
@@ -174,7 +178,7 @@ static shadow. If it could match, it inserts a call to the advice’s
 implementation method guarded by any dynamic testing needed to ensure
 the match.
 
-=== Runtime support library (runtime)
+== Runtime support library (runtime)
 
 This library provides classes that are used by the generated code at
 runtime. These are the only classes that must be redistributed with a
@@ -191,7 +195,7 @@ There are also several packages all under the header org.aspectj.runtime
 that are considered private to the implementation and may only be used
 by code generated by the AspectJ compiler.
 
-=== Mappings from AspectJ language to implementation
+== Mappings from AspectJ language to implementation
 
 [cols=",,",]
 |===
@@ -222,7 +226,7 @@ patterns.DeclareErrorOrWarning
 |pcd |ast.PointcutDesignator |patterns.Pointcut hierarchy
 |===
 
-== Tutorial: implementing a throw join point
+= Tutorial: implementing a throw join point
 
 This tutorial will walk step-by-step through the process of adding a new
 join point to AspectJ for the moment when an exception is thrown. In
@@ -237,14 +241,14 @@ size of your actual code changes will likely be smaller, but you are
 likely to need to be familiar with all of the pieces of the
 implementation described below.
 
-=== Part 1: Adding the join point and corresponding pcd
+== Part 1: Adding the join point and corresponding pcd
 
 The first part of this tutorial will implement the main features of the
 throw join point. We will create a new join point shadow corresponding
 to the athrow instruction and also create a new pointcut designator
 (pcd) for matching it.
 
-==== Step 1. Synchronize with repository and run the existing test suite
+=== Step 1. Synchronize with repository and run the existing test suite
 
 Do a Team->Synchronize With Repository and make sure that your tree is
 completely in sync with the existing repository. Make sure to address
@@ -261,7 +265,7 @@ Run the existing test suite. I currently do this in four steps:
 There should be no failures when you run these tests. If there are
 failures, resolve them with the AspectJ developers before moving on.
 
-==== Step 2. Write a proto test case
+=== Step 2. Write a proto test case
 
 {empty}a. Create a new file in tests/design/pcds/Throw.java
 
@@ -315,7 +319,7 @@ about to execute: call(java.lang.RuntimeException(String))
 PASS Suite.Spec(c:\aspectj\eclipse\tests) 1 tests (1 passed) 2 seconds
 ....
 
-==== Step 3. Implement the new join point shadow kind
+=== Step 3. Implement the new join point shadow kind
 
 Modify runtime/org.aspectj.lang/JoinPoint.java to add a name for the
 Throw shadow kind.
@@ -362,7 +366,7 @@ Shadow.Kind.
 case 12: return Throw;
 ....
 
-==== Step 4. Create this new kind of joinpoint for the throw bytecode
+=== Step 4. Create this new kind of joinpoint for the throw bytecode
 
 Modify weaver/org.aspectj.weaver.bcel/BcelClassWeaver.java to recognize
 this new joinpoint kind. In the method
@@ -450,7 +454,7 @@ we used Member.HANDLER for the kind of the signature of this join point.
 That's clearly not correct. We'll fix that at the end of the lesson as
 part of the clean-up. For now, let's go on with the interesting parts.
 
-==== Step 5. Extend our proto-test to use a pointcut designator for matching
+=== Step 5. Extend our proto-test to use a pointcut designator for matching
 
 Add a second piece of before advice to the test aspect A:
 
@@ -481,7 +485,7 @@ any existing programs that use throw as the name for a user-defined PCD.
 Fortunately because throw is a Java keyword this particular change is
 very safe.
 
-==== Step 6. Extend the PCD parser to handle this new primitive PCD
+=== Step 6. Extend the PCD parser to handle this new primitive PCD
 
 Modify the parseSinglePointcut method in
 weaver/org.aspectj.weaver.patterns/PatternParser.java to add one more
@@ -526,7 +530,7 @@ Make sure that you see the 'about to throw' printed before moving on.
 This shows that the throw PCD is now successfully matching the throw
 join point shadow we added earlier.
 
-==== Step 7. Check that we're properly providing the single thrown argument (and clean-up the test)
+=== Step 7. Check that we're properly providing the single thrown argument (and clean-up the test)
 
 Now that we have a valid pcd for this advice, we can simplify our test
 case. Modify our test aspect A to be the following. In addition to
@@ -557,7 +561,7 @@ a new join point to the AspectJ language and a corresponding PCD to
 match it. This is a good time to take a break before moving on to part
 two.
 
-=== Part 2: Getting the signature of this new join point right
+== Part 2: Getting the signature of this new join point right
 
 We know that throw(catch(Throwable)) is not the right thing to be
 printing for the signature at this join point. What is the correct
@@ -601,7 +605,7 @@ allow dynamic matching in args to select more specific types. In
 general, good AspectJ code should use this dynamic matching anyway to
 correspond to good OO designs.
 
-==== Step 1. Change the signature of the throw pcd
+=== Step 1. Change the signature of the throw pcd
 
 Since we aren't going to recover the static type of the exception
 thrown, we need to fix the parser for the throw pcd to remove this
@@ -683,7 +687,7 @@ passing:
 PASS Suite.Spec(c:\aspectj\eclipse\tests) 1 tests (1 passed) 2 seconds
 ....
 
-==== Part 2. Make a real test case
+=== Part 2. Make a real test case
 
 The pass result from running our test should worry you. Unlike previous
 runs, this test run doesn't show the output from our System.out.println
@@ -734,7 +738,7 @@ we're not matching the throw join point anymore.
 FAIL Suite.Spec(c:\aspectj\eclipse\tests) 1 tests (1 failed) 1 seconds
 ....
 
-==== Step 3. Fix signature matching again
+=== Step 3. Fix signature matching again
 
 In org.aspectj.weaver.patterns.SignaturePattern.matches, we need to
 handle throw signature matching the same way we handle advice signature
@@ -777,7 +781,7 @@ Member.THROW. This problem only shows up when we try to print
 thisJoinPoint. It's showing that we haven't updated the reflection API
 to understand this new signature kind.
 
-==== Step 4. Extend org.aspectj.lang.reflect to understand throw signatures
+=== Step 4. Extend org.aspectj.lang.reflect to understand throw signatures
 
 We need to add a couple of classes to the reflection API to implement
 the throw signature. Because we decided at the beginning of this section
@@ -906,7 +910,7 @@ about to throw: 'java.lang.RuntimeException: expected exception' at throw(throw)
 PASS Suite.Spec(c:\aspectj\eclipse\tests) 1 tests (1 passed) 1 seconds
 ....
 
-==== Step 5. Extend the test for automated coverage of reflection
+=== Step 5. Extend the test for automated coverage of reflection
 
 Modify the before advice to include at least minimal checks of the new
 reflective information:
@@ -927,14 +931,14 @@ working version of the throw join point and there are no obvious pieces
 that we've skipped. Take a break before proceeding to the final phase of
 tests.
 
-=== Part 3: More serious testing
+== Part 3: More serious testing
 
 Now it's time to get a decent testing story. The test work that we will
 do here is probably too little for adding a new join point to the
 aspectj language; however, it should at least give you a sense of what's
 involved.
 
-==== Step 1. Run the test suite again
+=== Step 1. Run the test suite again
 
 Rerun the tests you ran at the beginning of part 1. Any failures that
 occur should be resolved at this point. At the time of writing this
@@ -972,7 +976,7 @@ noted in the release notes for any AspectJ release. Since we're not
 writing documentation in this tutorial, we will move on an fix the test
 case.
 
-==== Step 2. Fix the failing test case
+=== Step 2. Fix the failing test case
 
 Now we need to fix this failing test case. The first step is to copy the
 test specification into our local myTests.xml file. The easiest way to
@@ -1001,7 +1005,7 @@ new expected event between these two:
 
 Run the test suite again to see that this test now passes.
 
-==== Step 3. Extend test coverage to after advice
+=== Step 3. Extend test coverage to after advice
 
 There is a lot we should do now to extend test coverage for this new
 kind of join point. For the purpose of this tutorial, we're just going
@@ -1060,7 +1064,7 @@ property of the orthogonality of the implementation of join points and
 advice. We never had to do any implementation work to make our new join
 point kind work for before and all three kinds of after advice.
 
-==== Step 4. Look at around advice on throw join points
+=== Step 4. Look at around advice on throw join points
 
 Let's create a new test case to see how this new join point interacts
 with around advice.
@@ -1120,7 +1124,7 @@ best design. For the purpose of this tutorial we're once again going to
 make the language design choice that is easiest to implement and press
 on.
 
-==== Step 5. Prohibit around advice on this new join point kind
+=== Step 5. Prohibit around advice on this new join point kind
 
 The easiest solution to implement is to prohibit around advice on throw
 join points. There are already a number of these kinds of rules
@@ -1169,7 +1173,7 @@ following specification:
 
 Run myTests.xml one last time to see both tests passing.
 
-==== Step 6. Final preparations for a commit or patch
+=== Step 6. Final preparations for a commit or patch
 
 You probably want to stop here for the purposes of this tutorial. We've
 pointed out several language design decisions that would need to be
diff --git a/docs/developer/design-overview.adoc b/docs/developer/design-overview.adoc
index 06d00d83a..4edbd41b3 100644
--- a/docs/developer/design-overview.adoc
+++ b/docs/developer/design-overview.adoc
@@ -1,5 +1,6 @@
 = AspectJ Design Overview
 :doctype: book
+:leveloffset: +1
 
 Here are some sobering words:
 
diff --git a/docs/developer/index.adoc b/docs/developer/index.adoc
index a358948b3..88b638e0b 100644
--- a/docs/developer/index.adoc
+++ b/docs/developer/index.adoc
@@ -1,5 +1,6 @@
 = AspectJ Design Overview
 :doctype: book
+:leveloffset: +1
 
 Here are some sobering words:
 
diff --git a/docs/developer/language.adoc b/docs/developer/language.adoc
index 28a3f7548..45ee827ad 100644
--- a/docs/developer/language.adoc
+++ b/docs/developer/language.adoc
@@ -1,6 +1,6 @@
-== AspectJ Language Design
+= AspectJ Language Design
 
-=== User-suggested New Language Features
+== User-suggested New Language Features
 
 * `-` wildcard
 ** https://dev.eclipse.org/mhonarc/lists/aspectj-dev/msg00717.html
@@ -13,9 +13,9 @@
 ** https://dev.eclipse.org/mhonarc/lists/aspectj-dev/msg00458.html
 ** https://dev.eclipse.org/mhonarc/lists/aspectj-dev/msg00467.html +
 
-=== Key Language Design Properties
+== Key Language Design Properties
 
-==== Orthogonal join point model
+=== Orthogonal join point model
 
 The different kinds of join
 points, the different primitive pointcuts, and the different kinds of
@@ -25,7 +25,7 @@ This was one of the hardest parts of the design to get right, because of
 the "constructor must call super" rule in Java. But we finally got this
 in 1.0.
 
-==== Pointcuts support composition and abstraction
+=== Pointcuts support composition and abstraction
 
 Abelson and Sussman
 say that composition and abstraction are the key elements of a real
@@ -45,18 +45,18 @@ pointcut topLevelStateChange(): stateChange() && !cflowbelow(stateChange());
 is what makes it possible for people to really work with crosscutting
 structure and make their code more clear.
 
-==== Statically type checked
+=== Statically type checked
 
 The efficiency, code quality and programmer
 productivity arguments for this have been made elsewhere, so I won't
 repeat them.
 
-==== Efficient
+=== Efficient
 
 AspectJ code is as fast as the equivalent functionality,
 written by hand, in a scattered and tangled way.
 
-==== Simple kernel
+=== Simple kernel
 
 I've heard some people say that AspectJ is too big
 and too complex. In the most important sense of simple AspectJ is
@@ -69,7 +69,7 @@ the right idea for a standard AOP API
 is this kernel, packaged in a way that allows building more
 sophisticated tools on top of it.
 
-==== Supports multiple weave times
+=== Supports multiple weave times
 
 AspectJ is neutral on whether weaving
 happens at pre-process, compile, post-process, load, JIT or runtime.
diff --git a/docs/developer/modules.adoc b/docs/developer/modules.adoc
index 74292212b..2cb60910f 100644
--- a/docs/developer/modules.adoc
+++ b/docs/developer/modules.adoc
@@ -1,10 +1,10 @@
-== AspectJ Modules
+= AspectJ Modules
 
 There are a number of different structures [Parnas]: "the module structure, the uses structure, the runtime structure,
 ..." This document overviews module structure and summarizes what is hidden by each. For detailed documentation refer to
 the individual module sources and docs available via CVS.
 
-=== Core Modules
+== Core Modules
 
 *CVS Location:* dev.eclipse.org:/cvsroot/technology/org.aspectj/modules
 
@@ -50,7 +50,7 @@ bytecode toolkit. All advice planning and weaving is done here. Takes an aspect
 classfiles as input.
 |===
 
-=== Supporting Modules
+== Supporting Modules
 
 *CVS Location:* dev.eclipse.org:/cvsroot/technology/org.aspectj/modules
 
@@ -66,7 +66,7 @@ classfiles as input.
 | tests | AspectJ test suite, including all language tests, regression tests, and test system sources
 |===
 
-=== Eclipse AspectJ Development Tools (AJDT)
+== Eclipse AspectJ Development Tools (AJDT)
 
 *CVS Location:* dev.eclipse.org:/cvsroot/technology/org.eclipse.ajdt/plugins/org.eclipse.ajdt
 
diff --git a/docs/devguide/aj.adoc b/docs/devguide/aj.adoc
index 0a7b53108..2aa2c2c6e 100644
--- a/docs/devguide/aj.adoc
+++ b/docs/devguide/aj.adoc
@@ -1,16 +1,16 @@
-== `aj`, the AspectJ load-time weaving launcher
+= `aj`, the AspectJ load-time weaving launcher
 
-=== Name
+== Name
 
 `aj` - command-line launcher for basic load-time weaving
 
-=== Synopsis
+== Synopsis
 
 [subs=+quotes]
 aj [_Options_] [_arg_...]
 
 [[aj]]
-=== Description
+== Description
 
 The `aj` command runs Java programs in Java 1.4 or later by setting up
 `WeavingURLClassLoader` as the system class loader, to do load-time
@@ -23,7 +23,7 @@ Users should define the environment variables `CLASSPATH` and
 For more information and alternatives for load-time weaving, see
 xref:ltw.adoc#ltw[Load-Time Weaving].
 
-=== Examples
+== Examples
 
 Use ajc to build a library, then weave at load time
 
diff --git a/docs/devguide/ajc.adoc b/docs/devguide/ajc.adoc
index 7fbc4053a..51091ee1e 100644
--- a/docs/devguide/ajc.adoc
+++ b/docs/devguide/ajc.adoc
@@ -1,16 +1,16 @@
 [[ajc]]
-== `ajc`, the AspectJ compiler/weaver
+= `ajc`, the AspectJ compiler/weaver
 
-=== Name
+== Name
 
 `ajc` - compiler and bytecode weaver for the AspectJ and Java languages
 
-=== Synopsis
+== Synopsis
 
 [subs=+quotes]
  ajc [_option_...] [_file_... | @_file_... | -argfile _file_...]
 
-=== Description
+== Description
 
 The `ajc` command compiles and weaves AspectJ and Java source and .class
 files, producing .class files compliant with any Java VM (1.1 or later).
@@ -28,7 +28,7 @@ include the source not only for the aspects or pointcuts but also for
 any affected types. Specifying all sources is necessary because, unlike
 javac, ajc does not search the sourcepath for classes. (For a discussion
 of what affected types might be required, see
-xref:../progguide/implementation.html[The AspectJ Programming Guide,
+xref:../progguide/implementation.adoc[The AspectJ Programming Guide,
 Implementation Appendix].)
 
 To specify sources, you can list source files as arguments or use the
@@ -38,7 +38,7 @@ which source is correct. (This happens most often when users include the
 destination directory on the inpath and rebuild.)
 
 [[ajc_options]]
-==== Options
+=== Options
 
 `-injars <JarList>`::
   deprecated: since 1.2, use -inpath, which also takes directories.
@@ -91,7 +91,7 @@ destination directory on the inpath and rebuild.)
   Generate .ajesym symbol files for emacs support (deprecated).
 `-Xlint`::
   Same as -Xlint:warning (enabled by default)
-`-Xlint:{level}`::
+`-Xlint:\{level}`::
   Set default level for messages about potential programming mistakes in
   crosscutting code. \{level} may be ignore, warning, or error. This
   overrides entries in org/aspectj/weaver/XlintDefault.properties from
@@ -227,7 +227,7 @@ none                   suppress all compiler warnings
   (Experimental) Allows code to be generated that targets a 1.2 or a 1.5
   level AspectJ runtime (default 1.5)
 
-==== File names
+=== File names
 
 ajc accepts source files with either the `.java` extension or the `.aj`
 extension. We normally use `.java` for all of our files in an AspectJ
@@ -247,7 +247,7 @@ can create an artificial need for privileged aspects. Instead of adding
 a sub-package like `aspects` we recommend using the `.aj` extension and
 including these files in your existing packages instead.
 
-==== Compatibility
+=== Compatibility
 
 AspectJ is a compatible extension to the Java programming language. The
 AspectJ compiler adheres to the
@@ -259,7 +259,7 @@ platform. The code it generates runs on any Java 1.1 or later compatible
 platform. For more information on compatibility with Java and with
 previous releases of AspectJ, see xref:compatibility.adoc#versionCompatibility[Version Compatibility].
 
-==== Examples
+=== Examples
 
 Compile two files:
 
@@ -413,7 +413,7 @@ Run the application without tracing:
 java -classpath "app.jar" tracing.ExampleMain
 ....
 
-==== The AspectJ compiler API
+=== The AspectJ compiler API
 
 The AspectJ compiler is implemented completely in Java and can be called
 as a Java class. The only interface that should be considered public are
@@ -449,7 +449,7 @@ public class WrapAjc {
 }
 ....
 
-==== Stack Traces and the SourceFile attribute
+=== Stack Traces and the SourceFile attribute
 
 Unlike traditional java compilers, the AspectJ compiler may in certain
 cases generate classfiles from multiple source files. Unfortunately, the
diff --git a/docs/devguide/ajdoc.adoc b/docs/devguide/ajdoc.adoc
index 6bea2ff16..eaa0ee1b5 100644
--- a/docs/devguide/ajdoc.adoc
+++ b/docs/devguide/ajdoc.adoc
@@ -1,15 +1,15 @@
-== `ajdoc`, the AspectJ API documentation generator
+= `ajdoc`, the AspectJ API documentation generator
 
-=== Name
+== Name
 
 `ajdoc` - generate HTML API documentation, including crosscutting structure
 
-=== Synopsis
+== Synopsis
 
 [subs=+quotes]
  ajdoc [ -bootclasspath _classpathlist_ ] [ -classpath _classpathlist_ ] [-d _path_] [-help] [-package] [-protected] [-private] [-public] [-overview _overviewFile_] [ -sourcepath _sourcepathlist_ ] [-verbose] [-version] [_sourcefiles_... | _packages_... | @_file_... | -argfile _file_...] [ _ajc options_ ]
 
-=== Description
+== Description
 
 `ajdoc` renders HTML documentation for AspectJ constructs as well as the
 Java constructs that `javadoc` renders. In addition `ajdoc` displays the
@@ -51,7 +51,7 @@ classpath. Normally the scripts set this up, assuming that your
 may need to provide this jar when using a different version of Java or a
 JRE.
 
-=== Examples
+== Examples
 
 * Change into the `examples` directory.
 * Type `mkdir doc` to create the destination directory for the documentation.
diff --git a/docs/devguide/antsupport.adoc b/docs/devguide/antsupport.adoc
index 6c8217930..9a13b56ab 100644
--- a/docs/devguide/antsupport.adoc
+++ b/docs/devguide/antsupport.adoc
@@ -1,8 +1,8 @@
 [[antTasks]]
-== AspectJ Ant Tasks
+= AspectJ Ant Tasks
 
 [[antTasks-intro]]
-=== Introduction
+== Introduction
 
 AspectJ contains a compiler, `ajc`, that can be run from Ant. Included
 in the `aspectjtools.jar` are Ant binaries to support three ways of
@@ -22,7 +22,7 @@ This describes how to install and use the tasks and the adapter. For an
 example Ant script, see xref:../examples/build.xml[examples/build.xml].
 
 [[antTasks-install]]
-=== Installing Ant Tasks
+== Installing Ant Tasks
 
 Install Jakarta Ant 1.5.1: Please see the official Jakarta Ant website
 for more information and the 1.5.1 distribution. This release is
@@ -34,7 +34,7 @@ v 2.0 at https://eclipse.org/aspectj.
 In Ant 1.5, third-party tasks can be declared using a taskdef entry in
 the build script, to identify the name and classes. When declaring a
 task, include the `aspectjtools.jar` either in the taskdef classpath or
-in `${ANT_HOME}/lib` where it will be added to the system class path by
+in `$\{ANT_HOME}/lib` where it will be added to the system class path by
 the ant script. You may specify the task script names directly, or use
 the "resource" attribute to specify the default names:
 
@@ -49,7 +49,7 @@ uses "iajc" for the AspectJ post-1.1 task.
 In Ant 1.6, third-party tasks are declared in their own namespace using
 `antlib.xml`. For example, the following script would build and run the
 spacewar example, if you put the script in the examples directory and
-`aspectjtools.jar` in the `${ANT_HOME}/lib` directory.
+`aspectjtools.jar` in the `$\{ANT_HOME}/lib` directory.
 
 [source, xml]
 ....
@@ -71,7 +71,7 @@ For more information on using Ant, please refer to Jakarta's
 documentation on integrating user-defined Ant tasks into builds.
 
 [[antTasks-iajc]]
-=== AjcTask (iajc)
+== AjcTask (iajc)
 
 This task uses the AspectJ post-1.1 compiler ajc. The AspectJ compiler
 can be used like Javac to compile Java sources, but it can also compile
@@ -91,7 +91,7 @@ directory.
 This task is named iajc to avoid conflict with the 1.0 task ajc.
 
 [[antTasks-iajc-options]]
-==== AjcTask (iajc) Options
+=== AjcTask (iajc) Options
 
 The following tables list the supported parameters. For any parameter
 specified as a Path, a single path can be specified directly as an
@@ -325,7 +325,7 @@ depends on compliance mode.
 |===
 
 [[antTasks-nested-includes]]
-==== AjcTask matching parameters specified as nested elements
+=== AjcTask matching parameters specified as nested elements
 
 This task forms an implicit FileSet and supports all attributes of
 `fileset` (dir becomes srcdir) as well as the nested `include`,
@@ -335,7 +335,7 @@ source directories unless using filters to exclude some files from
 compilation.
 
 [[antTasks-iajc-paths]]
-==== AjcTask Path-like Structures
+=== AjcTask Path-like Structures
 
 Some parameters are path-like structures containing one or more
 elements; these are `sourceroots`, `argfiles`, `injars`, `inpath`,
@@ -370,7 +370,7 @@ specified using the refid attribute:
 </iajc>
 ....
 
-The task also supports an attribute `{name}ref` for each such parameter.
+The task also supports an attribute `\{name}ref` for each such parameter.
 E.g., for `aspectpath`:
 
 [source, xml]
@@ -379,7 +379,7 @@ E.g., for `aspectpath`:
 ....
 
 [[antTasks-iajc-sample]]
-==== Sample of iajc task
+=== Sample of iajc task
 
 A minimal build script defines the task and runs it, specifying the
 sources:
@@ -452,7 +452,7 @@ has quit, then this runs the application.
 For an example of a build script, see ../examples/build.xml.
 
 [[antTasks-iajc-uptodate]]
-==== Avoiding clean compiles
+=== Avoiding clean compiles
 
 Unlike javac, the ajc compiler always processes all input because new
 aspects can apply to updated classes and vice-versa. However, in the
@@ -479,7 +479,7 @@ When using this technique, be careful to verify that binary input jars
 are themselves up-to-date after they would have been modified by any
 build commands.
 
-==== Programmatically handling compiler messages
+=== Programmatically handling compiler messages
 
 Users may specify a message holder to which the compiler will pass all
 messages as they are generated. This will override all of the normal
@@ -495,7 +495,7 @@ AspectJ testing module (which is not included in the binary
 distribution).
 
 [[antTasks-adapter]]
-=== Ajc11CompilerAdapter (javac)
+== Ajc11CompilerAdapter (javac)
 
 This CompilerAdapter can be used in javac task calls by setting the
 `build.compiler` property. This enables users to to easily switch
@@ -507,10 +507,10 @@ possible for any given compile job to restate the Javac task in a way
 that can be handled by iajc/ajc.
 
 [[antTasks-adapter-sample]]
-==== Sample of compiler adapter
+=== Sample of compiler adapter
 
 To build using the adapter, put the `aspectjtools.jar` on the system/ant
-classpath (e.g., in `${ANT_HOME}/lib`) and define the `build.compiler`
+classpath (e.g., in `$\{ANT_HOME}/lib`) and define the `build.compiler`
 property as the fully-qualified name of the class,
 `org.aspectj.tools.ant.taskdefs.Ajc11CompilerAdapter`.
 
@@ -565,7 +565,7 @@ that source root (without exception or filtering).) To replace source
 dir searching in Javac, use an Ant filter to specify the source files.
 
 [[antTasks-adapter-options]]
-==== Compiler adapter compilerarg options
+=== Compiler adapter compilerarg options
 
 The adapter supports any ajc command-line option passed using
 compilerarg, as well as the following options available only in AjcTask.
@@ -580,10 +580,10 @@ in javac).
 as the message holder.
 * `-Xcopyinjars`: copy resources from any input jars to output (default
 behavior since 1.1.1)
-* `-Xsourcerootcopyfilter {filter}`: copy resources from source
+* `-Xsourcerootcopyfilter \{filter}`: copy resources from source
 directories to output (minus files specified in filter)
-* `-Xtagfile {file}`: use file to control incremental compilation
-* `-Xsrcdir {dir}`: add to list of ajc source roots (all source files
+* `-Xtagfile \{file}`: use file to control incremental compilation
+* `-Xsrcdir \{dir}`: add to list of ajc source roots (all source files
 will be included).
 
 Special considerations when using Javac and compilerarg:
@@ -630,7 +630,7 @@ to the destination directory.
 compile.
 
 [[antTasks-ajc]]
-=== Ajc10 (ajc)
+== Ajc10 (ajc)
 
 This task handles the same arguments as those used by the AspectJ 1.0
 task. This should permit those with existing build scripts using the Ajc
@@ -642,7 +642,7 @@ AspectJ 1.1 only should upgrade their scripts to use AjcTask instead.
 This will not work for AspectJ 1.2 or later.)
 
 [[antTasks-ajc-options]]
-==== Ajc10 (ajc) Options
+=== Ajc10 (ajc) Options
 
 Most attributes and nested elements are optional. The compiler requires
 that the same version of `aspectjrt.jar` be specified on the classpath,
@@ -733,9 +733,9 @@ line-delimited list of source file paths (absolute or relative to the
 argfile).
 |===
 
-===== argfiles - argument list files
+==== argfiles - argument list files
 
-An argument file is a file (usually `{file}.lst`) containing a list of
+An argument file is a file (usually `\{file}.lst`) containing a list of
 source file paths (absolute or relative to the argfile). You can use it
 to specify all source files to be compiled, which ajc requires to avoid
 searching every possible source file in the source path when building
@@ -750,7 +750,7 @@ IDE support for such files varies, and Javac does not support them. Be
 sure to include exactly one argument on each line.
 
 [[antTasks-ajc-nested]]
-==== Ajc10 parameters specified as nested elements
+=== Ajc10 parameters specified as nested elements
 
 This task forms an implicit FileSet and supports all attributes of
 `fileset` (dir becomes srcdir) as well as the nested `include`,
@@ -763,7 +763,7 @@ attributes are path-like structures and can also be set via nested
 elements, respectively.
 
 [[antTasks-ajc-sample]]
-==== Sample of ajc task
+=== Sample of ajc task
 
 Following is a declaration for the ajc task and a sample invocation that
 uses the ajc compiler to compile the files listed in `default.lst` into
@@ -818,15 +818,15 @@ This next example
 />
 ....
 
-compiles .java files under the `${src}` directory in the spacewar and
-coordination packages, and stores the .class files in the `${build}`
+compiles .java files under the `$\{src}` directory in the spacewar and
+coordination packages, and stores the .class files in the `$\{build}`
 directory. All source files under spacewar/ and coordination/ are used,
 except Debug.java.
 
 See ../examples/build.xml for an example build script.
 
 [[antTasks-problems]]
-=== Isolating problems running the Ant tasks
+== Isolating problems running the Ant tasks
 
 If you have problems with the tasks not solved by the documentation,
 please try to see if you have the same problems when running ajc
@@ -842,7 +842,7 @@ building from Ant, then please send a report (including your build file,
 if possible).
 
 [[antTasks-knownProblems]]
-==== Known issues with the Ant tasks
+=== Known issues with the Ant tasks
 
 For the most up-to-date information on known problems, see the
 https://bugs.eclipse.org/bugs[bug database] for unresolved
@@ -869,7 +869,7 @@ Ant (see the Ant documentation, searching for ANT_OPTS, the variable
 they use in their scripts to pass VM options, e.g., ANT_OPTS=-Xmx128m).
 
 [[antTasks-feedback]]
-==== Ant task questions and bugs
+=== Ant task questions and bugs
 
 For questions, you can send email to aspectj-users@dev.eclipse.org. (Do
 join the list to participate!) We also welcome any bug reports, patches,
diff --git a/docs/devguide/compatibility.adoc b/docs/devguide/compatibility.adoc
index 63822e003..ea96ebf3c 100644
--- a/docs/devguide/compatibility.adoc
+++ b/docs/devguide/compatibility.adoc
@@ -1,8 +1,8 @@
 [[compatibility]]
-== AspectJ version compatibility
+= AspectJ version compatibility
 
 [[versionCompatibility]]
-=== Version Compatibility
+== Version Compatibility
 
 Systems, code, and build tools change over time, often not in step.
 Generally, later versions of the build tools understand earlier versions
@@ -10,7 +10,7 @@ of the code, but systems should include versions of the runtime used to
 build the AspectJ program.
 
 [[javaCompatibility]]
-==== Java compatibility
+=== Java compatibility
 
 AspectJ programs can run on any Java VM of the required version. The
 AspectJ tools produce Java bytecode .class files that run on Java
@@ -35,7 +35,7 @@ require a more recent version of Java. You might use Java 5 to run the
 AspectJ compiler to produce code for Java 1.1.8.
 
 [[runtimeCompatibility]]
-==== Runtime library compatibility
+=== Runtime library compatibility
 
 When deploying AspectJ programs, include on the classpath the classes,
 aspects, and the AspectJ runtime library (`aspectjrt.jar`). Use the
@@ -59,7 +59,7 @@ aspect. To find out if the runtime you deployed is the one actually
 being used, log the defining class loader for the aspects and runtime.
 
 [[binaryCompatibility]]
-==== Aspect binary compatibility
+=== Aspect binary compatibility
 
 Generally, binary aspects can be read by later versions of the weaver if
 the aspects were built by version 1.2.1 or later. (Some future weavers
@@ -76,7 +76,7 @@ weaver, be careful to rebuild and redeploy with the next released
 version.
 
 [[sourceCompatibility]]
-==== Aspect source compatibility
+=== Aspect source compatibility
 
 Generally, AspectJ source files can be read by later versions of the
 compiler. Language features do not change in dot releases (e.g., from
@@ -91,7 +91,7 @@ xref:../progguide/semantics.html[Semantics appendix to the Programming
 Guide].
 
 [[upgrading]]
-==== Problems when upgrading to new AspectJ versions
+=== Problems when upgrading to new AspectJ versions
 
 Let's say your program behaves differently after being built with a new
 version of the AspectJ tools. It could be a bug that was introduced by
diff --git a/docs/devguide/devguide.adoc b/docs/devguide/devguide.adoc
index 6d8065baf..6f019d43a 100644
--- a/docs/devguide/devguide.adoc
+++ b/docs/devguide/devguide.adoc
@@ -1,6 +1,6 @@
 = The AspectJ^TM^ Development Environment Guide
-
 :doctype: book
+:leveloffset: +1
 
 _by the AspectJ Team_
 
@@ -8,7 +8,7 @@ _Copyright (c) 1998-2001 Xerox Corporation, 2002 Palo Alto Research Center, Inco
 All rights reserved._
 
 This guide describes how to build and deploy AspectJ programs using the AspectJ tools and facilities. See also the
-xref:../progguide/progguide.adoc[AspectJ Programming Guide], the documentation available with the AspectJ support
+xref:../progguide/index.adoc[AspectJ Programming Guide], the documentation available with the AspectJ support
 available for various integrated development environments (e.g. https://www.eclipse.org/ajdt/[Eclipse AJDT]), and the
 most-recent documentation available from the https://eclipse.org/aspectj[AspectJ project page].
 
diff --git a/docs/devguide/index.adoc b/docs/devguide/index.adoc
index ea6288ae1..115595ec7 100644
--- a/docs/devguide/index.adoc
+++ b/docs/devguide/index.adoc
@@ -1,6 +1,6 @@
 = The AspectJ^TM^ Development Environment Guide
-
 :doctype: book
+:leveloffset: +1
 
 _by the AspectJ Team_
 
@@ -8,7 +8,7 @@ _Copyright (c) 1998-2001 Xerox Corporation, 2002 Palo Alto Research Center, Inco
 All rights reserved._
 
 This guide describes how to build and deploy AspectJ programs using the AspectJ tools and facilities. See also the
-xref:../progguide/progguide.adoc[AspectJ Programming Guide], the documentation available with the AspectJ support
+xref:../progguide/index.adoc[AspectJ Programming Guide], the documentation available with the AspectJ support
 available for various integrated development environments (e.g. https://www.eclipse.org/ajdt/[Eclipse AJDT]), and the
 most-recent documentation available from the https://eclipse.org/aspectj[AspectJ project page].
 
diff --git a/docs/devguide/ltw.adoc b/docs/devguide/ltw.adoc
index 5966ba993..1d1831c92 100644
--- a/docs/devguide/ltw.adoc
+++ b/docs/devguide/ltw.adoc
@@ -1,8 +1,8 @@
 [[ltw]]
-== Load-Time Weaving
+= Load-Time Weaving
 
 [[ltw-introduction]]
-=== Introduction
+== Introduction
 
 The AspectJ weaver takes class files as input and produces class files
 as output. The weaving process itself can take place at one of three
@@ -35,7 +35,7 @@ reloading those classes). AspectJ 5 does not provide explicit support
 for run-time weaving although simple coding patterns can support
 dynamically enabling and disabling advice in aspects.
 
-==== Weaving class files more than once
+=== Weaving class files more than once
 
 As of AspectJ 5 aspects (code style or annotation style) and woven
 classes are reweavable by default. If you are developing AspectJ
@@ -46,7 +46,7 @@ additional state in the class files that is used to support subsequent
 reweaving.
 
 [[ltw-rules]]
-=== Load-time Weaving Requirements
+== Load-time Weaving Requirements
 
 All load-time weaving is done in the context of a class loader, and
 hence the set of aspects used for weaving and the types that can be
@@ -67,7 +67,7 @@ may be extended.
 weave classes loaded by a delegate or parent class loader.
 
 [[ltw-configuration]]
-=== Configuration
+== Configuration
 
 New in AspectJ 5 are a number of mechanisms to make load-time weaving
 easy to use. The load-time weaving mechanism is chosen through JVM
@@ -75,7 +75,7 @@ startup options. Configuration files determine the set of aspects to be
 used for weaving and which types will be woven. Additional diagnostic
 options allow the user to debug the configuration and weaving process.
 
-==== Enabling Load-time Weaving
+=== Enabling Load-time Weaving
 
 AspectJ 5 supports several ways of enabling load-time weaving for an
 application: agents, a command-line launch script, and a set of
@@ -116,7 +116,7 @@ documentation and source for `WeavingURLClassLoader` and
 `WeavingAdapter`.
 
 [[configuring-load-time-weaving-with-aopxml-files]]
-==== Configuring Load-time Weaving with aop.xml files
+=== Configuring Load-time Weaving with aop.xml files
 
 The weaver is configured using one or more `META-INF/aop.xml` files
 located on the class loader search path. Each file may declare a list of
@@ -255,7 +255,7 @@ option a JAR is produced that can be used with the `aj5` command or a
 load-time weaving environment.
 
 [[concrete-aspect]]
-==== Using Concrete Aspects
+=== Using Concrete Aspects
 
 It is possible to make an abstract aspect concrete by means of the
 `META-INF/aop.xml` file. This is useful way to implement abstract
@@ -355,7 +355,7 @@ AbstractAspect concreteInstance = Aspects.aspectOf(myConcreteAspectClass);
 ....
 
 [[concrete-aspect-precedence]]
-==== Using Concrete Aspects to define precedence
+=== Using Concrete Aspects to define precedence
 
 As described in the previous section, the `concrete-aspect` element in
 `META-INF/aop.xml` gives the option to declare the precedence, just as
@@ -382,7 +382,7 @@ qualified class name that will be then reserved for this concrete-aspect
 and must not conflict with other classes you deploy.
 
 [[weaver-options]]
-==== Weaver Options
+=== Weaver Options
 
 The table below lists the AspectJ options supported by LTW. All other
 options will be ignored and a warning issued.
@@ -429,7 +429,7 @@ declared to the same weaver.
 |===
 
 [[ltw-specialcases]]
-=== Special cases
+== Special cases
 
 The following classes are not exposed to the LTW infrastructure
 regardless of the `aop.xml` file(s) used:
@@ -453,7 +453,7 @@ The `adviceDidNotMatch` won't be handled as a warn (as during compile
 time) but as an info message.
 
 [[ltw-packaging]]
-=== Runtime Requirements for Load-time Weaving
+== Runtime Requirements for Load-time Weaving
 
 To use LTW the `aspectjweaver.jar` library must be added to the
 classpath. This contains the AspectJ 5 runtime, weaver, weaving class
@@ -461,9 +461,9 @@ loader and weaving agents. It also contains the DTD for parsing XML
 weaving configuration files.
 
 [[ltw-agents]]
-=== Supported Agents
+== Supported Agents
 
-==== JVMTI
+=== JVMTI
 
 When using Java 5 the JVMTI agent can be used by starting the JVM with
 the following option (adapt according to the path to aspectjweaver.jar):
@@ -474,7 +474,7 @@ the following option (adapt according to the path to aspectjweaver.jar):
 ....
 
 [[jrockit]]
-==== JRockit with Java 1.3/1.4 (use JVMTI on Java 5)
+=== JRockit with Java 1.3/1.4 (use JVMTI on Java 5)
 
 Since AspectJ 1.9.7, the obsolete Oracle/BEA JRockit agent is no longer
 part of AspectJ. JRockit JDK never supported Java versions higher than
diff --git a/docs/devguide/tools-intro.adoc b/docs/devguide/tools-intro.adoc
index 7673d3fc5..c9bd34ea5 100644
--- a/docs/devguide/tools-intro.adoc
+++ b/docs/devguide/tools-intro.adoc
@@ -1,8 +1,8 @@
 [[tools-intro]]
-== Introduction to the AspectJ tools
+= Introduction to the AspectJ tools
 
 [[eclipse-aspectj]]
-=== The Eclipse AspectJ implementation
+== The Eclipse AspectJ implementation
 
 The xref:../progguide/index.html[AspectJ Programming Guide] describes
 the AspectJ language. This guide describes the AspectJ tools produced by
@@ -41,7 +41,7 @@ text below introduces an implementation detail, it will warn if users
 make mistakes by applying it in lieu of the language semantics.
 
 [[bytecode-concepts]]
-=== Bytecode weaving, incremental compilation, and memory usage
+== Bytecode weaving, incremental compilation, and memory usage
 
 Bytecode weaving takes classes and aspects in .class form and weaves
 them together to produce binary-compatible .class files that run in any
@@ -74,7 +74,7 @@ require more memory and more time to recompile than the corresponding
 AspectJ program.)
 
 [[classpathInpathAndAspectpath]]
-==== Classpath, inpath, and aspectpath
+=== Classpath, inpath, and aspectpath
 
 AspectJ introduces two new paths for the binary input to the weaver
 which you'll find referenced in xref:ajc.adoc[`ajc`, the AspectJ compiler/weaver],
diff --git a/docs/examples/spacewar/README.adoc b/docs/examples/spacewar/README.adoc
index 9991867a3..d39b9b5fc 100644
--- a/docs/examples/spacewar/README.adoc
+++ b/docs/examples/spacewar/README.adoc
@@ -1,5 +1,5 @@
 [[_5]]
-== Exploring the Spacewar Example
+= Exploring the Spacewar Example
 
 _© Copyright 1997-2001 Xerox Corporation. All rights reserved._
 
@@ -19,13 +19,13 @@ the helloworld example first by following the instructions in
 xref:../doc/primer/default.html[Primer] section Getting Started.
 
 [[_5_1]]
-=== Compiling Spacewar
+== Compiling Spacewar
 
 * Change to the `examples` directory.
 * Type `ajc -argfile spacewar/demo.lst` to compile the system.
 
 [[_5_2]]
-=== Running Spacewar
+== Running Spacewar
 
 * In the examples directory, type `java spacewar.Game`
 
@@ -42,7 +42,7 @@ focus so that your keystrokes are recognized.
 You can quit the game with ctl-Q.
 
 [[_5_3]]
-=== Exploring the Code
+== Exploring the Code
 
 There is one other built-in configurations for the Spacewar game. Try it
 by typing `ajc @spacewar\debug.lst`. This compiles in an elaborate
diff --git a/docs/faq/faq.adoc b/docs/faq/faq.adoc
index a5a76e804..f52d9d5ed 100644
--- a/docs/faq/faq.adoc
+++ b/docs/faq/faq.adoc
@@ -2267,7 +2267,7 @@ bug. See #q:bugreports[Q:How do I submit a bug report?].
 specifying the defining signature. Since all overriding methods share
 this signature, the advice runs for each method executed. (This happens,
 e.g., when one method invokes the same method in the superclass using
-`super.{method}(..)`). This is the correct behavior.
+`super.\{method}(..)`). This is the correct behavior.
 
 To avoid this, use the `call(..)` pointcut designator, or use
 `!cflow(..)` to pick out only the initial method-execution.
@@ -2467,7 +2467,7 @@ Aspect instances will be garbage collected just like regular objects
 after there are no more strong references to them. For the default
 aspect instantiation model, `issingleton`, the aspect class retains a
 reference to the singleton instance, in order to implement
-`static {AspectClass} aspectOf()`, so singleton instances will not be
+`static \{AspectClass} aspectOf()`, so singleton instances will not be
 garbage collected until the class is. For long-running or
 memory-critical programs, consider using weak references in singleton
 aspects for state that should be garbage collected.
@@ -2586,8 +2586,8 @@ JBuilder, and NetBeans through a common API, AJDE.
 *Q:* What are the new features of AspectJ 5?
 
 *A:* All the new features are documented in the
-xref:../adk15notebook/adk15notebook.adoc[AspectJ 5 Developer's Notebook] and the
-link:devguide/index.html[AspectJ Development Environment Guide]. To
+xref:../adk15notebook/index.adoc[AspectJ 5 Developer's Notebook] and the
+xref:../devguide/index.adoc[AspectJ Development Environment Guide]. To
 summarize:
 
 * Java 5 support: as an extension to Java, AspectJ supports all the new
diff --git a/docs/index.adoc b/docs/index.adoc
index 4daa8ee0a..32a8d2001 100644
--- a/docs/index.adoc
+++ b/docs/index.adoc
@@ -1,5 +1,5 @@
 [[top]]
-== AspectJ Documentation and Resources
+= AspectJ Documentation and Resources
 
 AspectJ^TM^ is a seamless aspect-oriented extension to Java^TM^. The compiler and development tools are available under
 an open-source license, require Java 8 to run, and produce code that runs in JDK 1.3 and later VM's. For the latest
@@ -27,7 +27,7 @@ mailto:aspectj-users@eclipse.org[users] and mailto:aspectj-dev@eclipse.org[devel
 |===
 
 [[documentation]]
-=== AspectJ documentation
+== AspectJ documentation
 
 [width="100%",cols="50%,50%",options="header",]
 |===
@@ -144,7 +144,7 @@ a|AspectJ Design Overview
 
 [[distributions]]
 
-=== AspectJ distributions
+== AspectJ distributions
 
 [cols=",",options="header",]
 |===
@@ -167,7 +167,7 @@ eclipse.org project site https://eclipse.org/ajdt
 
 [[resources]]
 
-=== Other AspectJ resources
+== Other AspectJ resources
 
 [cols=",",options="header",]
 |===
@@ -193,7 +193,7 @@ See the xref:faq/faq.adoc#ajcbugs[FAQ entry] for instructions on submitting comp
 |===
 
 [[paths]]
-=== Suggested learning paths for those new to AspectJ
+== Suggested learning paths for those new to AspectJ
 
 To learn the AspectJ language, read the xref:progguide/index.adoc[Programming Guide], keeping the
 xref:progguide/semantics.adoc[Semantics appendix] nearby as the best reference for AspectJ usage. Focus initially on the
diff --git a/docs/pdguide/ajcore.adoc b/docs/pdguide/ajcore.adoc
index 5928d372d..39b727286 100644
--- a/docs/pdguide/ajcore.adoc
+++ b/docs/pdguide/ajcore.adoc
@@ -1,8 +1,8 @@
 [[ajcore]]
-== AspectJ Core Files
+= AspectJ Core Files
 
 [[ajcore-introduction]]
-=== Introduction
+== Introduction
 
 When the compiler terminates abnormally, either because a particular
 kind of message was issued or an exception was thrown, an AspectJ core
@@ -15,7 +15,7 @@ version. When submitting a bug, include this file whenever it is
 available.
 
 [[configuration]]
-==== Configuring dump files
+=== Configuring dump files
 
 By default AspectJ will only create an `ajcore` file when an unexpected
 exception is thrown by the weaver or an `abort` message is issued.
@@ -37,7 +37,7 @@ files.
 |===
 
 [[ajcore-examples]]
-==== AJCore File Examples
+=== AJCore File Examples
 
 Below is an extract from an `ajcore` file. You will see details of the
 dump configuration as well as the exception (with stack trace) that is
diff --git a/docs/pdguide/index.adoc b/docs/pdguide/index.adoc
index 79940f9ff..5b2dc916a 100644
--- a/docs/pdguide/index.adoc
+++ b/docs/pdguide/index.adoc
@@ -1,6 +1,6 @@
 = The AspectJ^TM^ Problem Diagnosis Guide
-
 :doctype: book
+:leveloffset: +1
 
 _by the AspectJ Team_
 
diff --git a/docs/pdguide/ltwdump.adoc b/docs/pdguide/ltwdump.adoc
index 8442a36a3..fa5ea4794 100644
--- a/docs/pdguide/ltwdump.adoc
+++ b/docs/pdguide/ltwdump.adoc
@@ -1,8 +1,8 @@
 [[ltwdump]]
-== Dumping classes during load-time weaving
+= Dumping classes during load-time weaving
 
 [[ltwdump-introduction]]
-=== Introduction
+== Introduction
 
 Very rarely problems may be encountered with classes that have been
 load-time woven. Symptoms will include incorrect program function or a
@@ -16,15 +16,15 @@ proxy or has already been instrumented by another agent) you can
 configure the weaver to dump the input classes as well.
 
 [[ltw-examples]]
-==== Configuring bytecode dumping in load-time weaving
+=== Configuring bytecode dumping in load-time weaving
 
 For details of how to configure byte-code dumping, see the AspectJ
 Development Environment Guide section on
-xref:../devguide/ltw.html#configuring-load-time-weaving-with-aopxml-files[Configuring
+xref:../devguide/ltw.adoc#configuring-load-time-weaving-with-aopxml-files[Configuring
 Load-time Weaving]. Following is a simple example.
 
 [[ltwdump-examples]]
-==== LTW Dump Examples
+=== LTW Dump Examples
 
 The following `META-INF/aop.xml` will weave classes in the `com.foo`
 package (and subpackages) but not CGLIB generated classes in the
diff --git a/docs/pdguide/messages.adoc b/docs/pdguide/messages.adoc
index b9b1779d5..c32d07f07 100644
--- a/docs/pdguide/messages.adoc
+++ b/docs/pdguide/messages.adoc
@@ -1,8 +1,8 @@
 [[messages]]
-== Messages
+= Messages
 
 [[messages-introduction]]
-=== Introduction
+== Introduction
 
 Messages point out potential problems in the input program; some are
 clearly problems (errors), but many more may depend on what the
@@ -14,7 +14,7 @@ some problem scenarios when compiling or doing load-time weaving, and
 summarizes some of the more relevant messages.
 
 [[messages-introduction-config]]
-==== Configuring Messages
+=== Configuring Messages
 
 The compiler offers `-verbose`, `-warning`, and `-XLint` options when
 invoked using the command-line, Ant, or embedded in an IDE. All options
@@ -85,19 +85,19 @@ warnings associated with the next line of code.
 |===
 
 [[messages-scenarios]]
-=== Message scenarios
+== Message scenarios
 
 [[messages-scenarios-ct]]
-==== Compile-time weaving scenarios
+=== Compile-time weaving scenarios
 
 [[messages-scenarios-ct-adviceNotWoven]]
-===== Advice not woven
+==== Advice not woven
 
 This means that the pointcut for the advice did not match, and it should
 be debugged as described in xref:pointcuts.adoc#pointcuts[Debugging Pointcuts].
 
 [[messages-scenarios-ltw]]
-==== Load-time weaving scenarios
+=== Load-time weaving scenarios
 
 You can use `META-INF/aop.xml` to control which messages are produced
 during LTW. The following example will produce basic informational
@@ -129,7 +129,7 @@ applications each of which will typically have its own class loader.
 ....
 
 [[messages-scenarios-ltw-adviceNotWoven]]
-===== Advice not woven
+==== Advice not woven
 
 It is often difficult to determine, especially when using load-time
 weaving (LTW), why advice has not been woven. Here is a quick guide to
@@ -164,7 +164,7 @@ If advice is woven at this join point you should get the corresponding
 message.
 
 [[messages-xlint]]
-=== Lint messages
+== Lint messages
 
 The table below lists some useful `-Xlint` messages.
 
diff --git a/docs/pdguide/pdguide.adoc b/docs/pdguide/pdguide.adoc
index dcbcfc331..c14cc5e30 100644
--- a/docs/pdguide/pdguide.adoc
+++ b/docs/pdguide/pdguide.adoc
@@ -1,6 +1,6 @@
 = The AspectJ^TM^ Problem Diagnosis Guide
-
 :doctype: book
+:leveloffset: +1
 
 _by the AspectJ Team_
 
diff --git a/docs/pdguide/pointcuts.adoc b/docs/pdguide/pointcuts.adoc
index ecd964c57..e5199fc95 100644
--- a/docs/pdguide/pointcuts.adoc
+++ b/docs/pdguide/pointcuts.adoc
@@ -1,8 +1,8 @@
 [[pointcuts]]
-== Debugging Pointcuts
+= Debugging Pointcuts
 
 [[pointcuts-introduction]]
-=== Introduction
+== Introduction
 
 This section describes how to write and debug pointcuts using the usual
 approach of iteration and decomposition. New users are often stumped
@@ -14,11 +14,11 @@ break it down, particularly into parts that can be checked at
 compile-time, can save a lot of time.
 
 [[pointcuts-debugging]]
-=== Debugging pointcuts
+== Debugging pointcuts
 
 Go at it top-down and then bottom-up.
 
-==== Top-down
+=== Top-down
 
 Top-down, draft significant
 aspects by first writing the comments to specify responsibilities.
@@ -30,7 +30,7 @@ semantic bridge to the plain-text meaning in a comment, e.g. `// when
 the client passes only context into the library`. This gets you to a
 point where you can debug the parts of the pointcut independently.
 
-==== Bottom-up
+=== Bottom-up
 
 Bottom-up (to build each part), consider each primitive pointcut
 designator (PCD), then the composition, and then any implicit
@@ -59,12 +59,12 @@ listed above). If compiles themselves take too long because of all the
 AspectJ weaving, then try to only include the debugging aspect with the
 prototype pointcut, and limit the scope using `within(..)`.
 
-=== Common pointcut mistakes
+== Common pointcut mistakes
 
 There are some typical types of mistakes developers make when designing pointcuts.
 Here are a few examples:
 
-==== Mistakes in primitive pointcuts
+=== Mistakes in primitive pointcuts
 
 * `this(Foo) && execution(static * *(..))`: There is no `this` in a
 static context, so `this()` or `target()` should not be used in a static
@@ -90,7 +90,7 @@ within `Foo`, so this won't pick out any overrides of `bar(..)`. Use
 * `within(Foo)`: anonymous types are not known at weave-time to be
 within the lexically-enclosing type (a limitation of Java bytecode).
 
-==== Mistakes in composition
+=== Mistakes in composition
 
 * `call(* foo(Bar, Foo)) && args(Foo)`: This will never match. The
 parameters in `args(..)` are position-dependent, so `args(Foo)` only
@@ -104,7 +104,7 @@ different kinds of join points (here, call or execution), use `||`.
 E.g., to match both method-call and field-get join points, use
 `call(* ...) || get(...)`.
 
-==== Mistakes in implicit advice constraints
+=== Mistakes in implicit advice constraints
 
 * `after () returning (Foo foo) : ...`: after advice can bind the
 returned object or exception thrown. That effectively acts like
@@ -112,7 +112,7 @@ returned object or exception thrown. That effectively acts like
 based on the runtime type of the bound object, even though it is not
 explicitly part of the pointcut.
 
-==== Mistakes in implementation requirements
+=== Mistakes in implementation requirements
 
 * _ajc_ has to control the code for a join point in order to implement
 the join point. This translates to an implicit `within({code under the
diff --git a/docs/pdguide/trace.adoc b/docs/pdguide/trace.adoc
index a752e0262..d9c9de1d9 100644
--- a/docs/pdguide/trace.adoc
+++ b/docs/pdguide/trace.adoc
@@ -1,8 +1,8 @@
 [[trace]]
-== Tracing
+= Tracing
 
 [[trace-introduction]]
-=== Introduction
+== Introduction
 
 The AspectJ developers have instrumented the compiler/weaver with many
 "trace" messages for their own debugging use. These remain in the
@@ -22,7 +22,7 @@ produce a trace of the compiler when the problem occurs instead. This
 can then be attached to the bug report.
 
 [[trace-configuration]]
-==== Configuring Tracing
+=== Configuring Tracing
 
 When available (Java 5 or later) AspectJ will use the
 http://java.sun.com/j2se/1.5.0/docs/guide/logging/index.html[java.util.logging]
@@ -72,7 +72,7 @@ Default: `false`.
 |===
 
 [[trace-examples]]
-==== Examples
+=== Examples
 
 Using `-Dorg.aspectj.tracing.factory=default` to force AspectJ to use
 its internal infrastructure, `-Dorg.aspectj.tracing.enabled=true` to
diff --git a/docs/progguide/examples.adoc b/docs/progguide/examples.adoc
index caa74a620..98b7f6a3a 100644
--- a/docs/progguide/examples.adoc
+++ b/docs/progguide/examples.adoc
@@ -1,8 +1,8 @@
 [[examples]]
-== Examples
+= Examples
 
 [[examples-intro]]
-=== Introduction
+== Introduction
 
 This chapter consists entirely of examples of AspectJ use.
 
@@ -18,7 +18,7 @@ reusable::
   Examples of reuse of aspects and pointcuts
 
 [[examples-howto]]
-=== Obtaining, Compiling and Running the Examples
+== Obtaining, Compiling and Running the Examples
 
 The examples source code is part of the AspectJ distribution which may
 be downloaded from the https://eclipse.org/aspectj[AspectJ project page].
@@ -51,7 +51,7 @@ java -classpath ".;InstallDir/lib/aspectjrt.jar" telecom.billingSimulation
 ....
 
 [[examples-basic]]
-=== Basic Techniques
+== Basic Techniques
 
 This section presents two basic techniques of using AspectJ, one each
 from the two fundamental ways of capturing crosscutting concerns: with
@@ -65,7 +65,7 @@ some advice. The second example, xref:#examples-roles[Roles and Views],
 concerns a crosscutting view of an existing class hierarchy.
 
 [[examples-joinPoints]]
-==== Join Points and `thisJoinPoint`
+=== Join Points and `thisJoinPoint`
 
 (The code for this example is in `InstallDir/examples/tjp`.)
 
@@ -125,7 +125,7 @@ point
 * an object encapsulating the static information about the join point.
 This is also available through the special variable `thisJoinPointStaticPart`.
 
-===== The `Demo` class
+==== The `Demo` class
 
 The class `tjp.Demo` in `tjp/Demo.java` defines two methods `foo` and
 `bar` with different parameter lists and return types. Both are called,
@@ -158,7 +158,7 @@ public class Demo {
 }
 ....
 
-===== The `GetInfo` aspect
+==== The `GetInfo` aspect
 
 This aspect uses around advice to intercept the execution of methods
 `foo` and `bar` in `Demo`, and prints out information garnered from
@@ -201,7 +201,7 @@ aspect GetInfo {
 }
 ....
 
-====== Defining the scope of a pointcut
+===== Defining the scope of a pointcut
 
 The pointcut `goCut` is defined as
 
@@ -216,7 +216,7 @@ execution of `go` itself, so the definition of the around advice
 includes `!execution(* go())` to exclude it from the set of executions
 advised.
 
-====== Printing the class and method name
+===== Printing the class and method name
 
 The name of the method and that method's defining class are available as
 parts of the
@@ -224,7 +224,7 @@ xref:../api/org/aspectj/lang/Signature.html[`org.aspectj.lang.Signature`]
 object returned by calling `getSignature()` on either `thisJoinPoint` or
 `thisJoinPointStaticPart`.
 
-====== Printing the parameters
+===== Printing the parameters
 
 The static portions of the parameter details, the name and types of the
 parameters, can be accessed through the
@@ -236,7 +236,7 @@ The dynamic portions of the parameter details, the actual values of the
 parameters, are accessed directly from the execution join point object.
 
 [[examples-roles]]
-==== Roles and Views
+=== Roles and Views
 
 (The code for this example is in `InstallDir/examples/introduction`.)
 
@@ -269,7 +269,7 @@ and polar coordinates. Our inter-type declarations will make the class
 are provided by AspectJ without having to modify the code for the class
 `Point`.
 
-===== The `Point` class
+==== The `Point` class
 
 The `Point` class defines geometric points whose interface includes
 polar and rectangular coordinates, plus some simple operations to
@@ -289,7 +289,7 @@ with the class `Point`.
 
 image:images/aspects.png[image]
 
-===== The `CloneablePoint` aspect
+==== The `CloneablePoint` aspect
 
 This first aspect is responsible for ``Point``'s implementation of the
 `Cloneable` interface. It declares that `Point implements Cloneable`
@@ -336,7 +336,7 @@ public aspect CloneablePoint {
 }
 ....
 
-===== The `ComparablePoint` aspect
+==== The `ComparablePoint` aspect
 
 `ComparablePoint` is responsible for ``Point``'s implementation of the
 `Comparable` interface.
@@ -387,7 +387,7 @@ public aspect ComparablePoint {
 }
 ....
 
-===== The `HashablePoint` aspect
+==== The `HashablePoint` aspect
 
 Our third aspect is responsible for ``Point``'s overriding of ``Object``'s
 `equals` and `hashCode` methods in order to make ``Point``s hashable.
@@ -450,9 +450,9 @@ public aspect HashablePoint {
 ....
 
 [[examples-development]]
-=== Development Aspects
+== Development Aspects
 
-==== Tracing using aspects
+=== Tracing using aspects
 
 (The code for this example is in `InstallDir/examples/tracing`.)
 
@@ -482,7 +482,7 @@ one of those kind of system aspects that can potentially be plugged in
 and unplugged without any side-effects in the basic functionality of the
 system.
 
-===== An Example Application
+==== An Example Application
 
 Throughout this example we will use a simple application that contains
 only four classes. The application is about shapes. The `TwoDShape`
@@ -586,7 +586,7 @@ s1.distance(c1) = 2.23606797749979
 s1.toString(): Square side = 1.0 @ (1.0, 2.0)
 ....
 
-===== Tracing - Version 1
+==== Tracing - Version 1
 
 In a first attempt to insert tracing in this application, we will start
 by writing a `Trace` class that is exactly what we would write if we
@@ -707,7 +707,7 @@ s1.toString(): Square side = 1.0 @ (1.0, 2.0)
 When `TraceMyClasses.java` is not provided to `ajc`, the aspect does not
 have any affect on the system and the tracing is unplugged.
 
-===== Tracing - Version 2
+==== Tracing - Version 2
 
 Another way to accomplish the same thing would be to write a reusable
 tracing aspect that can be used not only for these application classes,
@@ -846,9 +846,9 @@ Abstract methods don't provide the implementation, but you know that the
 concrete subclasses will, so you can invoke those methods.
 
 [[examples-production]]
-=== Production Aspects
+== Production Aspects
 
-==== A Bean Aspect
+=== A Bean Aspect
 
 (The code for this example is in `InstallDir/examples/bean`.)
 
@@ -876,7 +876,7 @@ class is not serializable. Bound is an aspect that makes `Point` a
 serializable class and makes its `get` and `set` methods support the
 bound property protocol.
 
-===== The `Point` class
+==== The `Point` class
 
 The `Point` class is a very simple class with trivial getters and
 setters, and a simple vector offset method.
@@ -919,7 +919,7 @@ class Point {
 }
 ....
 
-===== The `BoundPoint` aspect
+==== The `BoundPoint` aspect
 
 The `BoundPoint` aspect is responsible for ``Point``'s "beanness". The
 first thing it does is privately declare that each `Point` has a
@@ -1023,7 +1023,7 @@ aspect BoundPoint {
 }
 ....
 
-===== The Test Program
+==== The Test Program
 
 The test program registers itself as a property change listener to a
 `Point` object that it creates and then performs simple manipulation of
@@ -1064,7 +1064,7 @@ class Demo implements PropertyChangeListener {
 }
 ....
 
-===== Compiling and Running the Example
+==== Compiling and Running the Example
 
 To compile and run this example, go to the examples directory and type:
 
@@ -1075,7 +1075,7 @@ java bean.Demo
 ....
 
 [[the-subject-observer-protocol]]
-==== The Subject/Observer Protocol
+=== The Subject/Observer Protocol
 
 (The code for this example is in `InstallDir/examples/observer`.)
 
@@ -1095,7 +1095,7 @@ The demo is designed and implemented using the Subject/Observer design
 pattern. The remainder of this example explains the classes and aspects
 of this demo, and tells you how to run it.
 
-===== Generic Components
+==== Generic Components
 
 The generic parts of the protocol are the interfaces `Subject` and
 `Observer`, and the abstract aspect `SubjectObserverProtocol`. The
@@ -1165,7 +1165,7 @@ after the join points of the pointcut. And it declares an inter-type
 field and two inter-type methods so that each `Observer` can hold onto
 its `Subject`.
 
-===== Application Classes
+==== Application Classes
 
 `Button` objects extend `java.awt.Button`, and all they do is make sure
 the `void click()` method is called whenever a button is clicked.
@@ -1255,7 +1255,7 @@ required by those interfaces, and providing a definition for the
 abstract `stateChanges` pointcut. Now, every time a `Button` is clicked,
 all `ColorLabel` objects observing that button will `colorCycle`.
 
-===== Compiling and Running
+==== Compiling and Running
 
 `Demo` is the top class that starts this demo. It instantiates a two
 buttons and three observers and links them together as subjects and
@@ -1267,7 +1267,7 @@ ajc -argfile observer/files.lst
 java observer.Demo
 ....
 
-==== A Simple Telecom Simulation
+=== A Simple Telecom Simulation
 
 (The code for this example is in `InstallDir/examples/telecom`.)
 
@@ -1277,7 +1277,7 @@ model of telephone connections to which timing and billing features are
 added using aspects, where the billing feature depends upon the timing
 feature.
 
-===== The Application
+==== The Application
 
 The example application is a simple simulation of a telephony system in
 which customers make, accept, merge and hang-up both local and long
@@ -1303,7 +1303,7 @@ share a common superclass `AbstractSimulation`, which defines the method
 run with the simulation itself and the method wait used to simulate
 elapsed time.
 
-===== The Basic Objects
+==== The Basic Objects
 
 The telecom simulation comprises the classes `Customer`, `Call` and the
 abstract class `Connection` with its two concrete subclasses `Local` and
@@ -1316,7 +1316,7 @@ involved in many calls at one time.
 
 image:images/telecom.png[image]
 
-===== The `Customer` class
+==== The `Customer` class
 
 `Customer` has methods `call`, `pickup`, `hangup` and `merge` for
 managing calls.
@@ -1377,7 +1377,7 @@ public class Customer {
 }
 ....
 
-===== The `Call` class
+==== The `Call` class
 
 Calls are created with a caller and receiver who are customers. If the
 caller and receiver have the same area code then the call can be
@@ -1387,7 +1387,7 @@ connections between customers. Initially there is only the connection
 between the caller and receiver but additional connections can be added
 if calls are merged to form conference calls.
 
-===== The `Connection` class
+==== The `Connection` class
 
 The class `Connection` models the physical details of establishing a
 connection between customers. It does this with a simple state machine
@@ -1437,7 +1437,7 @@ abstract class Connection {
 }
 ....
 
-===== The `Local` and `LongDistance` classes
+==== The `Local` and `LongDistance` classes
 
 The two kinds of connections supported by our simulation are `Local` and
 `LongDistance` connections.
@@ -1466,7 +1466,7 @@ class LongDistance extends Connection {
 }
 ....
 
-===== Compiling and Running the Basic Simulation
+==== Compiling and Running the Basic Simulation
 
 The source files for the basic system are listed in the file
 `basic.lst`. To build and run the basic system, in a shell window, type
@@ -1478,13 +1478,13 @@ ajc -argfile telecom/basic.lst
 java telecom.BasicSimulation
 ....
 
-===== The Timing aspect
+==== The Timing aspect
 
 The `Timing` aspect keeps track of total connection time for each
 `Customer` by starting and stopping a timer associated with each
 connection. It uses some helper classes:
 
-====== The `Timer` class
+===== The `Timer` class
 
 A `Timer` object simply records the current time when it is started and
 stopped, and returns their difference when asked for the elapsed time.
@@ -1511,7 +1511,7 @@ class Timer {
 }
 ....
 
-===== The `TimerLog` aspect
+==== The `TimerLog` aspect
 
 The `TimerLog` aspect can be included in a build to get the timer to
 announce when it is started and stopped.
@@ -1530,7 +1530,7 @@ public aspect TimerLog {
 }
 ....
 
-===== The `Timing` aspect
+==== The `Timing` aspect
 
 The `Timing` aspect is declares an inter-type field `totalConnectTime`
 for `Customer` to store the accumulated connection time per `Customer`.
@@ -1573,7 +1573,7 @@ public aspect Timing {
 }
 ....
 
-===== The `Billing` aspect
+==== The `Billing` aspect
 
 The Billing system adds billing functionality to the telecom application
 on top of timing.
@@ -1627,7 +1627,7 @@ public aspect Billing {
 }
 ....
 
-===== Accessing the inter-type state
+==== Accessing the inter-type state
 
 Both the aspects `Timing` and `Billing` contain the definition of
 operations that the rest of the system may want to access. For example,
@@ -1651,7 +1651,7 @@ protected void report(Customer c){
 }
 ....
 
-===== Compiling and Running
+==== Compiling and Running
 
 The files timing.lst and billing.lst contain file lists for the timing
 and billing configurations. To build and run the application with only
@@ -1672,7 +1672,7 @@ ajc -argfile telecom/billing.lst
 java telecom.BillingSimulation
 ....
 
-===== Discussion
+==== Discussion
 
 There are some explicit dependencies between the aspects `Billing` and
 `Timing`:
@@ -1683,13 +1683,13 @@ advice runs after that of `Timing` when they are on the same join point.
 * `Billing` needs access to the timer associated with a connection.
 
 [[examples-reusable]]
-=== Reusable Aspects
+== Reusable Aspects
 
-==== Tracing using Aspects, Revisited
+=== Tracing using Aspects, Revisited
 
 (The code for this example is in `InstallDir/examples/tracing`.)
 
-===== Tracing - Version 3
+==== Tracing - Version 3
 
 One advantage of not exposing the methods `traceEntry` and `traceExit` as
 public operations is that we can easily change their interface without
diff --git a/docs/progguide/gettingstarted.adoc b/docs/progguide/gettingstarted.adoc
index b7de29e59..b74006724 100644
--- a/docs/progguide/gettingstarted.adoc
+++ b/docs/progguide/gettingstarted.adoc
@@ -1,8 +1,8 @@
 [[starting]]
-== Getting Started with AspectJ
+= Getting Started with AspectJ
 
 [[starting-intro]]
-=== Introduction
+== Introduction
 
 Many software developers are attracted to the idea of aspect-oriented
 programming (AOP) but unsure about how to begin using the technology.
@@ -48,7 +48,7 @@ is one ordering that allows developers to get experience with (and
 benefit from) AOP technology quickly, while also minimizing risk.
 
 [[starting-aspectj]]
-=== Introduction to AspectJ
+== Introduction to AspectJ
 
 This section presents a brief introduction to the features of AspectJ
 used later in this chapter. These features are at the core of the
@@ -114,7 +114,7 @@ inheritable unit of modularity. Lastly, we will look at how to use
 inter-type declarations to deal with crosscutting concerns of a
 program's class structure.
 
-==== The Dynamic Join Point Model
+=== The Dynamic Join Point Model
 
 A critical element in the design of any aspect-oriented language is the
 join point model. The join point model provides the common frame of
@@ -138,7 +138,7 @@ from the body. We say that these join points execute in the _dynamic
 context_ of the original call join point.
 
 [[pointcuts-starting]]
-==== Pointcuts
+=== Pointcuts
 
 In AspectJ, _pointcuts_ pick out certain join points in the program
 flow. For example, the pointcut
@@ -239,7 +239,7 @@ called and when it returns (either normally or by throwing an
 exception).
 
 [[advice-starting]]
-==== Advice
+=== Advice
 
 So pointcuts pick out join points. But they don't _do_ anything apart
 from picking out join points. To actually implement crosscutting
@@ -279,7 +279,7 @@ _Around advice_ on a join point runs as the join point is reached, and
 has explicit control over whether the program proceeds with the join
 point. Around advice is not discussed in this section.
 
-===== Exposing Context in Pointcuts
+==== Exposing Context in Pointcuts
 
 Pointcuts not only pick out join points, they can also expose part of
 the execution context at their join points. Values exposed by a pointcut
@@ -353,7 +353,7 @@ after(FigureElement fe, int x, int y) returning: setXY(fe, x, y) {
 }
 ....
 
-==== Inter-type declarations
+=== Inter-type declarations
 
 Inter-type declarations in AspectJ are declarations that cut across
 classes and their hierarchies. They may declare members that cut across
@@ -440,7 +440,7 @@ Note that neither ``Screen``'s nor ``Point``'s code has to be modified, and
 that all the changes needed to support this new capability are local to
 this aspect.
 
-==== Aspects
+=== Aspects
 
 Aspects wrap up pointcuts, advice, and inter-type declarations in a a
 modular unit of crosscutting implementation. It is defined very much
@@ -469,7 +469,7 @@ Aspects may also have more complicated rules for instantiation, but
 these will be described in a later chapter.
 
 [[starting-development]]
-=== Development Aspects
+== Development Aspects
 
 The next two sections present the use of aspects in increasingly
 sophisticated ways. Development aspects are easily removed from
@@ -484,7 +484,7 @@ consistency within the application. Using AspectJ makes it possible to
 cleanly modularize this kind of functionality, thereby making it
 possible to easily enable and disable the functionality when desired.
 
-==== Tracing
+=== Tracing
 
 This first example shows how to increase the visibility of the internal
 workings of a program. It is a simple tracing aspect that prints a
@@ -537,7 +537,7 @@ that have proven useful in the past is a direct result of AspectJ
 modularizing a crosscutting design element the set of methods that are
 appropriate to trace when looking for a given kind of information.
 
-==== Profiling and Logging
+=== Profiling and Logging
 
 Our second example shows you how to do some very specific profiling.
 Although many sophisticated profiling tools are available, and these can
@@ -588,7 +588,7 @@ Such questions may be difficult to express using standard profiling or
 logging tools.
 
 [[pre-and-post-conditions]]
-==== Pre- and Post-Conditions
+=== Pre- and Post-Conditions
 
 Many programmers use the "Design by Contract" style popularized by
 Bertand Meyer in Object-Oriented Software Construction, 2/e. In this
@@ -637,7 +637,7 @@ in the production build as well. Again, because AspectJ makes it
 possible to modularize these crosscutting concerns cleanly, it gives
 developers good control over this decision.
 
-==== Contract Enforcement
+=== Contract Enforcement
 
 The property-based crosscutting mechanisms can be very useful in
 defining more sophisticated contract enforcement. One very powerful use
@@ -692,7 +692,7 @@ and the `call` pointcut here picks out join points statically). Other
 enforcement, such as the precondition enforcement, above, does require
 dynamic information such as the runtime value of parameters.
 
-==== Configuration Management
+=== Configuration Management
 
 Configuration management for aspects can be handled using a variety of
 make-file like techniques. To work with optional aspects, the programmer
@@ -706,7 +706,7 @@ to write such make files, the AspectJ compiler has a command-line
 interface that is consistent with ordinary Java compilers.
 
 [[starting-production]]
-=== Production Aspects
+== Production Aspects
 
 This section presents examples of aspects that are inherently intended
 to be included in the production builds of an application. Production
@@ -719,7 +719,7 @@ adopting AspectJ. But even though they tend to be small and simple, they
 can often have a significant effect in terms of making the program
 easier to understand and maintain.
 
-==== Change Monitoring
+=== Change Monitoring
 
 The first example production aspect shows how one might implement some
 simple functionality where it is problematic to try and do it
@@ -803,7 +803,7 @@ compelling for property-based aspects (see the section
 xref:#starting-production-consistentBehavior[Providing Consistent
 Behavior]).
 
-==== Context Passing
+=== Context Passing
 
 The crosscutting structure of context passing can be a significant
 source of complexity in Java programs. Consider implementing
@@ -844,7 +844,7 @@ aspects while the aspect is short and affects only a modest number of
 benefits, the complexity the aspect saves is potentially much larger.
 
 [[starting-production-consistentBehavior]]
-==== Providing Consistent Behavior
+=== Providing Consistent Behavior
 
 This example shows how a property-based aspect can be used to provide
 consistent handling of functionality across a large set of operations.
@@ -935,7 +935,7 @@ crosscutting structure of the aspect explicitly made the code more
 concise and eliminated latent bugs.
 
 [[starting-conclusion]]
-=== Conclusion
+== Conclusion
 
 AspectJ is a simple and practical aspect-oriented extension to Java.
 With just a few new constructs, AspectJ provides support for modular
diff --git a/docs/progguide/idioms.adoc b/docs/progguide/idioms.adoc
index e27395a48..a264084e0 100644
--- a/docs/progguide/idioms.adoc
+++ b/docs/progguide/idioms.adoc
@@ -1,7 +1,7 @@
-== Idioms
+= Idioms
 
 [[idioms-intro]]
-=== Introduction
+== Introduction
 
 This chapter consists of very short snippets of AspectJ code, typically
 pointcuts, that are particularly evocative or useful. This section is a
diff --git a/docs/progguide/implementation.adoc b/docs/progguide/implementation.adoc
index 42ee2e37e..03a0e19ae 100644
--- a/docs/progguide/implementation.adoc
+++ b/docs/progguide/implementation.adoc
@@ -1,7 +1,7 @@
 [[implementation]]
-== Implementation Notes
+= Implementation Notes
 
-=== Compiler Notes
+== Compiler Notes
 
 The initial implementations of AspectJ have all been compiler-based
 implementations. Certain elements of AspectJ's semantics are difficult
@@ -108,10 +108,10 @@ used. During your development, you will have to be aware of the
 limitations of the _ajc_ compiler you're using, but these limitations
 should not drive the design of your aspects.
 
-=== Bytecode Notes
+== Bytecode Notes
 
 [[the-class-expression-and-string-plus]]
-==== The `.class` expression and `String` `+`
+=== The `.class` expression and `String` `+`
 
 The java language form `Foo.class` is implemented in bytecode with a
 call to `Class.forName` guarded by an exception handler catching a
@@ -140,7 +140,7 @@ class Test {
 In short, the join point model of the current AspectJ compiler considers
 these as valid join points.
 
-==== The `handler()` join point
+=== The `handler()` join point
 
 The end of exception handlers cannot reliably be found in Java bytecode.
 Instead of removing the `handler` join point entirely, the current AspectJ
@@ -185,7 +185,7 @@ A source-code implementation of AspectJ (such as AspectJ 1.0.6) is able
 to detect the endpoint of a handler join point, and as such will likely
 have fewer such restrictions.
 
-==== Initializers and Inter-type Constructors
+=== Initializers and Inter-type Constructors
 
 The code for Java initializers, such as the assignment to the field `d` in
 
@@ -221,7 +221,7 @@ aspect A {
 It is the job of an inter-type constructor to do all the required
 initialization, or to delegate to a `this` constructor if necessary.
 
-=== Annotation-style Notes
+== Annotation-style Notes
 
 Writing aspects in annotation-style is subject to the same bytecode
 limitations since the binary aspects take the same form and are woven in
@@ -229,7 +229,7 @@ the same way. However, the implementation differences (e.g., the
 mechanism for implementing `around` advice) may be apparent at runtime.
 See the documentation on annotation-style for more information.
 
-=== Summary of implementation requirements
+== Summary of implementation requirements
 
 This summarizes the requirements of our implementation of AspectJ. For
 more details, see the relevant sections of this guide.
diff --git a/docs/progguide/index.adoc b/docs/progguide/index.adoc
index eb1b42375..11ba5afd8 100644
--- a/docs/progguide/index.adoc
+++ b/docs/progguide/index.adoc
@@ -1,6 +1,6 @@
 = The AspectJ^TM^ Programming Guide
-
 :doctype: book
+:leveloffset: +1
 
 _by the AspectJ Team_
 
diff --git a/docs/progguide/language.adoc b/docs/progguide/language.adoc
index 14b662aad..72a49e813 100644
--- a/docs/progguide/language.adoc
+++ b/docs/progguide/language.adoc
@@ -1,8 +1,8 @@
 [[language]]
-== The AspectJ Language
+= The AspectJ Language
 
 [[language-intro]]
-=== Introduction
+== Introduction
 
 The previous chapter, xref:gettingstarted.adoc#starting[Getting Started with AspectJ], was a brief overview of the
 AspectJ language. You should read this chapter to understand AspectJ's
@@ -14,13 +14,13 @@ of a pointcut, an introduction, and two pieces of advice. This example
 aspect will gives us something concrete to talk about.
 
 [[language-anatomy]]
-=== The Anatomy of an Aspect
+== The Anatomy of an Aspect
 
 This lesson explains the parts of AspectJ's aspects. By reading this
 lesson you will have an overview of what's in an aspect and you will be
 exposed to the new terminology introduced by AspectJ.
 
-==== An Example Aspect
+=== An Example Aspect
 
 Here's an example of an aspect definition in AspectJ:
 
@@ -61,7 +61,7 @@ and methods, pointcut definitions, inter-type declarations, and advice,
 where advice may be before, after or around advice. The remainder of
 this lesson focuses on those crosscut-related constructs.
 
-==== Pointcuts
+=== Pointcuts
 
 AspectJ's pointcut definitions give names to pointcuts. Pointcuts
 themselves pick out join points, i.e. interesting points in the
@@ -109,7 +109,7 @@ execution, and field access. Each kind of join point can be picked out
 by its own specialized pointcut that you will learn about in other parts
 of this guide.
 
-==== Advice
+=== Advice
 
 A piece of advice brings together a pointcut and a body of code to
 define aspect implementation that runs at join points picked out by the
@@ -148,7 +148,7 @@ third kind of advice called around. You will see those in other parts of
 this guide.
 
 [[language-joinPoints]]
-=== Join Points and Pointcuts
+== Join Points and Pointcuts
 
 Consider the following Java class:
 
@@ -221,7 +221,7 @@ separated by a colon. The left-hand side consists of the pointcut name
 and the pointcut parameters (i.e. the data available when the events
 happen). The right-hand side consists of the pointcut itself.
 
-==== Some Example Pointcuts
+=== Some Example Pointcuts
 
 Here are examples of pointcuts picking out
 
@@ -302,7 +302,7 @@ in ``MyInterface``'s signature -- that is, any method defined by
 `MyInterface` or inherited by one of its a supertypes.
 
 [[call-vs-execution]]
-==== call vs. execution
+=== call vs. execution
 
 When methods and constructors run, there are two interesting times
 associated with them. That is when they are called, and when they
@@ -335,7 +335,7 @@ use `execution`, but if you want to pick one that runs when a particular
 _signature_ is called (as is often the case for production aspects), use
 `call`.
 
-==== Pointcut composition
+=== Pointcut composition
 
 Pointcuts are put together with the operators and (spelled `&&`), or
 (spelled `||`), and not (spelled `!`). This allows the creation of very
@@ -426,7 +426,7 @@ If this was not present a recursive call would result as the pointcut
 would apply to its own advice. (See xref:pitfalls.adoc#pitfalls-infiniteLoops[Infinite loops]
 for more details.)
 
-==== Pointcut Parameters
+=== Pointcut Parameters
 
 Consider again the first pointcut definition in this chapter:
 
@@ -520,7 +520,7 @@ when calling `setY`, but the pointcut picks out all of these join points
 and tries to bind both `p1` and `p2`.
 
 [[example]]
-==== Example: `HandleLiveness`
+=== Example: `HandleLiveness`
 
 The example below consists of two object classes (plus an exception
 class) and one aspect. Handle objects delegate their public, non-static
@@ -561,7 +561,7 @@ class DeadPartnerException extends RuntimeException {}
 ....
 
 [[pointcut-best-practice]]
-==== Writing good pointcuts
+=== Writing good pointcuts
 
 During compilation, AspectJ processes pointcuts in order to try and
 optimize matching performance. Examining code and determining if each
@@ -603,7 +603,7 @@ processed - that is why a good pointcut should always include one if
 possible.
 
 [[language-advice]]
-=== Advice
+== Advice
 
 Advice defines pieces of aspect implementation that execute at
 well-defined points in the execution of the program. Those points can be
@@ -710,7 +710,7 @@ void around(Point p, int x):
 ....
 
 [[language-interType]]
-=== Inter-type declarations
+== Inter-type declarations
 
 Aspects can declare members (fields, methods, and constructors) that are
 owned by other types. These are called inter-type members. Aspects can
@@ -820,7 +820,7 @@ As you can see from the above example, an aspect can declare that
 interfaces have fields and methods, even non-constant fields and methods
 with bodies.
 
-==== Inter-type Scope
+=== Inter-type Scope
 
 AspectJ allows private and package-protected (default) inter-type
 declarations in addition to public inter-type declarations. Private
@@ -843,7 +843,7 @@ int Foo.x;
 then everything in the aspect's package (which may or may not be ``Foo``'s
 package) can access `x`.
 
-==== Example: `PointAssertions`
+=== Example: `PointAssertions`
 
 The example below consists of one class and one aspect. The aspect
 privately declares the assertion methods of `Point`, `assertX` and
@@ -888,7 +888,7 @@ aspect PointAssertions {
 ....
 
 [[language-thisJoinPoint]]
-=== `thisJoinPoint`
+== `thisJoinPoint`
 
 AspectJ provides a special reference variable, `thisJoinPoint`, that
 contains reflective information about the current join point for the
diff --git a/docs/progguide/pitfalls.adoc b/docs/progguide/pitfalls.adoc
index eb9e15315..a80460c58 100644
--- a/docs/progguide/pitfalls.adoc
+++ b/docs/progguide/pitfalls.adoc
@@ -1,13 +1,13 @@
-== Pitfalls
+= Pitfalls
 
 [[pitfalls-intro]]
-=== Introduction
+== Introduction
 
 This chapter consists of a few AspectJ programs that may lead to
 surprising behavior and how to understand them.
 
 [[pitfalls-infiniteLoops]]
-=== Infinite loops
+== Infinite loops
 
 Here is a Java program with peculiar behavior
 
diff --git a/docs/progguide/preface.adoc b/docs/progguide/preface.adoc
index efeb18637..92f0c1da0 100644
--- a/docs/progguide/preface.adoc
+++ b/docs/progguide/preface.adoc
@@ -1,4 +1,4 @@
-== Preface
+= Preface
 
 This programming guide does three things. It
 
diff --git a/docs/progguide/progguide.adoc b/docs/progguide/progguide.adoc
index 2e595edb6..6099dd5f1 100644
--- a/docs/progguide/progguide.adoc
+++ b/docs/progguide/progguide.adoc
@@ -1,6 +1,6 @@
 = The AspectJ^TM^ Programming Guide
-
 :doctype: book
+:leveloffset: +1
 
 _by the AspectJ Team_
 
diff --git a/docs/progguide/quickreference.adoc b/docs/progguide/quickreference.adoc
index 3920b5ef2..d1a16066d 100644
--- a/docs/progguide/quickreference.adoc
+++ b/docs/progguide/quickreference.adoc
@@ -1,8 +1,8 @@
 [[quick]]
-== AspectJ Quick Reference
+= AspectJ Quick Reference
 
 [[quick-pointcuts]]
-=== Pointcuts
+== Pointcuts
 
 [cols=",",]
 |===
@@ -56,7 +56,7 @@ or constructor matching `Signature`
 |===
 
 [[quick-typePatterns]]
-=== Type Patterns
+== Type Patterns
 
 A type pattern is one of
 
@@ -90,7 +90,7 @@ An embedded `..` in an identifier matches any sequence of characters
 that starts and ends with the package (or inner-type) separator `.`.
 
 [[quick-advice]]
-=== Advice
+== Advice
 
 Each piece of advice is of the form
 
@@ -130,7 +130,7 @@ Three special variables are available inside of advice bodies:
   the static part of the dynamically enclosing join point
 
 [[quick-interType]]
-=== Inter-type member declarations
+== Inter-type member declarations
 
 Each inter-type member is one of
 
@@ -144,7 +144,7 @@ Each inter-type member is one of
   a field on `OnType`
 
 [[quick-other]]
-=== Other declarations
+== Other declarations
 
 `declare parents : TypePattern extends Type ;`::
   the types in `TypePattern` extend `Type`
@@ -164,7 +164,7 @@ Each inter-type member is one of
   precedence at that join point is in `TypePatternList` order
 
 [[quick-aspectAssociations]]
-=== Aspects
+== Aspects
 
 Each aspect is of the form
 
diff --git a/docs/progguide/semantics.adoc b/docs/progguide/semantics.adoc
index 0cb513ad0..d993d2fcb 100644
--- a/docs/progguide/semantics.adoc
+++ b/docs/progguide/semantics.adoc
@@ -1,8 +1,8 @@
 [[semantics]]
-== Language Semantics
+= Language Semantics
 
 [[semantics-intro]]
-=== Introduction
+== Introduction
 
 AspectJ extends Java by overlaying a concept of join points onto the
 existing Java semantics and adding a few new program elements to Java:
@@ -35,7 +35,7 @@ possible to do reasoning at compile time. Aspects are defined by the
 `aspect` declaration.
 
 [[semantics-joinPoints]]
-=== Join Points
+== Join Points
 
 While aspects define types that crosscut, the AspectJ system does not
 allow completely arbitrary crosscutting. Rather, aspects define types
@@ -152,7 +152,7 @@ bodies or static initializers.
 methods or fields.
 
 [[semantics-pointcuts]]
-=== Pointcuts
+== Pointcuts
 
 A pointcut is a program element that picks out join points and exposes
 data from the execution context of those join points. Pointcuts are used
@@ -233,7 +233,7 @@ provided by the language are:
 `( Pointcut )`::
   Picks out each join points picked out by `_Pointcut_` .
 
-==== Pointcut definition
+=== Pointcut definition
 
 Pointcuts are defined and named by the programmer with the `pointcut`
 declaration.
@@ -300,7 +300,7 @@ aspect B percflow(publicCall()) {
 }
 ....
 
-==== Context exposure
+=== Context exposure
 
 Pointcuts have an interface; they expose some parts of the execution
 context of the join points they pick out. For example, the PublicIntCall
@@ -384,9 +384,9 @@ aspect IntToLong {
 The pointcut will match and expose the integer argument, but it will
 expose it as an `Integer`, not a `Long`.
 
-==== Primitive pointcuts
+=== Primitive pointcuts
 
-===== Method-related pointcuts
+==== Method-related pointcuts
 
 AspectJ provides two primitive pointcut designators designed to capture
 method call and execution join points.
@@ -394,7 +394,7 @@ method call and execution join points.
 * `call( MethodPattern )`
 * `execution( MethodPattern )`
 
-===== Field-related pointcuts
+==== Field-related pointcuts
 
 AspectJ provides two primitive pointcut designators designed to capture
 field reference and set join points:
@@ -419,7 +419,7 @@ aspect GuardedX {
 }
 ....
 
-===== Object creation-related pointcuts
+==== Object creation-related pointcuts
 
 AspectJ provides primitive pointcut designators designed to capture the
 initializer execution join points of objects.
@@ -429,14 +429,14 @@ initializer execution join points of objects.
 * `initialization( ConstructorPattern )`
 * `preinitialization( ConstructorPattern )`
 
-===== Class initialization-related pointcuts
+==== Class initialization-related pointcuts
 
 AspectJ provides one primitive pointcut designator to pick out static
 initializer execution join points.
 
 * `staticinitialization( TypePattern )`
 
-===== Exception handler execution-related pointcuts
+==== Exception handler execution-related pointcuts
 
 AspectJ provides one primitive pointcut designator to capture execution
 of exception handlers:
@@ -457,7 +457,7 @@ aspect NormalizeFooException {
 }
 ....
 
-===== Advice execution-related pointcuts
+==== Advice execution-related pointcuts
 
 AspectJ provides one primitive pointcut designator to capture execution
 of advice
@@ -478,7 +478,7 @@ aspect TraceStuff {
 }
 ....
 
-===== State-based pointcuts
+==== State-based pointcuts
 
 Many concerns cut across the dynamic times when an object of a
 particular type is executing, being operated on, or being passed around.
@@ -521,7 +521,7 @@ args(int, .., String)
 will pick out all join points where the first argument is an `int` and
 the last is a `String`.
 
-===== Control flow-based pointcuts
+==== Control flow-based pointcuts
 
 Some concerns cut across the control flow of the program. The `cflow`
 and `cflowbelow` primitive pointcut designators capture join points
@@ -540,7 +540,7 @@ entry and exit of each join point `P` picked out by `Pointcut`, but not
 including `P` itself. Hence, it picks out the join points _below_ the
 control flow of the join points picked out by `Pointcut`.
 
-====== Context exposure from control flows
+===== Context exposure from control flows
 
 The `cflow` and `cflowbelow` pointcuts may expose context state through
 enclosed `this`, `target`, and `args` pointcuts.
@@ -577,7 +577,7 @@ aspect A {
 It is an error to expose such state through _negated_ control flow
 pointcuts, such as within `!cflowbelow(P)`.
 
-===== Program text-based pointcuts
+==== Program text-based pointcuts
 
 While many concerns cut across the runtime structure of the program,
 some must deal with the lexical structure. AspectJ allows aspects to
@@ -603,7 +603,7 @@ expressions of the method or constructor. It also includes any join
 points that are associated with code in a method or constructor's local
 or anonymous types.
 
-===== Expression-based pointcuts
+==== Expression-based pointcuts
 
 * `if( BooleanExpression )`
 
@@ -623,13 +623,13 @@ a join point is undefined. Writing `if` pointcuts that have side-effects
 is considered bad style and may also lead to potentially confusing or
 even changing behavior with regard to when or if the test code will run.
 
-==== Signatures
+=== Signatures
 
 One very important property of a join point is its signature, which is
 used by many of AspectJ's pointcut designators to select particular join
 points.
 
-===== Methods
+==== Methods
 
 Join points associated with methods typically have method signatures,
 consisting of a method name, parameter types, return type, the types of
@@ -645,7 +645,7 @@ means that the signature for the join point created from the call
 At a method execution join point, the signature is a method signature
 whose qualifying type is the declaring type of the method.
 
-===== Fields
+==== Fields
 
 Join points associated with fields typically have field signatures,
 consisting of a field name and a field type. A field reference join
@@ -653,7 +653,7 @@ point has such a signature, and no parameters. A field set join point
 has such a signature, but has a has a single parameter whose type is the
 same as the field type.
 
-===== Constructors
+==== Constructors
 
 Join points associated with constructors typically have constructor
 signatures, consisting of a parameter types, the types of the declared
@@ -669,7 +669,7 @@ signature is the constructor signature for the constructor that started
 this initialization: the first constructor entered during this type's
 initialization of this object.
 
-===== Others
+==== Others
 
 At a handler execution join point, the signature is composed of the
 exception type that the handler handles.
@@ -679,7 +679,7 @@ aspect type, the parameter types of the advice, the return type (void
 for all but around advice) and the types of the declared (checked)
 exceptions.
 
-==== Matching
+=== Matching
 
 The `withincode`, `call`, `execution`, `get`, and `set` primitive
 pointcut designators all use signature patterns to determine the join
@@ -796,7 +796,7 @@ private null constructor of a class `C` defined to throw an
 execution(private C.new() throws ArithmeticException)
 ....
 
-===== Matching based on the declaring type
+==== Matching based on the declaring type
 
 The signature-matching pointcuts all specify a declaring type, but the
 meaning varies slightly for each join point signature, in line with Java
@@ -869,7 +869,7 @@ class Sub extends Middle {
 }
 ....
 
-===== Matching based on the `throws` clause
+==== Matching based on the `throws` clause
 
 Type patterns may be used to pick out methods and constructors based on
 their `throws` clauses. This allows the following two kinds of extremely
@@ -927,13 +927,13 @@ declares that it `throws IOException`.
 [2] *will* match the method `m()`, because ``m``'s throws clause declares that
 it throws some exception which does not match `IOException`, i.e. `RuntimeException`.
 
-==== Type patterns
+=== Type patterns
 
 Type patterns are a way to pick out collections of types and use them in
 places where you would otherwise use only one type. The rules for using
 type patterns are simple.
 
-===== Exact type pattern
+==== Exact type pattern
 
 First, all type names are also type patterns. So `Object`,
 `java.util.HashMap`, `Map.Entry`, `int` are all type patterns.
@@ -953,7 +953,7 @@ then the matching works just like normal type lookup in Java:
 
 So exact type patterns match based on usual Java scope rules.
 
-===== Type name patterns
+==== Type name patterns
 
 There is a special type name, `\*`, which is also a type pattern. `*` picks
 out all types, including primitive types. So
@@ -1004,7 +1004,7 @@ Type patterns with wildcards do not depend on Java's usual scope rules -
 they match against all types available to the weaver, not just those
 that are imported into an Aspect's declaring file.
 
-===== Subtype patterns
+==== Subtype patterns
 
 It is possible to pick out all subtypes of a type (or a collection of
 types) with the `+` wildcard. The `+` wildcard follows immediately a
@@ -1034,13 +1034,13 @@ call(*Handler+.new())
 picks out all constructor call join points where an instance of any
 subtype of any type whose name ends in `Handler` is constructed.
 
-===== Array type patterns
+==== Array type patterns
 
 A type name pattern or subtype pattern can be followed by one or more
 sets of square brackets to make array type patterns. So `Object[]` is an
 array type pattern, and so is `com.xerox..*[][]`, and so is `Object+[]`.
 
-===== Type patterns
+==== Type patterns
 
 Type patterns are built up out of type name patterns, subtype patterns,
 and array type patterns, and constructed with boolean operators `&&`,
@@ -1062,7 +1062,7 @@ call((Foo+ && ! Foo).new(..))
 picks out the constructor call join points when a subtype of `Foo`, but
 not `Foo` itself, is constructed.
 
-==== Pattern Summary
+=== Pattern Summary
 
 Here is a summary of the pattern syntax used in AspectJ:
 
@@ -1093,7 +1093,7 @@ ModifiersPattern =
 ....
 
 [[semantics-advice]]
-=== Advice
+== Advice
 
 Each piece of advice is of the form
 
@@ -1338,13 +1338,13 @@ prove that there won't be a runtime binary-compatible change in the
 hierarchy of `LinkedList` or some other advice on the join point that
 requires a `LinkedList`.
 
-==== Advice modifiers
+=== Advice modifiers
 
 The `strictfp` modifier is the only modifier allowed on advice, and it
 has the effect of making all floating-point expressions within the
 advice be FP-strict.
 
-==== Advice and checked exceptions
+=== Advice and checked exceptions
 
 An advice declaration must include a `throws` clause listing the checked
 exceptions the body may throw. This list of checked exceptions must be
@@ -1394,12 +1394,12 @@ pre-initialization and initialization::
 advice execution::
   any exception that is in the `throws` clause of the advice.
 
-==== Advice precedence
+=== Advice precedence
 
 Multiple pieces of advice may apply to the same join point. In such
 cases, the resolution order of the advice is based on advice precedence.
 
-===== Determining precedence
+==== Determining precedence
 
 There are a number of rules that determine whether a particular piece of
 advice has precedence over another when they advise the same join point.
@@ -1438,7 +1438,7 @@ aspect A {
 
 such circularities will result in errors signalled by the compiler.
 
-===== Effects of precedence
+==== Effects of precedence
 
 At a particular join point, advice is ordered by precedence.
 
@@ -1466,7 +1466,7 @@ Running `after` advice will run the advice of next precedence, or the
 computation under the join point if there is no further advice. Then the
 body of the advice will run.
 
-==== Reflective access to the join point
+=== Reflective access to the join point
 
 Three special variables are visible within bodies of advice and within
 `if()` pointcut expressions: `thisJoinPoint`, `thisJoinPointStaticPart`,
@@ -1503,14 +1503,14 @@ to `thisJoinPoint` is `org.aspectj.lang.JoinPoint`, while
 `org.aspectj.lang.JoinPoint.StaticPart`.
 
 [[semantics-declare]]
-=== Static crosscutting
+== Static crosscutting
 
 Advice declarations change the behavior of classes they crosscut, but do
 not change their static type structure. For crosscutting concerns that
 do operate over the static structure of type hierarchies, AspectJ
 provides inter-type member declarations and other `declare` forms.
 
-==== Inter-type member declarations
+=== Inter-type member declarations
 
 AspectJ allows the declaration of members by aspects that are associated
 with other types.
@@ -1576,7 +1576,7 @@ inter-type field declaration, refers to the `OnType` object rather than
 to the aspect type; it is an error to access `this` in such a position
 from a `static` inter-type member declaration.
 
-==== Access modifiers
+=== Access modifiers
 
 Inter-type member declarations may be `public` or `private`, or have default
 (package-protected) visibility. AspectJ does not provide protected
@@ -1604,7 +1604,7 @@ public interface. This is illegal because it would say that a public
 interface has a constraint that only non-public implementors must
 fulfill. This would not be compatible with Java's type system.
 
-==== Conflicts
+=== Conflicts
 
 Inter-type declarations raise the possibility of conflicts among locally
 declared members and inter-type members. For example, assuming
@@ -1663,7 +1663,7 @@ This is true both when the precedence is declared explicitly with
 `declare precedence` as well as when when sub-aspects implicitly have
 precedence over their super-aspect.
 
-==== Extension and Implementation
+=== Extension and Implementation
 
 An aspect may change the inheritance hierarchy of a system by changing
 the superclass of a type or adding a superinterface onto a type, with
@@ -1687,7 +1687,7 @@ aspect A {
 }
 ....
 
-==== Interfaces with members
+=== Interfaces with members
 
 Through the use of inter-type members, interfaces may now carry
 (non-public-static-final) fields and (non-public-abstract) methods that
@@ -1721,7 +1721,7 @@ when a new `E` is instantiated, the initializers run in this order:
 Object M C O N D Q P E
 ....
 
-==== Warnings and Errors
+=== Warnings and Errors
 
 An aspect may specify that a particular join point should never be
 reached.
@@ -1733,7 +1733,7 @@ If the compiler determines that a join point in `Pointcut` could
 possibly be reached, then it will signal either an error or warning, as
 declared, using the `String` for its message.
 
-==== Softened exceptions
+=== Softened exceptions
 
 An aspect may specify that a particular kind of exception, if thrown at
 a join point, should bypass Java's usual static exception checking
@@ -1790,7 +1790,7 @@ abstract aspect A {
 ....
 
 [[advice-precedence-cross]]
-==== Advice Precedence
+=== Advice Precedence
 
 An aspect may declare a precedence relationship between concrete aspects
 with the `declare precedence` form:
@@ -1844,7 +1844,7 @@ aspect CountEntry {
 }
 ....
 
-===== Various cycles
+==== Various cycles
 
 It is an error for any aspect to be matched by more than one TypePattern
 in a single decare precedence, so:
@@ -1868,7 +1868,7 @@ And a system in which both constraints are active may also be legal, so
 long as advice from `A` and `B` don't share a join point. So this is an
 idiom that can be used to enforce that `A` and `B` are strongly independent.
 
-===== Applies to concrete aspects
+==== Applies to concrete aspects
 
 Consider the following library aspects:
 
@@ -1922,7 +1922,7 @@ declare precedence: Logging+, Profiling+;
 
 are meaningful.
 
-==== Statically determinable pointcuts
+=== Statically determinable pointcuts
 
 Pointcuts that appear inside of `declare` forms have certain
 restrictions. Like other pointcuts, these pick out join points, but they
@@ -1943,17 +1943,17 @@ defined in terms of
 all of which can discriminate on runtime information.
 
 [[semantics-aspects]]
-=== Aspects
+== Aspects
 
 An aspect is a crosscutting type defined by the `aspect` declaration.
 
-==== Aspect Declaration
+=== Aspect Declaration
 
 The `aspect` declaration is similar to the `class` declaration in that
 it defines a type and an implementation for that type. It differs in a
 number of ways:
 
-===== Aspect implementation can cut across other types
+==== Aspect implementation can cut across other types
 
 In addition to normal Java class declarations such as methods and
 fields, aspect declarations can include AspectJ declarations such as
@@ -1961,45 +1961,45 @@ advice, pointcuts, and inter-type declarations. Thus, aspects contain
 implementation declarations that can can cut across other types
 (including those defined by other aspect declarations).
 
-===== Aspects are not directly instantiated
+==== Aspects are not directly instantiated
 
 Aspects are not directly instantiated with a new expression, with
 cloning, or with serialization. Aspects may have one constructor
 definition, but if so it must be of a constructor taking no arguments
 and throwing no checked exceptions.
 
-===== Nested aspects must be `static`
+==== Nested aspects must be `static`
 
 Aspects may be defined either at the package level, or as a `static`
 nested aspect -- that is, a `static` member of a class, interface, or
 aspect. If it is not at the package level, the aspect _must_ be defined
 with the `static` keyword. Local and anonymous aspects are not allowed.
 
-==== Aspect Extension
+=== Aspect Extension
 
 To support abstraction and composition of crosscutting concerns, aspects
 can be extended in much the same way that classes can. Aspect extension
 adds some new rules, though.
 
-===== Aspects may extend classes and implement interfaces
+==== Aspects may extend classes and implement interfaces
 
 An aspect, abstract or concrete, may extend a class and may implement a
 set of interfaces. Extending a class does not provide the ability to
 instantiate the aspect with a new expression: The aspect may still only
 define a null constructor.
 
-===== Classes may not extend aspects
+==== Classes may not extend aspects
 
 It is an error for a class to extend or implement an aspect.
 
-===== Aspects extending aspects
+==== Aspects extending aspects
 
 Aspects may extend other aspects, in which case not only are fields and
 methods inherited but so are pointcuts. However, aspects may only extend
 abstract aspects. It is an error for a concrete aspect to extend another
 concrete aspect.
 
-==== Aspect instantiation
+=== Aspect instantiation
 
 Unlike class expressions, aspects are not instantiated with `new`
 expressions. Rather, aspect instances are automatically created to cut
@@ -2015,7 +2015,7 @@ then by default the aspect is a singleton aspect. How an aspect is
 instantiated controls the form of the `aspectOf(..)` method defined on
 the concrete aspect class.
 
-===== Singleton Aspects
+==== Singleton Aspects
 
 * `aspect Id { ... }`
 * `aspect Id issingleton() { ... }`
@@ -2035,7 +2035,7 @@ chance to run at all such join points.
 the aspect `A`, so there will be one instantiation for each time `A` is
 loaded by a different classloader.)
 
-===== Per-object aspects
+==== Per-object aspects
 
 * `aspect Id perthis( Pointcut ) { ... }`
 * `aspect Id pertarget( Pointcut ) { ... }`
@@ -2062,7 +2062,7 @@ Both `perthis` and `pertarget` aspects may be affected by code the
 AspectJ compiler controls, as discussed in the xref:implementation.adoc#implementation[Implementation Notes]
 appendix.
 
-===== Per-control-flow aspects
+==== Per-control-flow aspects
 
 * `aspect Id percflow( Pointcut ) { ... }`
 * `aspect Id percflowbelow( Pointcut ) { ... }`
@@ -2076,7 +2076,7 @@ under that control flow. During each such flow of control, the static
 method `A.aspectOf()` will return an object of type `A`. An instance of
 the aspect is created upon entry into each such control flow.
 
-===== Aspect instantiation and advice
+==== Aspect instantiation and advice
 
 All advice runs in the context of an aspect instance, but it is possible
 to write a piece of advice with a pointcut that picks out a join point
@@ -2111,7 +2111,7 @@ compile time. If advice runs before its aspect is instantiated, AspectJ
 will throw a
 xref:../api/org/aspectj/lang/NoAspectBoundException.html[`org.aspectj.lang.NoAspectBoundException`].
 
-==== Aspect privilege
+=== Aspect privilege
 
 * `privileged aspect Id { ... }`
 
diff --git a/docs/release/README-1.1.adoc b/docs/release/README-1.1.adoc
index d846cff81..f78e4ce70 100644
--- a/docs/release/README-1.1.adoc
+++ b/docs/release/README-1.1.adoc
@@ -1,5 +1,5 @@
 [[readme-1_1]]
-== AspectJ 1.1
+= AspectJ 1.1
 
 _© Copyright 2002 Palo Alto Research Center, Incorporated, 2003
 Contributors. All rights reserved._
@@ -32,7 +32,7 @@ xref:#knownLimitations[known limitations].
 '''''
 
 [[language]]
-=== The Language
+== The Language
 
 AspectJ 1.1 is a slightly different language than AspectJ 1.0. In all
 but a few cases, programs written in AspectJ 1.0 should compile
@@ -119,7 +119,7 @@ specifier] in this release, but it may well be in a future release.
 '''''
 
 [[compiler]]
-=== The Compiler
+== The Compiler
 
 The compiler for AspectJ 1.1 is different than the compiler for AspectJ
 1.0. While this document describes the differences in the compiler, it's
@@ -194,7 +194,7 @@ xref:#ONE_FOUR_METHOD_SIGNATURES[the -1.4 flag].
 '''''
 
 [[tools]]
-=== Support Tools
+== Support Tools
 
 This release includes an Ant task for old-style 1.0 build scripts, a new
 task for all the new compiler options, and a CompilerAdapter to support
@@ -224,7 +224,7 @@ support is available.
 '''''
 
 [[runtime]]
-=== The Runtime Library
+== The Runtime Library
 
 This release has minor additions to the runtime library classes. As with
 any release, you should compile and run with the runtime library that
@@ -240,7 +240,7 @@ and will always return 0.
 '''''
 
 [[devenv]]
-=== The AJDE Tools
+== The AJDE Tools
 
 The AspectJ Browser supports incremental compilation and running
 programs. AJDE for JBuilder, AJDE for NetBeans, and AJDE for Emacs are
@@ -250,7 +250,7 @@ the batch-build mode of the new compiler.
 '''''
 
 [[sources]]
-=== The Sources and the Licenses
+== The Sources and the Licenses
 
 The AspectJ tools sources are available under the
 https://www.eclipse.org/org/documents/epl-2.0/EPL-2.0.txt[Eclipse Public
@@ -260,7 +260,7 @@ more information, see the FAQ entry on building sources.
 '''''
 
 [[distribution]]
-=== The AspectJ distribution
+== The AspectJ distribution
 
 AspectJ 1.0 had many distributions - for the tools, the documentation,
 each IDE support package, their respective sources, and the Ant tasks -
@@ -278,10 +278,10 @@ SourceForge projects.
 '''''
 
 [[details]]
-=== Details of some language and compiler changes
+== Details of some language and compiler changes
 
 [[ASPECT_INSTANTIATION_AND_ADVICE]]
-==== Aspect Instantiation and Advice
+=== Aspect Instantiation and Advice
 
 In AspectJ 1.0.6, we made an effort to hide some complications with
 Aspect instantiation from the user. In particular, the following code
@@ -347,7 +347,7 @@ both of the above programs will throw
 org.aspectj.lang.NoAspectBoundException.
 
 [[THROWS_PATTERN]]
-==== Matching based on throws
+=== Matching based on throws
 
 Type patterns may now be used to pick out methods and constructors based
 on their throws clauses. This allows the following two kinds of
@@ -409,7 +409,7 @@ because method m's throws clause declares the it throws some exception
 which does not match IOException, i.e. RuntimeException.
 
 [[NEW_PCDS]]
-==== New kinded pointcut designators
+=== New kinded pointcut designators
 
 AspectJ 1.0 does not provide kinded pointcut designators for two (rarely
 used) join points: preinitialization (the code that runs before a super
@@ -427,7 +427,7 @@ join points where the initialization process is entered through
 `ConstructorPattern`.
 
 [[PER_TYPE]]
-==== New pertype aspect specifier (not in 1.1)
+=== New pertype aspect specifier (not in 1.1)
 
 We strongly considered adding a pertype aspect kind to 1.1. This is
 somewhat motivated by the new
@@ -471,7 +471,7 @@ the most common uses of this idiom.
 In any case, this feature will not be in AspectJ 1.1.
 
 [[SINGLE_INTERCLASS_TARGET]]
-==== One target for intertype declarations
+=== One target for intertype declarations
 
 Intertype declarations (once called "introductions") in AspectJ 1.1 can
 only have one target type. So the following code intended to declare
@@ -506,7 +506,7 @@ xref:#PER_TYPE[pertype proposal] provides this functionality in a much
 more usable form.
 
 [[UNAVAILABLE_JOIN_POINTS]]
-==== No initializer execution join points
+=== No initializer execution join points
 
 AspectJ 1.1 does not consider initializer execution a principled join
 point. The collection of initializer code (the code that sets fields
@@ -515,14 +515,14 @@ something that makes sense only in Java source code, not in Java
 bytecode.
 
 [[AFTER_HANDLER]]
-==== No after or around advice on handler join points
+=== No after or around advice on handler join points
 
 The end of an exception handler is underdetermined in bytecode, so ajc
 will not implement after or around advice on handler join points,
 instead signaling a compile-time error.
 
 [[CONSTRUCTOR_EXECUTION_IS_BIGGER]]
-==== Initializers run inside constructor execution join points
+=== Initializers run inside constructor execution join points
 
 The code generated by the initializers in Java source code now runs
 inside of constructor execution join points. This changes how before
@@ -560,7 +560,7 @@ assume incomplete object initialization, since the constructor has not
 yet run.
 
 [[INTER_TYPE_FIELD_INITIALIZERS]]
-==== Inter-type field initializers
+=== Inter-type field initializers
 
 The initializer, if any, of an inter-type field definition runs before
 the class-local initializers of its target class.
@@ -588,7 +588,7 @@ method (thus incrementing the method count) and then the field was reset
 to zero after the constructor was done.
 
 [[WITHIN_MEMBER_TYPES]]
-==== Small limitations of the within pointcut
+=== Small limitations of the within pointcut
 
 Because of the guarantees made (and not made) by the Java classfile
 format, there are cases where AspectJ 1.1 cannot guarantee that the
@@ -627,13 +627,13 @@ We believe the non-guarantee is small, and we haven't verified that it
 is a problem in practice.
 
 [[WITHIN_CODE]]
-==== Small limitations of the withincode pointcut
+=== Small limitations of the withincode pointcut
 
 The withincode pointcut has similar issues to those described above for
 within.
 
 [[INSTANCEOF_ON_WILD]]
-==== Can't do instanceof matching on type patterns with wildcard
+=== Can't do instanceof matching on type patterns with wildcard
 
 The pointcut designators this, target and args specify a dynamic test on
 their argument. These tests can not be performed on type patterns with
@@ -680,7 +680,7 @@ match any code lexically within one of your classes or a subtype
 thereof. This is often a good choice.
 
 [[NO_SOURCE_COLUMN]]
-==== SourceLocation.getColumn()
+=== SourceLocation.getColumn()
 
 The Java .class file format contains information about the source file
 and line numbers of its contents; however, it has no information about
@@ -690,7 +690,7 @@ thisJoinPoint.getSourceLocation().getColumn() will be marked as
 deprecated by the compiler, and will always return 0.
 
 [[ASPECT_PRECEDENCE]]
-==== Aspect precedence
+=== Aspect precedence
 
 AspectJ 1.1 has a new declare form:
 
@@ -713,7 +713,7 @@ declare precedence: *..*Security*, Logging+, *;
 In the TypePatternList, the wildcard * means "any type not matched by
 another type in the declare precedence".
 
-===== Various cycles
+==== Various cycles
 
 It is an error for any aspect to be matched by more than one TypePattern
 in a single declare precedence, so:
@@ -737,7 +737,7 @@ And a system in which both constraints are active may also be legal, so
 long as advice from A and B don't share a join point. So this is an
 idiom that can be used to enforce that A and B are strongly independent.
 
-===== Applies to concrete aspects
+==== Applies to concrete aspects
 
 Consider the following library aspects:
 
@@ -783,7 +783,7 @@ simple:
 declare precedence: MyLogging, MyProfiling;
 ....
 
-===== Changing order of advice for sub-aspects
+==== Changing order of advice for sub-aspects
 
 By default, advice in a sub-aspect has more precedence than advice in a
 super-aspect. One use of the AspectJ 1.0 dominates form was to change
@@ -813,7 +813,7 @@ matters for concrete aspects. Thus, if you want to regain this kind of
 precedence change, you will need to refactor your aspects.
 
 [[SOURCEROOT]]
-==== The -sourceroots option
+=== The -sourceroots option
 
 The AspectJ 1.1 compiler now accepts a -sourceroots option used to pass
 all .java files in particular directories to the compiler. It takes
@@ -835,7 +835,7 @@ This option may be used in conjunction with lst files, listing .java
 files on the command line, and the -injars option.
 
 [[BYTECODE_WEAVING]]
-==== The -injars option
+=== The -injars option
 
 The AspectJ 1.1 compiler now accepts an -injars option used to pass all
 .class files in a particular jar file to the compiler. It takes either a
@@ -862,7 +862,7 @@ This option may be used in conjunction with lst files, listing .java
 files on the command line, and the -sourceroots option.
 
 [[OUTJAR]]
-==== The -outjar option
+=== The -outjar option
 
 The -outjar option takes the name of a jar file into which the results
 of the compilation should be put. For example:
@@ -875,7 +875,7 @@ ajc -injars myBase.jar MyTracing.java -outjar myTracedBase.jar
 No meta information is placed in the output jar file.
 
 [[INCREMENTAL]]
-==== Incremental compilation
+=== Incremental compilation
 
 The AspectJ 1.1 compiler now supports incremental compilation. When ajc
 is called with the -incremental option, it must also be passed a
@@ -884,12 +884,12 @@ Once the initial compile is done, ajc waits for console input. Every
 time it reads a new line (i.e., every time the user hits return) ajc
 recompiles those input files that need recompiling.
 
-===== Limitations
+==== Limitations
 
 This new functionality is still only lightly tested.
 
 [[XNOWEAVE]]
-==== -XnoWeave, a compiler option to suppress weaving
+=== -XnoWeave, a compiler option to suppress weaving
 
 The -XnoWeave option suppresses weaving, and generates classfiles and
 that can be passed to ajc again (through the -injars option) to generate
@@ -903,7 +903,7 @@ cases for unwoven classfiles, but we've moved the flag to experimental
 status.
 
 [[BINARY_ASPECTS]]
-==== -aspectpath, working with aspects in .class/.jar form
+=== -aspectpath, working with aspects in .class/.jar form
 
 When aspects are compiled into classfiles, they include all information
 necessary for the ajc compiler to weave their advice and deal with their
@@ -914,7 +914,7 @@ and any aspects that are found will be enabled during the compilation.
 The binary forms of this aspects will be untouched.
 
 [[NO_CALLEE_SIDE_CALL]]
-==== Callee-side call join points
+=== Callee-side call join points
 
 The 1.0 implementation of AspectJ, when given:
 
@@ -1023,7 +1023,7 @@ How will this affect developers?
 calling code or use the execution PCD instead.
 
 [[OTHER_X_OPTIONS]]
-==== Various -X options
+=== Various -X options
 
 The AspectJ 1.0 compiler supported a number of options that started with
 X, for "experimental". Some of them will not be supported in 1.1, either
@@ -1042,7 +1042,7 @@ because we're now always using (what we believe to be) safe prefixes.
 * -Xlint: Still supported, with xref:#XLINT[various options].
 
 [[ERROR_MESSAGES]]
-==== Some confusing error messages
+=== Some confusing error messages
 
 Building on the eclipse compiler has given us access to a very
 sophisticated problem reporting system as well as highly optimized error
@@ -1053,7 +1053,7 @@ single small syntax error will produce dozens of other messages. Please
 report any very confusing error messages as bugs.
 
 [[MESSAGE_CONTEXT]]
-==== Source code context is not shown for errors and warnings detected during bytecode weaving
+=== Source code context is not shown for errors and warnings detected during bytecode weaving
 
 For compiler errors and warnings detected during bytecode weaving,
 source code context will not be displayed. In particular, for declare
@@ -1064,7 +1064,7 @@ available, we might specify the signature of the offending code. For
 more information, see bug 31724.
 
 [[XLINT]]
-==== The -Xlint option
+=== The -Xlint option
 
 `-Xlint:ignore,error,warning` will set the level for all Xlint warnings.
 `-Xlint`, alone, is an abbreviation for `-Xlint:warning`.
@@ -1081,26 +1081,26 @@ potentially unsafe casts used by very polymorphic uses of proceed in
 around advice.
 
 [[NO_SOURCE]]
-==== Source-specific options
+=== Source-specific options
 
 Because AspectJ 1.1 does not generate source code after weaving, the
 source-code-specific options -preprocess, -usejavac, -nocomment and
 -workingdir options are meaningless and so not supported.
 
 [[NO_STRICT_LENIENT]]
-==== The -strict and -lenient options
+=== The -strict and -lenient options
 
 Because AspectJ 1.1 uses the Eclipse compiler, which has its own
 mechanism for changing strictness, we no longer support the -strict and
 -lenient options.
 
 [[NO_PORTING]]
-==== The -porting option
+=== The -porting option
 
 AspectJ 1.1 does not have a -porting option.
 
 [[_13_REQUIRED]]
-==== J2SE 1.3 required
+=== J2SE 1.3 required
 
 Because we build on Eclipse, the compiler will no longer run under J2SE
 1.2. You must run the compiler (and all tools based on the compiler)
@@ -1109,7 +1109,7 @@ run on Java 1.1 or later VM's if compiled against the correct runtime
 libraries.
 
 [[DEFAULT_CONSTRUCTOR_CONFLICT]]
-==== Default constructors
+=== Default constructors
 
 AspectJ 1.1 does not allow the inter-type definition of a zero-argument
 constructor on a class with a visible default constructor. So this is no
@@ -1135,7 +1135,7 @@ classfiles. Therefore, it was an oversight that AspectJ 1.0.6 allowed
 such an "overriding" inter-type constructor definition.
 
 [[SUPER_IFACE_INITS]]
-==== Initialization join points for super-interfaces
+=== Initialization join points for super-interfaces
 
 In AspectJ, interfaces may have non-static members due to inter-type
 declarations. Because of this, the semantics of AspectJ defines the
@@ -1182,7 +1182,7 @@ for its superinterfaces.
 ____
 
 [[VOID_FIELD_SET]]
-==== Field Set Join Points
+=== Field Set Join Points
 
 In AspectJ 1.0.6, the join point for setting a field F had, as a return
 type, F's type. This was "java compatible" because field assignment in
@@ -1233,7 +1233,7 @@ is the last possibility to make the semantics more useful, we have made
 set join points have a void return type in 1.1.
 
 [[XNOINLINE]]
-==== The -XnoInline Option
+=== The -XnoInline Option
 
 The `-XnoInline` option to indicate that no inlining of any kind should
 be done. This is purely a compiler pragma: No program semantics (apart
@@ -1241,7 +1241,7 @@ from stack traces) will be changed by the presence or absence of this
 option.
 
 [[TARGET_TYPES_MADE_PUBLIC]]
-==== Target types made public
+=== Target types made public
 
 Even in 1.0.6, the AspectJ compiler has occasionally needed to convert
 the visibility of a package-level class to a public one. This was
@@ -1260,7 +1260,7 @@ not encounter them as such a concern when they were done in the 1.0.6
 implementation.
 
 [[STRINGBUFFER]]
-==== String + now advised
+=== String + now advised
 
 In Java, the + operator sometimes results in StringBuffer objects being
 created, appended to, and used to generate a new String. Thus,
@@ -1319,7 +1319,7 @@ call(* *(int)) && args(i) && !target(StringBuffer)
 ....
 
 [[ONE_FOUR_METHOD_SIGNATURES]]
-==== The -1.4 flag and method signatures
+=== The -1.4 flag and method signatures
 
 Consider the following aspect
 
@@ -1358,7 +1358,7 @@ a call site, but only want to know the dynamic instanceof behavior which
 is what the target matching will handle.
 
 [[knownLimitations]]
-=== Known limitations
+== Known limitations
 
 The AspectJ 1.1.0 release contains a small number of known limitations
 relative to the AspectJ 1.1 language. For the most up-to-date
diff --git a/docs/release/README-1.2.1.adoc b/docs/release/README-1.2.1.adoc
index 04cb6e831..d90d232ed 100644
--- a/docs/release/README-1.2.1.adoc
+++ b/docs/release/README-1.2.1.adoc
@@ -1,4 +1,4 @@
-== AspectJ 1.2.1
+= AspectJ 1.2.1
 
 _© Copyright 2004 Contributors. All rights reserved._
 
@@ -25,7 +25,7 @@ of ajc
 See the link:changes.html[changes document] for more details, or
 xref:#allchanges[all the changes] as detailed in the bugzilla database.
 
-=== Weaver Informational Messages
+== Weaver Informational Messages
 
 The AspectJ 1.2.1 compiler can produce informational messages about the
 weaving process. To see these messages, use the -showWeaveInfo compiler
@@ -48,7 +48,7 @@ Type 'tjp.Demo' (Demo.java:34) advised by around advice from 'tjp.GetInfo'
 (GetInfo.java:26) [RuntimeTest=true]
 ....
 
-=== Dump Support
+== Dump Support
 
 In the event of a compiler crash, AspectJ 1.2.1 will produce a dump file
 giving important information about the state of the compiler at the time
@@ -61,11 +61,11 @@ detected, the AspectJ 1.2.1 compiler can also be requested to create a
 dump file on detection of a compilation error. Set the property
 org.aspectj.weaver.Dump.condition=error to enable this behaviour.
 
-=== JDT Compiler Version
+== JDT Compiler Version
 
 AspectJ 1.2.1 is based on the Eclipse 3.0 final JDT compiler.
 
-=== Line Number Information for Join Points
+== Line Number Information for Join Points
 
 For source files compiled by ajc (as opposed to binary inputs to the
 compiler compiled with some other java compiler), ajc now emits better
@@ -75,7 +75,7 @@ example by a declare error or declare warning statement), ajc 1.2.1
 reports the first line number of the declaration, as opposed to the line
 number of the first line of code in the body.
 
-=== Runtime Performance
+== Runtime Performance
 
 AspectJ 1.2.1 contains a small number of runtime performance
 optimisations, including optimisations of if(true) and if(false)
@@ -87,7 +87,7 @@ programs compiled under AspectJ 1.2.1 and that make heavy use of cflow
 will run significantly faster. Thanks to the abc compiler team for
 detecting this performance related bug and for piloting the fix.
 
-=== String Concatentation in Declare Error/Warning Statements
+== String Concatentation in Declare Error/Warning Statements
 
 String concatentation in declare error and warning statements is now
 supported. For example, you can write:
@@ -99,7 +99,7 @@ declare warning : jdbcCall() && !inDataLayer()
                   "outside of the data layer.";
 ....
 
-=== Load-time Weaving Support
+== Load-time Weaving Support
 
 The AspectJ 1.2.1 distribution contains a new jar in the lib directory,
 aspectjweaver.jar, that contains the subset of aspectjtools.jar needed
@@ -112,7 +112,7 @@ doc/examples/ltw directory in the 1.2 distribution has been moved into
 the regular bin directory. See xref:README-1.2.adoc[README-1.2] for
 details of using this script.
 
-=== Binary Compatibility
+== Binary Compatibility
 
 AspectJ 1.2.1 introduces a backwards-incompatible change to the class
 file format generated by the AspectJ compiler. Classes generated by ajc
@@ -127,7 +127,7 @@ comes with the distribution you used to build your application.
 '''''
 
 [[allchanges]]
-=== All changes are listed in the bug database
+== All changes are listed in the bug database
 
 For a complete list of changes in the 1.2.1 release, search for
 `target 1.2.1` in the bug database:
diff --git a/docs/release/README-1.2.adoc b/docs/release/README-1.2.adoc
index 5aa96f30e..b68ebafb3 100644
--- a/docs/release/README-1.2.adoc
+++ b/docs/release/README-1.2.adoc
@@ -1,4 +1,4 @@
-== AspectJ 1.2
+= AspectJ 1.2
 
 _© Copyright 2003,2004 Contributors. All rights reserved._
 
@@ -25,7 +25,7 @@ readers to the bug database for xref:#allchanges[all the changes].
 '''''
 
 [[compiler]]
-=== The Compiler
+== The Compiler
 
 Compared to AspectJ 1.1.1, the AspectJ 1.2 compiler...
 
@@ -56,7 +56,7 @@ ajc].
 '''''
 
 [[tools]]
-=== Support Tools
+== Support Tools
 
 AspectJ 1.2 contains two important changes to the supporting tools:
 
@@ -67,7 +67,7 @@ command-line.
 '''''
 
 [[runtime]]
-=== The Runtime Library
+== The Runtime Library
 
 This release has minor updates to the runtime library classes. As with
 any release, you should compile and run with the runtime library that
@@ -86,7 +86,7 @@ heap usage for multi-threaded applications that use cflow.
 '''''
 
 [[devenv]]
-=== The AJDE Tools
+== The AJDE Tools
 
 The AJDE based tools for JBuilder, NetBeans and Emacs continue to be
 independent SourceForge projects. The AspectJ 1.2 distribution includes
@@ -104,10 +104,10 @@ https://www.eclipse.org/ajdt[AJDT project website].
 '''''
 
 [[details]]
-=== Details of some compiler changes
+== Details of some compiler changes
 
 [[WEAVE_TIME]]
-==== Compilation (weave) times reduced.
+=== Compilation (weave) times reduced.
 
 Our benchmark suite shows that AspectJ 1.2 is at least twice as fast in
 the weaving phase as AspectJ 1.1.1 for matches based on a variety of
@@ -123,7 +123,7 @@ performance and memory usage. Experiments forcing GC showed that we can
 achieve about a 20% memory usage reduction in this manner if needed.
 
 [[LAZY_TJP]]
-==== The -XlazyTjp option.
+=== The -XlazyTjp option.
 
 Under AspectJ 1.1.1, if the body of an advice contained a reference to a
 non-statically determinable portion of `thisJoinPoint` (such as for
@@ -161,7 +161,7 @@ issues. The optimization is disabled at join points advised by around
 advice, and an Xlint warning will be displayed in these cases.
 
 [[INCREMENTAL]]
-==== Improvements to incremental compilation.
+=== Improvements to incremental compilation.
 
 AspectJ 1.2 provides more complete incremental compilation support than
 AspectJ 1.1.1. Firstly, incremental compilation resulting from a change
@@ -179,7 +179,7 @@ detected, but will trigger a full rebuild, as will any change to the
 paths used to control compilation.
 
 [[ERROR_MESSAGES]]
-==== Improved error messages.
+=== Improved error messages.
 
 AspectJ 1.1.1 did not provide source context information for messages
 produced during the weaving phase, even in the case where source files
@@ -234,7 +234,7 @@ file called `BadClass.java`, contains a join point
 line 5 of the file `DeclareError.java`.
 
 [[LINT]]
-==== New lint warnings.
+=== New lint warnings.
 
 Consider the program:
 
@@ -326,7 +326,7 @@ process of weaving makes an incompatible change to a serializable class
 (for example, through the addition of an inter-type declared field).
 
 [[REWEAVABLE]]
-==== The -Xreweavable option.
+=== The -Xreweavable option.
 
 The new `-Xreweavable` option produces class files that contain enough
 additional information in them that they can be rewoven. In time we hope
@@ -347,7 +347,7 @@ during weaving be present in the system during a reweave. An error will
 be issued if any are missing.
 
 [[INPATH]]
-==== The -inpath option.
+=== The -inpath option.
 
 The new `-inpath` option replaces the `-injars` option (which is still
 supported for backwards compatibility). It allows both directories and
@@ -357,7 +357,7 @@ result of building one project to become binary input to the compilation
 of a second project.
 
 [[COMPLIANCE]]
-==== The default compliance mode of the compiler has changed from -1.3 to -1.4.
+=== The default compliance mode of the compiler has changed from -1.3 to -1.4.
 
 The default AspectJ compiler compliance level is now 1.4 (whereas in
 previous releases the default compliance level was 1.3). This has a
@@ -432,7 +432,7 @@ actual type of the receiver.
 '''''
 
 [[AJDOC]]
-==== The ajdoc tool makes a comeback in the AspectJ 1.2 distribution.
+=== The ajdoc tool makes a comeback in the AspectJ 1.2 distribution.
 
 `ajdoc` (the AspectJ replacement for the `javadoc` tool) is once again
 included in the AspectJ distribution. The `ajdoc` tool produces regular
@@ -460,7 +460,7 @@ image:images/ajdoc1.JPG[image]
 image:images/ajdoc2.JPG[image]
 
 [[LTW]]
-==== A sample script is supplied that supports load-time weaving from the command-line
+=== A sample script is supplied that supports load-time weaving from the command-line
 
 The AspectJ 1.2 distribution ships with sample scripts for Windows and
 Unix platforms that exploit AspectJ's binary weaving capabilities at
@@ -541,7 +541,7 @@ welcome contributions from users to improve these scripts.
 '''''
 
 [[SOFTEX]]
-==== SoftException now supports getCause()
+=== SoftException now supports getCause()
 
 `org.aspectj.lang.SoftException` now supports the `getCause()` method,
 which returns the original exception wrapped by the `SoftException`.
@@ -549,7 +549,7 @@ This means that exception chains will print correctly on 1.4 and later
 JREs.
 
 [[LTW2]]
-==== org.aspectj.weaver.tools package added
+=== org.aspectj.weaver.tools package added
 
 A new set of public APIs are exported by the
 link:api/index.html[`org.aspectj.weaver.tools`] package that can be used
@@ -561,7 +561,7 @@ example of how to use these APIs, see the
 '''''
 
 [[allchanges]]
-=== All changes are listed in the bug database
+== All changes are listed in the bug database
 
 For a complete list of changes in the 1.2 release, search for
 `target 1.2` in the bug database:
diff --git a/docs/release/README-1.5.0.adoc b/docs/release/README-1.5.0.adoc
index e3f7c1196..d6bd837f0 100644
--- a/docs/release/README-1.5.0.adoc
+++ b/docs/release/README-1.5.0.adoc
@@ -1,13 +1,13 @@
-== AspectJ 5
+= AspectJ 5
 
 _© Copyright 2005 Contributors. All rights reserved._
 
 AspectJ 5 introduces several important changes to the language and tools
 in order to support Java 5 and extend the capabilities of AspectJ in
-general. For language changes, see xref:../../adk15notebook/adk15notebook.adoc[AspectJ 5 Developer's Notebook]. For tools changes, see the
-link:devguide/index.html[AspectJ Development Environment Guide],
-especially the section on link:devguide/ltw.html[Load-time weaving]. The
-changes are summarized in the faq.html#q:aspectj5features[FAQ entry on
+general. For language changes, see xref:../adk15notebook/index.adoc[AspectJ 5 Developer's Notebook]. For tools changes, see the
+xref:../devguide/index.adoc[AspectJ Development Environment Guide],
+especially the section on xref:../devguide/ltw.adoc[Load-time weaving]. The
+changes are summarized in the xref:../faq/faq.adoc#AspectJ5[FAQ entry on
 AspectJ 5].
 
 Some of the other documentation has not been updated for AspectJ 5. For
@@ -16,4 +16,4 @@ https://eclipse.org/aspectj/doc/next/index.html, linked off
 https://eclipse.org/aspectj/docs.php[the AspectJ documentation home page].
 
 For information on bug fixes in AspectJ 5 v1.5.0, see the
-link:changes.html[changes] document.
+xref:changes.adoc[changes] document.
diff --git a/docs/release/README-1.5.1.adoc b/docs/release/README-1.5.1.adoc
index bc513d512..724d4ecbb 100644
--- a/docs/release/README-1.5.1.adoc
+++ b/docs/release/README-1.5.1.adoc
@@ -1,4 +1,4 @@
-== AspectJ 5 v1.5.1 Readme
+= AspectJ 5 v1.5.1 Readme
 
 _© Copyright 2006 Contributors. All rights reserved._
 
diff --git a/docs/release/README-1.5.2.adoc b/docs/release/README-1.5.2.adoc
index b903a9841..fa905a0de 100644
--- a/docs/release/README-1.5.2.adoc
+++ b/docs/release/README-1.5.2.adoc
@@ -1,4 +1,4 @@
-== AspectJ 5 v1.5.2 Readme
+= AspectJ 5 v1.5.2 Readme
 
 _© Copyright 2006 Contributors. All rights reserved._
 
diff --git a/docs/release/README-1.5.3.adoc b/docs/release/README-1.5.3.adoc
index d5d9a228c..280181aeb 100644
--- a/docs/release/README-1.5.3.adoc
+++ b/docs/release/README-1.5.3.adoc
@@ -1,4 +1,4 @@
-== AspectJ 5 v1.5.3 Readme
+= AspectJ 5 v1.5.3 Readme
 
 _© Copyright 2006 Contributors. All rights reserved._
 
@@ -9,7 +9,7 @@ bugzilla query].
 
 Notable changes since the 1.5.2 release include: +
 
-=== Pipeline compilation - https://bugs.eclipse.org/bugs/show_bug.cgi?id=146781[146781]
+== Pipeline compilation - https://bugs.eclipse.org/bugs/show_bug.cgi?id=146781[146781]
 
 Until this release, the memory profile for AspectJ looked like this
 (time is along the X axis, memory usage is the Y axis)
@@ -74,7 +74,7 @@ with memory. These savings will affect any code built from source: on
 the command line, in Ant, or in AJDT. It will not affect binary weaving
 - that is a future enhancement.
 
-=== Serviceability - https://bugs.eclipse.org/bugs/show_bug.cgi?id=150487[150487]
+== Serviceability - https://bugs.eclipse.org/bugs/show_bug.cgi?id=150487[150487]
 
 As AspectJ grows in popularity, we find that it is becoming more
 difficult for users to come up with the small testcases that recreate
@@ -87,9 +87,9 @@ https://www.eclipse.org/aspectj/doc/released/pdguide/index.html[documentation]
 on how to configure these new features. Don't be surprised if you get
 asked for an AspectJ trace on a future bug report!
 
-=== LTW enhancements
+== LTW enhancements
 
-==== User and System Configuration Files - https://bugs.eclipse.org/bugs/show_bug.cgi?id=149289[149289]
+=== User and System Configuration Files - https://bugs.eclipse.org/bugs/show_bug.cgi?id=149289[149289]
 
 The `-outxml` option now generates a file named `META-INF/aop-ajc.xml`.
 This no longer clashes with a user defined `META-INF/aop.xml`
@@ -97,11 +97,11 @@ configuration file. Both file names along with an OSGi-friendly
 `org/aspectj/aop.xml` (which can also be signed) are used by default to
 configure LTW.
 
-==== Weaving Concrete Aspects Defined in aop.xml - https://bugs.eclipse.org/bugs/show_bug.cgi?id=132080[132080]
+=== Weaving Concrete Aspects Defined in aop.xml - https://bugs.eclipse.org/bugs/show_bug.cgi?id=132080[132080]
 
 Concrete aspects defined using aop.xml are now exposed for weaving.
 
-=== Pertypewithin enhancement - https://bugs.eclipse.org/bugs/show_bug.cgi?id=123423[123423]
+== Pertypewithin enhancement - https://bugs.eclipse.org/bugs/show_bug.cgi?id=123423[123423]
 
 It is now possible to ask an instance of a ptw aspect which type it is
 'attached' to. The method:
diff --git a/docs/release/README-1.5.4.adoc b/docs/release/README-1.5.4.adoc
index 7c8fa50cc..f301664c8 100644
--- a/docs/release/README-1.5.4.adoc
+++ b/docs/release/README-1.5.4.adoc
@@ -1,4 +1,4 @@
-== AspectJ 5 v1.5.4 Readme
+= AspectJ 5 v1.5.4 Readme
 
 _© Copyright 2006 Contributors. All rights reserved._
 
diff --git a/docs/release/README-1.6.0.adoc b/docs/release/README-1.6.0.adoc
index 5e37c8efb..7ad1d7827 100644
--- a/docs/release/README-1.6.0.adoc
+++ b/docs/release/README-1.6.0.adoc
@@ -1,8 +1,8 @@
-== AspectJ 1.6.0
+= AspectJ 1.6.0
 
 _© Copyright 2008 Contributors. All rights reserved._
 
-=== AspectJ v1.6.0 - 23 Apr 2008
+== AspectJ v1.6.0 - 23 Apr 2008
 
 For the complete list of every issue addressed since the last full
 release, see
@@ -11,12 +11,12 @@ bugzilla link].
 
 Some of the highlights of 1.6.0 are:
 
-==== Upgrade to a Java 1.6 compiler
+=== Upgrade to a Java 1.6 compiler
 
 AspectJ1.6.0 upgrades the internal Eclipse compiler level to version
 785_R33x - a Java 1.6 level compiler
 
-==== Better incremental compilation support in the IDE
+=== Better incremental compilation support in the IDE
 
 Changes under https://bugs.eclipse.org/bugs/show_bug.cgi?id=221427[bug
 221427] mean that the compiler is better able to maintain incremental
@@ -28,7 +28,7 @@ findings can be seen in
 https://dev.eclipse.org/mhonarc/lists/aspectj-users/msg09002.html[this
 mailing list post].
 
-==== Parameter annotation matching
+=== Parameter annotation matching
 
 Parameter matching is possible for constructors and methods. The use of
 parentheses around the parameter types in a method signature determine
@@ -88,7 +88,7 @@ Join point 'method-execution(void C.goo(java.lang.String))' in Type 'C' (A.java:
 
 The first piece of advice matched both methods. The second only matched `goo()`.
 
-==== Annotation Value Matching
+=== Annotation Value Matching
 
 This allows static matching of the values of an annotation - if the
 matching is done statically at weave time, it is possible to avoid some
@@ -155,13 +155,13 @@ Matching is currently allowed on all annotation value types *except*
 class and array. Also it is not currently supported for parameter
 annotation values.
 
-==== Changes since release candidate
+=== Changes since release candidate
 
 The only fix 1.6.0 final includes beyond the release candidate is a
 multi-threading problem in the weaver -
 https://bugs.eclipse.org/bugs/show_bug.cgi?id=227029[bug 227029].
 
-==== Releases leading up to AspectJ 1.6.0
+=== Releases leading up to AspectJ 1.6.0
 
 AspectJ v1.6.0rc1- 16 Apr 2008
 
diff --git a/docs/release/README-1.6.1.adoc b/docs/release/README-1.6.1.adoc
index 5a9009cc8..71980170a 100644
--- a/docs/release/README-1.6.1.adoc
+++ b/docs/release/README-1.6.1.adoc
@@ -1,4 +1,4 @@
-== AspectJ 1.6.1
+= AspectJ 1.6.1
 
 _© Copyright 2008 Contributors. All rights reserved._
 
@@ -21,14 +21,14 @@ implemented]
 
 '''''
 
-=== Refactored (https://bugs.eclipse.org/bugs/show_bug.cgi?id=231396[bug 231396])
+== Refactored (https://bugs.eclipse.org/bugs/show_bug.cgi?id=231396[bug 231396])
 
 The bugzilla entry goes into more specifics on what has changed, the end
 result is that aspectjweaver.jar has had around 275 classes removed
 (about 25%) and has slimmed down by 350k (about 20%). In terms of
 performance for different scenarios:
 
-==== Straight compilation
+=== Straight compilation
 
 The refactoring effort has been focused on the weaver component, hence
 there is limited impact on the performance of source compilation but
@@ -45,7 +45,7 @@ join points)
 
 image:images/perfSourceCompile_161.jpg[image]
 
-==== Binary weaving
+=== Binary weaving
 
 Moving on from source compilation to pure binary weaving, the
 improvements are more obvious. Here we are using the complete JVM
@@ -62,7 +62,7 @@ aspect (121000 join points)
 
 image:images/perfBinaryWeave_161.jpg[image]
 
-==== Loadtime weaving
+=== Loadtime weaving
 
 The loadtime weaving improvements are similar to those seen for binary
 weaving (naturally). Here we are using the JDK tools jar 'tools.jar' as
@@ -93,7 +93,7 @@ So in terms of memory required, weaving the insane aspect into tools.jar
 created 1.4G of 'stuff' over the entire weaving process, compared to
 1.75G with 1.6.0.
 
-==== Loadtime weaving stress
+=== Loadtime weaving stress
 
 As well as addressing the memory usage of a single load time weaver, we
 have also looked at the use of load time weaving in a larger scale
@@ -119,7 +119,7 @@ And now AspectJ 1.6.1:
 
 image:images/memLtwStress_161.jpg[image]
 
-=== Incremental compilation
+== Incremental compilation
 
 Following on from the work done to improve compilation under Eclipse in
 AspectJ 1.6.0 (https://bugs.eclipse.org/bugs/show_bug.cgi?id=221427[Bug
@@ -138,9 +138,9 @@ with known errors, and this means AspectJ will more frequently do
 incremental builds rather than falling back to full builds because there
 was a compilation error.
 
-=== Language changes
+== Language changes
 
-==== Optmized syntax for annotation value binding (https://bugs.eclipse.org/bugs/show_bug.cgi?id=234943[Bug234943])
+=== Optmized syntax for annotation value binding (https://bugs.eclipse.org/bugs/show_bug.cgi?id=234943[Bug234943])
 
 If only binding an annotation at a method-execution join point in order
 to access an *enum value* within it, there is a more optimal syntax that
diff --git a/docs/release/README-1.6.10.adoc b/docs/release/README-1.6.10.adoc
index 5f571fce9..31a44ab8f 100644
--- a/docs/release/README-1.6.10.adoc
+++ b/docs/release/README-1.6.10.adoc
@@ -1,4 +1,4 @@
-== AspectJ 1.6.10
+= AspectJ 1.6.10
 
 _© Copyright 2010 Contributors. All rights reserved._
 
@@ -7,13 +7,13 @@ https://bugs.eclipse.org/bugs/buglist.cgi?query_format=advanced;bug_status=RESOL
 
 _Release info: 1.6.10 available 17-Nov-2010_
 
-=== Changes
+== Changes
 
 1.6.10 is primilarily just bug fixes for AspectJ, mainly in the areas of
 ITDs and generic aspects. However, there are a couple of important
 changes that users ought to be aware of:
 
-==== AJDT Memory usage
+=== AJDT Memory usage
 
 Type demotion has been in use during loadtime weaving for a while now,
 this enables the load time weavers to discard state and recover it at a
@@ -34,7 +34,7 @@ If I can get enough positive feedback about this option, it will be made
 the default. For a more detailed write up, check out the blog post:
 http://andrewclement.blogspot.com/2010/07/ajdt-memory-usage-reduction.html
 
-==== Runtime changes
+=== Runtime changes
 
 A big thank you to Abraham Nevado and his team who have been working on
 some issues to optimize loadtime weaving and the code generated by
diff --git a/docs/release/README-1.6.11.adoc b/docs/release/README-1.6.11.adoc
index e5f4226a2..b2e982c71 100644
--- a/docs/release/README-1.6.11.adoc
+++ b/docs/release/README-1.6.11.adoc
@@ -1,4 +1,4 @@
-== AspectJ 1.6.11
+= AspectJ 1.6.11
 
 _© Copyright 2010-2011 Contributors. All rights reserved._
 
@@ -7,9 +7,9 @@ https://bugs.eclipse.org/bugs/buglist.cgi?query_format=advanced;bug_status=RESOL
 
 _Release info: 1.6.11 available 15-Mar-2011_
 
-=== Notable Changes
+== Notable Changes
 
-==== RC1 - Our own XML parser
+=== RC1 - Our own XML parser
 
 Due to the way AspectJ loads one of the standard XML parsers (for
 processing aop.xml) it was possible to get into a deadlock situation. To
@@ -21,7 +21,7 @@ org.aspectj.weaver.loadtime.configuration.lightxmlparser=true.
 
 '''''
 
-==== M2 - Multithreaded world access
+=== M2 - Multithreaded world access
 
 The weaver is backed by a representation of types called a world.
 Traditionally the worlds have supported single threads - and that is how
@@ -32,7 +32,7 @@ same time. Under
 https://bugs.eclipse.org/bugs/show_bug.cgi?id=337855[bug337855] some
 changes have been made to better support this kind of configuration.
 
-==== M2 - various attribute deserialization issues
+=== M2 - various attribute deserialization issues
 
 In 1.6.9 we made some radical changes to the serialized form. It turns
 out some of the deserialization code wasn't handling these new forms
@@ -40,7 +40,7 @@ quite right. This would manifest as an IllegalStateException or
 IndexOutOfBoundsException or similar, during attribute unpacking. These
 issues have now all been sorted out in 1.6.11.M2.
 
-==== M2 - further optimizations in model for AJDT
+=== M2 - further optimizations in model for AJDT
 
 More changes have been made for users trying out the
 -Xset:minimalModel=true option to try and reduce the memory used in
@@ -52,7 +52,7 @@ over), but now it is insensitive to ordering and should always recover
 the same amount across builds of the same project. With a bit more
 positive feedback on this option, it will become the default under AJDT.
 
-==== M2 - spaces in path names can cause problems
+=== M2 - spaces in path names can cause problems
 
 AspectJ had problems if the paths it was being passed (e.g. aspectpath)
 included spaces. This is bug
@@ -61,7 +61,7 @@ been fixed.
 
 '''''
 
-==== M1 - Annotation removal
+=== M1 - Annotation removal
 
 Traditionally AspectJ has taken an additive approach, where
 methods/fields/supertypes/annotations can only be added to types. Now,
@@ -81,7 +81,7 @@ Notice the '-' in front of the annotation, meaning 'removal'. The whole
 construct means 'remove the @Anno annotation from the int field called i
 in type Foo'. It is not yet supported on the other forms of declare @.
 
-==== M1 - Intertype innertypes
+=== M1 - Intertype innertypes
 
 More work has gone into this feature. It was originally added in 1.6.9
 but the inability to use it with binary weaving greatly reduced the
diff --git a/docs/release/README-1.6.12.adoc b/docs/release/README-1.6.12.adoc
index ed9951d4d..165cd33a2 100644
--- a/docs/release/README-1.6.12.adoc
+++ b/docs/release/README-1.6.12.adoc
@@ -1,4 +1,4 @@
-== AspectJ 1.6.12
+= AspectJ 1.6.12
 
 _© Copyright 2010-2011 Contributors. All rights reserved._
 
@@ -12,9 +12,9 @@ _Release info:_
   * _1.6.12.M2 available 18-Aug-2011_
   * _1.6.12.M1 available 7-Jun-2011_
 
-=== Notable Changes
+== Notable Changes
 
-==== RC1 - annotation value matching and !=
+=== RC1 - annotation value matching and !=
 
 Prior to this change it was only possible to specify an annotation match
 like this: +
@@ -29,7 +29,7 @@ This can enable a group of annotated elements to be more easily
 identified. +
  +
 
-==== RC1 - More flexible pointcut/code wiring in aop.xml
+=== RC1 - More flexible pointcut/code wiring in aop.xml
 
 Prior to this version the wiring was quite limited. In order to wire a
 pointcut to a piece of code the user needed to write an abstract aspect
@@ -95,7 +95,7 @@ get started!
 
 '''''
 
-==== M2 - thisAspectInstance (https://bugs.eclipse.org/bugs/show_bug.cgi?id=239649[bug239649])
+=== M2 - thisAspectInstance (https://bugs.eclipse.org/bugs/show_bug.cgi?id=239649[bug239649])
 
 There is now a new well known name that you can use in the if clauses in
 your aspects. thisAspectInstance provides access to the aspect instance.
@@ -147,13 +147,13 @@ going to run. *Note:* right now this only works for singleton aspects.
 If you have need of it with other instantiation models, please comment
 on https://bugs.eclipse.org/bugs/show_bug.cgi?id=239649
 
-==== M2 - weaving groovy
+=== M2 - weaving groovy
 
 Although we have been successfully weaving groovy for a long time, it is
 becoming more popular and a few issues have been uncovered when using
 non-singleton aspects with groovy code. These have been fixed.
 
-==== M2 - AJDT memory
+=== M2 - AJDT memory
 
 The release notes for the last few versions of AspectJ have mentioned
 two options (minimalModel and typeDemotion) which can be switched on to
@@ -167,7 +167,7 @@ actively turning them off by specifying
 -Xset:minimalModel=false,typeDemotion=false in the project properties
 for your AspectJ project.
 
-==== M2 - Java7 weaving support
+=== M2 - Java7 weaving support
 
 Some preliminary work has been done to support Java7. Java7 class files
 must contain the necessary extra verifier support attributes in order to
@@ -181,7 +181,7 @@ supports Java7 language constructs - that will happen after Eclipse
 
 '''''
 
-==== M1 - synthetic is supported in pointcut modifiers https://bugs.eclipse.org/bugs/show_bug.cgi?id=327867[327867]
+=== M1 - synthetic is supported in pointcut modifiers https://bugs.eclipse.org/bugs/show_bug.cgi?id=327867[327867]
 
 It is now possible to specify synthetic in pointcuts:
 
@@ -190,21 +190,21 @@ It is now possible to specify synthetic in pointcuts:
 pointcut p(): execution(!synthetic * *(..));
 ....
 
-==== M1 - respect protection domain when generating types during weaving https://bugs.eclipse.org/bugs/show_bug.cgi?id=328099[328099]
+=== M1 - respect protection domain when generating types during weaving https://bugs.eclipse.org/bugs/show_bug.cgi?id=328099[328099]
 
 This enables us to weave signed jars correctly. AspectJ sometimes
 generates closure classes during weaving and these must be defined with
 the same protection domain as the jar that gave rise to them. In
 1.6.12.M1 this should now work correctly.
 
-==== M1 - Suppressions inline with the JDT compiler https://bugs.eclipse.org/bugs/show_bug.cgi?id=335810[335810]
+=== M1 - Suppressions inline with the JDT compiler https://bugs.eclipse.org/bugs/show_bug.cgi?id=335810[335810]
 
 Starting with Eclipse 3.6, the Eclipse compiler no longer suppresses raw
 type warnings with @SuppressWarnings("unchecked"). You need to use
 @SuppressWarnings("rawtypes") for that. AspectJ has now been updated
 with this rule too.
 
-==== M1 - Optimized annotation value binding for ints https://bugs.eclipse.org/bugs/show_bug.cgi?id=347684[347684]
+=== M1 - Optimized annotation value binding for ints https://bugs.eclipse.org/bugs/show_bug.cgi?id=347684[347684]
 
 The optimized annotation value binding now supports ints - this is for
 use when you want to match upon the existence of an annotation but you
diff --git a/docs/release/README-1.6.2.adoc b/docs/release/README-1.6.2.adoc
index a6b88ffee..56cc0adc9 100644
--- a/docs/release/README-1.6.2.adoc
+++ b/docs/release/README-1.6.2.adoc
@@ -1,4 +1,4 @@
-== AspectJ 1.6.2
+= AspectJ 1.6.2
 
 _© Copyright 2008 Contributors. All rights reserved._
 
@@ -31,7 +31,7 @@ resolved]
 
 '''''
 
-=== Incremental compilation (https://bugs.eclipse.org/bugs/show_bug.cgi?id=247742[bug 247742], https://bugs.eclipse.org/bugs/show_bug.cgi?id=245566[bug 245566], https://bugs.eclipse.org/bugs/show_bug.cgi?id=243376[bug 243376])
+== Incremental compilation (https://bugs.eclipse.org/bugs/show_bug.cgi?id=247742[bug 247742], https://bugs.eclipse.org/bugs/show_bug.cgi?id=245566[bug 245566], https://bugs.eclipse.org/bugs/show_bug.cgi?id=243376[bug 243376])
 
 Two main changes in this area.
 
diff --git a/docs/release/README-1.6.3.adoc b/docs/release/README-1.6.3.adoc
index 1609eb35f..3fbb1e249 100644
--- a/docs/release/README-1.6.3.adoc
+++ b/docs/release/README-1.6.3.adoc
@@ -1,4 +1,4 @@
-== AspectJ 1.6.3
+= AspectJ 1.6.3
 
 _© Copyright 2008 Contributors. All rights reserved._
 
@@ -10,7 +10,7 @@ _© Copyright 2008 Contributors. All rights reserved._
 '''''
 
 [[split]]
-=== Split matching/weaving
+== Split matching/weaving
 
 The main goal of AspectJ 1.6.3 was to make the line between matching and
 weaving more explicit and introduce the notion of a matcher artifact.
@@ -43,7 +43,7 @@ and reflection based - both of which require compilation).
 '''''
 
 [[bugsfixed]]
-=== Bugs fixed
+== Bugs fixed
 
 The complete list of issues resolved for AspectJ 1.6.3 (more than 50)
 can be found with this bugzilla query:
@@ -57,7 +57,7 @@ issues.
 '''''
 
 [[notable]]
-=== Notable bug fixes
+== Notable bug fixes
 
 * More improvements to the way AspectJ/AJDT communicate (251277, 249216,
 258325)
@@ -72,7 +72,7 @@ type (256669)
 '''''
 
 [[whatsnext]]
-=== What's next?
+== What's next?
 
 The JDT World should be completed in the 1.6.4 timeframe and that will
 surface as benefits in AJDT, possibly leading to better LTW tooling.
diff --git a/docs/release/README-1.6.4.adoc b/docs/release/README-1.6.4.adoc
index dc3a71816..e3d2550df 100644
--- a/docs/release/README-1.6.4.adoc
+++ b/docs/release/README-1.6.4.adoc
@@ -1,4 +1,4 @@
-== AspectJ 1.6.4
+= AspectJ 1.6.4
 
 _© Copyright 2009 Contributors. All rights reserved._
 
@@ -10,7 +10,7 @@ _© Copyright 2009 Contributors. All rights reserved._
 '''''
 
 [[compilation]]
-=== Compilation times
+== Compilation times
 
 In AspectJ 1.6.4 the goal was to improve the IDE experience, through a
 combination of improved compilation speed (both full builds and
@@ -107,7 +107,7 @@ AspectJ projects depend upon Java projects and where aspectpath is used.
 AJDT 1.6.5 dev builds also include some changes that really speed up
 builds.
 
-=== Better editor feedback
+== Better editor feedback
 
 Under https://bugs.eclipse.org/bugs/show_bug.cgi?id=246393[bug 246393]
 the problem has been addressed where sometimes spurious errors would
@@ -118,7 +118,7 @@ http://andrewclement.blogspot.com/2009/02/aspectj-fixing-reverse-cascade-errors.
 '''''
 
 [[language]]
-=== Language Enhancements
+== Language Enhancements
 
 *Optimizing support for maintaining per join point state*
 
@@ -169,7 +169,7 @@ advised type.
 See related https://bugs.eclipse.org/bugs/show_bug.cgi?id=89009[bug
 89009] for the full discussion
 
-=== @DeclareMixin
+== @DeclareMixin
 
 The annotation style declare parents support (@DeclareParents) has been
 (rightly) criticized because it really does not offer an equivalent to
@@ -208,7 +208,7 @@ deprecated.
 '''''
 
 [[bugsfixed]]
-=== Bugs fixed
+== Bugs fixed
 
 The complete list of issues resolved for AspectJ 1.6.4 (more than 70)
 can be found with this bugzilla query:
@@ -219,7 +219,7 @@ resolved]
 '''''
 
 [[whatsnext]]
-=== What's next?
+== What's next?
 
 *More incremental build enhancements*
 
diff --git a/docs/release/README-1.6.5.adoc b/docs/release/README-1.6.5.adoc
index 28396df40..1647e73d1 100644
--- a/docs/release/README-1.6.5.adoc
+++ b/docs/release/README-1.6.5.adoc
@@ -1,9 +1,9 @@
-== AspectJ 1.6.5
+= AspectJ 1.6.5
 
 _© Copyright 2009 Contributors. All rights reserved._
 
 [[bugsfixed]]
-=== Bugs fixed
+== Bugs fixed
 
 The complete list of issues resolved for AspectJ 1.6.5 can be found with
 this bugzilla query:
diff --git a/docs/release/README-1.6.6.adoc b/docs/release/README-1.6.6.adoc
index 940b2cf96..28a1c68a6 100644
--- a/docs/release/README-1.6.6.adoc
+++ b/docs/release/README-1.6.6.adoc
@@ -1,9 +1,9 @@
-== AspectJ 1.6.6
+= AspectJ 1.6.6
 
 _© Copyright 2009 Contributors. All rights reserved._
 
 [[bugsfixed]]
-=== Bugs fixed
+== Bugs fixed
 
 The complete list of issues resolved for AspectJ 1.6.6 can be found with
 this bugzilla query:
@@ -13,7 +13,7 @@ resolved]
 
 '''''
 
-=== Changes
+== Changes
 
 *Java5*
 
diff --git a/docs/release/README-1.6.7.adoc b/docs/release/README-1.6.7.adoc
index ad2769e41..464f34006 100644
--- a/docs/release/README-1.6.7.adoc
+++ b/docs/release/README-1.6.7.adoc
@@ -1,4 +1,4 @@
-== AspectJ 1.6.7
+= AspectJ 1.6.7
 
 _© Copyright 2009 Contributors. All rights reserved._
 
@@ -6,7 +6,7 @@ AspectJ 1.6.7 includes some radical internal changes. These improvements
 enable faster compilation, faster binary weaving, faster load time
 weaving and in some situations faster generated code.
 
-=== Pointcut timers
+== Pointcut timers
 
 Until 1.6.7 there has not really been a way to determine if it is just
 one of your pointcuts that is hurting your weaving performance. In 1.6.7
@@ -41,7 +41,7 @@ AJDT. Armed with this information you can optimize your pointcuts or
 post on the mailing list asking for help. The timers can even be turned
 on for load time weaving.
 
-=== Faster matching
+== Faster matching
 
 The changes to enable pointcut profiling enabled some targeted work to
 be done on the matching algorithms. These have remained unchanged for a
@@ -61,7 +61,7 @@ as early as possible once they can determine something is a match or is
 definetly not a match. This reduces memory usage, speeds up weaving and
 reduces the occurrences of those annoying 'cantFindType' messages.
 
-=== aop.xml processing
+== aop.xml processing
 
 The processing of include/exclude entries in aop.xml has been rewritten.
 It now optimizes for many more common patterns. If a pattern is
@@ -69,7 +69,7 @@ optimized then there is no need to ask the weaver to do an expensive
 include/exclude match. More details
 http://andrewclement.blogspot.com/2009/12/aspectj-167-and-faster-load-time.html[here].
 
-=== Less need to tweak options for load time weaving
+== Less need to tweak options for load time weaving
 
 A number of options were previously configurable for load time weaving
 that were considered experimental. These options have now been tested
@@ -82,7 +82,7 @@ by default in 1.6.7. If you have been using either of these:
 then please delete them from your weaver options section, the weaver
 will now do the right thing out of the box.
 
-=== Benchmarking memory and performance
+== Benchmarking memory and performance
 
 All those changes above, and some additional tweaks, mean we are now
 using less memory than ever before and getting things done more quickly.
@@ -98,7 +98,7 @@ image:images/167speed.png[image]
 
 image:images/167Memory.png[image]
 
-=== Annotation binding
+== Annotation binding
 
 All those changes affect compilation/weaving but what about the code
 that actually runs? One user, Oliver Hoff, raised a query on the
@@ -171,7 +171,7 @@ value.
 '''''
 
 [[bugsfixed]]
-==== Bugs fixed
+=== Bugs fixed
 
 The complete list of issues resolved for AspectJ 1.6.7 can be found with
 this bugzilla query:
diff --git a/docs/release/README-1.6.8.adoc b/docs/release/README-1.6.8.adoc
index 0adbd557a..42828d99a 100644
--- a/docs/release/README-1.6.8.adoc
+++ b/docs/release/README-1.6.8.adoc
@@ -1,4 +1,4 @@
-== AspectJ 1.6.8
+= AspectJ 1.6.8
 
 _© Copyright 2009 Contributors. All rights reserved._
 
@@ -9,7 +9,7 @@ Unfortunately not enough testing was done on 1.6.7 and two nasty issues
 were found that really needed addressing. Fixes for these issues are all
 that is new in 1.6.8.
 
-=== Incorrect treatment of some aop.xml include/exclude patterns
+== Incorrect treatment of some aop.xml include/exclude patterns
 
 See https://bugs.eclipse.org/bugs/show_bug.cgi?id=298786[Bug 298786]
 
@@ -39,7 +39,7 @@ right now as it includes multiple wildcards).
 With that configuration any types that the include="*" would have
 accepted are not accepted.
 
-=== Stack overflow problem in ReferenceType.isAssignableFrom()
+== Stack overflow problem in ReferenceType.isAssignableFrom()
 
 See https://bugs.eclipse.org/bugs/show_bug.cgi?id=298908[Bug 298908]
 
diff --git a/docs/release/README-1.6.9.adoc b/docs/release/README-1.6.9.adoc
index 943cc6d90..a7923cf01 100644
--- a/docs/release/README-1.6.9.adoc
+++ b/docs/release/README-1.6.9.adoc
@@ -1,13 +1,13 @@
-== AspectJ 1.6.9
+= AspectJ 1.6.9
 
 _© Copyright 2010 Contributors. All rights reserved._
 
 The full list of resolved issues in 1.6.9 is available
 https://bugs.eclipse.org/bugs/buglist.cgi?query_format=advanced;bug_status=RESOLVED;bug_status=VERIFIED;bug_status=CLOSED;product=AspectJ;target_milestone=1.6.9;target_milestone=1.6.9M1;target_milestone=1.6.9M2;target_milestone=1.6.9RC1[here]
 
-=== Features
+== Features
 
-==== declare annotation supports compound signature patterns: https://bugs.eclipse.org/bugs/show_bug.cgi?id=287613[287613]
+=== declare annotation supports compound signature patterns: https://bugs.eclipse.org/bugs/show_bug.cgi?id=287613[287613]
 
 Until now it wasn't possible to express a compound pattern in any of the
 declare annotation constructs that take a member signature. For example,
@@ -28,7 +28,7 @@ Now AspectJ allows compound patterns for declare
 declare @method: (* is*()) || (* get*()): @FooBar;
 ....
 
-==== Intertype declaration of member types
+=== Intertype declaration of member types
 
 It is now possible to ITD member types. The syntax is as would be
 expected. This example introduces a new member type called Inner into
@@ -53,7 +53,7 @@ aspect Magic {
 
 Only static member types are supported.
 
-==== 'Optional' aspects: https://bugs.eclipse.org/bugs/show_bug.cgi?id=310506[310506]
+=== 'Optional' aspects: https://bugs.eclipse.org/bugs/show_bug.cgi?id=310506[310506]
 
 It is not uncommon to ship a library aspect separately to a jar upon
 which it depends. In the case of Spring there is an aspect library
@@ -79,7 +79,7 @@ Here is an example, 'AspectA' will switch itself off if the type
 <aspect name="AspectA" requires="a.b.c.Anno"/>
 ....
 
-==== Reduction in class file sizes: https://bugs.eclipse.org/bugs/show_bug.cgi?id=312839[312839]
+=== Reduction in class file sizes: https://bugs.eclipse.org/bugs/show_bug.cgi?id=312839[312839]
 
 More details here:
 http://andrewclement.blogspot.com/2010/05/aspectj-size-is-important.html
@@ -88,7 +88,7 @@ aspects. As an example, a compiled Roo petclinic sample (which uses lots
 of aspects and ITDs) is down from 1Meg (AspectJ 1.6.9m2) to 630k
 (AspectJ 1.6.9rc1).
 
-==== Transparent weaving: https://bugs.eclipse.org/bugs/show_bug.cgi?id=309743[309743]
+=== Transparent weaving: https://bugs.eclipse.org/bugs/show_bug.cgi?id=309743[309743]
 
 In a further step towards transparent weaving, support for the AjType
 reflection system is now being made optional. This means if intending to
@@ -101,7 +101,7 @@ standard reflection than are using AjTypeSystem. The related bugzilla
 discussing this issue is
 https://bugs.eclipse.org/bugs/show_bug.cgi?id=309743[309743].
 
-==== Overweaving: https://bugs.eclipse.org/bugs/show_bug.cgi?id=293450[293450]
+=== Overweaving: https://bugs.eclipse.org/bugs/show_bug.cgi?id=293450[293450]
 
 Preliminary support for overweaving was added in AspectJ 1.6.7, but now
 in AspectJ 1.6.9m2 it is much more reliable. Basically it is an
@@ -116,7 +116,7 @@ article]. A weaver is switched into overweaving mode by the option
 in the weaver options section of aop.xml. There is still more work to be
 done on this feature - any feedback is welcome.
 
-==== AOP Scoping: https://bugs.eclipse.org/bugs/show_bug.cgi?id=124460[124460]
+=== AOP Scoping: https://bugs.eclipse.org/bugs/show_bug.cgi?id=124460[124460]
 
 Another feature that had preliminary support a while ago is aspect
 scoping in aop.xml. This has also been improved in AspectJ1.6.9m2. For
@@ -150,7 +150,7 @@ com..* should be woven and the aspects to be used are X and Y. The new
 'scope' setting on aspect Y's definition allows finer control, and
 specifies that Y should in fact only be applied to com.foo..* types.
 
-==== Message inserts for declare warning/error messages
+=== Message inserts for declare warning/error messages
 
 It is now possible to use joinpoint context in the messages attached to
 declare warning and declare error constructs. Some examples:
@@ -173,7 +173,7 @@ The syntax is to enclose the relevant key within curly brackets within
 the message. Please raise an enhancement request if you need other keys
 - the set supported so far are all those shown in the example above.
 
-==== declare warning/error for type patterns
+=== declare warning/error for type patterns
 
 It is now possible to use a type pattern with declare warning and
 declare error. For example:
@@ -183,7 +183,7 @@ declare error. For example:
 declare warning: I+ && !hasfield(int i): "Implementations of I are expected to have a int field called i";
 ....
 
-==== Type category type patterns
+=== Type category type patterns
 
 This is the ability to narrow the types of interest so that interfaces
 can be ignored, or inner types, or classes or aspects. There is now a
@@ -218,7 +218,7 @@ surrounding Boo will match it). Bar.foo() will not match
 !within(is(InnerType)) because Bar will match the pattern and then the
 result of that match will be negated.
 
-==== Intertype fields preserve visibility and name
+=== Intertype fields preserve visibility and name
 
 Some users always expect this:
 
@@ -270,7 +270,7 @@ The name 'someField' is preserved. The visibility is also preserved but
 because of that we also need to generate some accessors to get at the
 field.
 
-==== AspectJ snapshots in a maven repo
+=== AspectJ snapshots in a maven repo
 
 To ease how AspectJ development builds can be consumed, they are now
 placed into a maven repo. When a new version of AspectJ is put into AJDT
diff --git a/docs/release/README-1.7.0.adoc b/docs/release/README-1.7.0.adoc
index 2437d10ef..6856b161a 100644
--- a/docs/release/README-1.7.0.adoc
+++ b/docs/release/README-1.7.0.adoc
@@ -1,4 +1,4 @@
-== AspectJ 1.7.0
+= AspectJ 1.7.0
 
 _© Copyright 2011 Contributors. All rights reserved._
 
@@ -11,9 +11,9 @@ _Release info:_
 * _1.7.0.RC1 available 25-May-2012_
 * _1.7.0.M1 available 16-Dec-2011_
 
-=== Notable Changes
+== Notable Changes
 
-==== Java 7 bytecode weaving
+=== Java 7 bytecode weaving
 
 The first milestone of 1.7.0 upgraded the compiler but this still left
 the weaver with some issues if it had to weave into bytecode containing
@@ -26,7 +26,7 @@ point yet so you cannot write a pointcut to match on it. If you use
 execution() pointcuts as opposed to call() then you will still be able
 to advise what the invokedynamic actually calls.
 
-==== Bytecode caching for loadtime weaving
+=== Bytecode caching for loadtime weaving
 
 Under https://bugs.eclipse.org/bugs/show_bug.cgi?id=367673[bug 367673]
 we have had a contribution (thanks John Kew!) that enables a bytecode
@@ -42,7 +42,7 @@ To activate it, use the following system properties:
 -Daj.weaving.cache.dir=/tmp/aspectj-cache/
 ....
 
-==== Upgrade to Java 7
+=== Upgrade to Java 7
 
 For AspectJ 1.7.0, AspectJ moved from Eclipse JDT Core 0.785_R33x
 (Eclipse 3.3) to Eclipse JDT Core 0.B79_R37x (Eclipse 3.7). This is a
diff --git a/docs/release/README-1.7.1.adoc b/docs/release/README-1.7.1.adoc
index 30515f0e2..6910b64e9 100644
--- a/docs/release/README-1.7.1.adoc
+++ b/docs/release/README-1.7.1.adoc
@@ -1,4 +1,4 @@
-== AspectJ 1.7.1
+= AspectJ 1.7.1
 
 _© Copyright 2011 Contributors. All rights reserved._
 
@@ -7,7 +7,7 @@ https://bugs.eclipse.org/bugs/buglist.cgi?query_format=advanced;bug_status=RESOL
 
 _Release info: 1.7.1 available 6-Sep-2012_
 
-=== Changes
+== Changes
 
 https://bugs.eclipse.org/bugs/show_bug.cgi?id=388971[388971] Double
 Synthetic attributes on some around advice members +
diff --git a/docs/release/README-1.7.2.adoc b/docs/release/README-1.7.2.adoc
index 52754ad8e..a846f61ea 100644
--- a/docs/release/README-1.7.2.adoc
+++ b/docs/release/README-1.7.2.adoc
@@ -1,4 +1,4 @@
-== AspectJ 1.7.2
+= AspectJ 1.7.2
 
 _© Copyright 2011 Contributors. All rights reserved._
 
@@ -7,7 +7,7 @@ https://bugs.eclipse.org/bugs/buglist.cgi?query_format=advanced;bug_status=RESOL
 
 _Release info: 1.7.2 available 13-Feb-2013_
 
-=== Fixes:
+== Fixes:
 
 * Incorrect signature attributes generated into some class files for
 complex generics declarations.
diff --git a/docs/release/README-1.7.3.adoc b/docs/release/README-1.7.3.adoc
index 73a0ad320..0ef861cc4 100644
--- a/docs/release/README-1.7.3.adoc
+++ b/docs/release/README-1.7.3.adoc
@@ -1,4 +1,4 @@
-== AspectJ 1.7.3
+= AspectJ 1.7.3
 
 _© Copyright 2011 Contributors. All rights reserved._
 
diff --git a/docs/release/README-1.7.4.adoc b/docs/release/README-1.7.4.adoc
index 20464744a..c4c084245 100644
--- a/docs/release/README-1.7.4.adoc
+++ b/docs/release/README-1.7.4.adoc
@@ -1,4 +1,4 @@
-== AspectJ 1.7.4
+= AspectJ 1.7.4
 
 _© Copyright 2013 Contributors. All rights reserved._
 
diff --git a/docs/release/README-1.8.0.adoc b/docs/release/README-1.8.0.adoc
index 9a2ba78be..de5a6a987 100644
--- a/docs/release/README-1.8.0.adoc
+++ b/docs/release/README-1.8.0.adoc
@@ -1,4 +1,4 @@
-== AspectJ 1.8.0
+= AspectJ 1.8.0
 
 _© Copyright 2014 Contributors. All rights reserved._
 
@@ -11,9 +11,9 @@ _Release info:_
 * _1.8.0.RC1 available 18-Mar-2014_
 * _1.8.0.M1 available 29-Jul-2013_
 
-=== Notable changes
+== Notable changes
 
-==== Java 8 compilation
+=== Java 8 compilation
 
 AspectJ has been updated to the latest available Eclipse Java compiler
 version that compiles Java8 code (the version available as a feature
diff --git a/docs/release/README-1.8.1.adoc b/docs/release/README-1.8.1.adoc
index ef0e8a1ee..081820094 100644
--- a/docs/release/README-1.8.1.adoc
+++ b/docs/release/README-1.8.1.adoc
@@ -1,4 +1,4 @@
-== AspectJ 1.8.1
+= AspectJ 1.8.1
 
 _© Copyright 2014 Contributors. All rights reserved._
 
@@ -7,9 +7,9 @@ https://bugs.eclipse.org/bugs/buglist.cgi?query_format=advanced;bug_status=RESOL
 
 _Release info: 1.8.1 available 20-Jun-2014_
 
-=== Notable changes
+== Notable changes
 
-==== Java 8 update
+=== Java 8 update
 
 As Eclipse itself nears the 4.4 release, AspectJ has been updated to the
 latest Eclipse JDT Core that will be included in it, picking up numerous
diff --git a/docs/release/README-1.8.10.adoc b/docs/release/README-1.8.10.adoc
index cce5da187..21516350e 100644
--- a/docs/release/README-1.8.10.adoc
+++ b/docs/release/README-1.8.10.adoc
@@ -1,4 +1,4 @@
-== AspectJ 1.8.10
+= AspectJ 1.8.10
 
 _© Copyright 2016 Contributors. All rights reserved._
 
@@ -7,21 +7,21 @@ https://bugs.eclipse.org/bugs/buglist.cgi?query_format=advanced;bug_status=RESOL
 
 _Release info: 1.8.10 available 9-Dec-2016_
 
-=== Notable changes
+== Notable changes
 
-==== JDT Upgrade
+=== JDT Upgrade
 
 The JDT compiler inside AspectJ has been upgraded to the Eclipse Neon.2
 level (JDT commit #75dbfad0).
 
-==== Java8
+=== Java8
 
 The Eclipse JDT compiler embedded inside AspectJ now requires Java 8, so
 that is the minimum required level to compile sources with AspectJ.
 However, if only doing weaving and no compilation then it is possible to
 use Java 7.
 
-==== Annotation style around advice and proceed (https://bugs.eclipse.org/bugs/show_bug.cgi?id=500035[Bug 500035])
+=== Annotation style around advice and proceed (https://bugs.eclipse.org/bugs/show_bug.cgi?id=500035[Bug 500035])
 
 A long standing issue that has been lurking in the handling of arguments
 passed to proceed for annotation style aspects has been fixed. If, at a
diff --git a/docs/release/README-1.8.11.adoc b/docs/release/README-1.8.11.adoc
index dedbc0463..a8ee63da3 100644
--- a/docs/release/README-1.8.11.adoc
+++ b/docs/release/README-1.8.11.adoc
@@ -1,4 +1,4 @@
-== AspectJ 1.8.11
+= AspectJ 1.8.11
 
 _© Copyright 2017 Contributors. All rights reserved._
 
diff --git a/docs/release/README-1.8.2.adoc b/docs/release/README-1.8.2.adoc
index a49213617..ee3bbc4b6 100644
--- a/docs/release/README-1.8.2.adoc
+++ b/docs/release/README-1.8.2.adoc
@@ -1,4 +1,4 @@
-== AspectJ 1.8.2
+= AspectJ 1.8.2
 
 _© Copyright 2014 Contributors. All rights reserved._
 
@@ -7,31 +7,31 @@ https://bugs.eclipse.org/bugs/buglist.cgi?query_format=advanced;bug_status=RESOL
 
 _Release info: 1.8.2 available 14-Aug-2014_
 
-=== Notable changes
+== Notable changes
 
 Although only a few bugs have been fixed here, they are quite important
 ones:
 
-==== Update to more recent Eclipse Compiler
+=== Update to more recent Eclipse Compiler
 
 AspectJ is now based on a more up to date Eclipse compiler level (git
 hash 2b07958) so includes all the latest fixes
 
-==== Correct handling of RuntimeInvisibleTypeAnnotations (type annotations without runtime visibility)
+=== Correct handling of RuntimeInvisibleTypeAnnotations (type annotations without runtime visibility)
 
 For anyone weaving code containing these kind of type annotations, this
 is an important fix. Although AspectJ does not currently support
 pointcuts matching on these kinds of annotation it was crashing when
 they were encountered. That is now fixed.
 
-==== Annotation processing
+=== Annotation processing
 
 A very long standing issue, the AspectJ compiler now supports annotation
 processors thanks to some work by Sergey Stupin.
 
 Here is a short example, a very basic annotation and application:
 
-===== Marker.java
+==== Marker.java
 
 [source, java]
 ....
@@ -42,7 +42,7 @@ import java.lang.annotation.RetentionPolicy;
 public @interface Marker { }
 ....
 
-===== Code.java
+==== Code.java
 
 [source, java]
 ....
@@ -72,7 +72,7 @@ in the source marked with the annotation Marker and for each one
 generate an aspect tailored to advising that method (this *is* a
 contrived demo!)
 
-===== DemoProcessor.java
+==== DemoProcessor.java
 
 [source, java]
 ....
diff --git a/docs/release/README-1.8.3.adoc b/docs/release/README-1.8.3.adoc
index 0d114d1f2..e1015d709 100644
--- a/docs/release/README-1.8.3.adoc
+++ b/docs/release/README-1.8.3.adoc
@@ -1,4 +1,4 @@
-== AspectJ 1.8.3
+= AspectJ 1.8.3
 
 _© Copyright 2014 Contributors. All rights reserved._
 
@@ -7,9 +7,9 @@ https://bugs.eclipse.org/bugs/buglist.cgi?query_format=advanced;bug_status=RESOL
 
 _Release info: 1.8.3 available 22-Oct-2014_
 
-=== Notable changes
+== Notable changes
 
-==== Conditional aspect activation with @RequiredTypes - https://bugs.eclipse.org/bugs/show_bug.cgi?id=436653[Issue 436653]
+=== Conditional aspect activation with @RequiredTypes - https://bugs.eclipse.org/bugs/show_bug.cgi?id=436653[Issue 436653]
 
 AspectJ is sometimes used to create aspect libraries. These libraries
 contain a number of aspects often covering a variety of domains. The
@@ -49,7 +49,7 @@ passed on the aspectpath for compile time weaving, if the type
 turned off and the pointcut will have no effect. There will be no
 attempt made to match it and so no unhelpful "can't find type" messages.
 
-==== cflow and the pre-initialization joinpoint changes due to Java 7 verifier modifications - https://bugs.eclipse.org/bugs/show_bug.cgi?id=443477[Issue 443477]
+=== cflow and the pre-initialization joinpoint changes due to Java 7 verifier modifications - https://bugs.eclipse.org/bugs/show_bug.cgi?id=443477[Issue 443477]
 
 There has been a change in the Java7 verifier in a recent patch release
 of Java7 (update 67) that causes a verify error for usage of a
@@ -89,7 +89,7 @@ seems little use in applying it to pre-initialization - that is your cue
 to raise an AspectJ bug with a realistic use case inside that proves
 this an invalid assumption :)
 
-==== around advice and lambdas - https://bugs.eclipse.org/bugs/show_bug.cgi?id=445395[Issue 445395]
+=== around advice and lambdas - https://bugs.eclipse.org/bugs/show_bug.cgi?id=445395[Issue 445395]
 
 For optimal performance, where possible, AspectJ tries to inline around
 advice when it applies at a joinpoint. There are few characteristics of
diff --git a/docs/release/README-1.8.4.adoc b/docs/release/README-1.8.4.adoc
index 655d74a85..b70d97240 100644
--- a/docs/release/README-1.8.4.adoc
+++ b/docs/release/README-1.8.4.adoc
@@ -1,4 +1,4 @@
-== AspectJ 1.8.4
+= AspectJ 1.8.4
 
 _© Copyright 2014 Contributors. All rights reserved._
 
@@ -7,9 +7,9 @@ https://bugs.eclipse.org/bugs/buglist.cgi?query_format=advanced;bug_status=RESOL
 
 _Release info: 1.8.4 available 6-Nov-2014_
 
-=== Notable changes
+== Notable changes
 
-==== Support for is(FinalType)
+=== Support for is(FinalType)
 
 AspectJ has had type category type patterns since version 1.6.9, see the
 https://www.eclipse.org/aspectj/doc/released/README-1.6.9.html[README].
@@ -19,7 +19,7 @@ is(InnerType)) means not within innertypes. In 1.8.4 it is now possible
 to recognize (for inclusion or exclusion) final types with
 is(FinalType).
 
-==== thisAspectInstance correctly handled with -1.8
+=== thisAspectInstance correctly handled with -1.8
 
 This is the key fix in this release. Some products based on AspectJ were
 using the thisAspectInstance feature (see
diff --git a/docs/release/README-1.8.5.adoc b/docs/release/README-1.8.5.adoc
index 22fdcee3f..6585ee2ec 100644
--- a/docs/release/README-1.8.5.adoc
+++ b/docs/release/README-1.8.5.adoc
@@ -1,4 +1,4 @@
-== AspectJ 1.8.5
+= AspectJ 1.8.5
 
 _© Copyright 2015 Contributors. All rights reserved._
 
@@ -7,7 +7,7 @@ https://bugs.eclipse.org/bugs/buglist.cgi?query_format=advanced;bug_status=RESOL
 
 _Release info: 1.8.5 available 28-Jan-2015_
 
-=== Notable changes
+== Notable changes
 
 The most important fixes in 1.8.5 are JDT compiler fixes that it
 includes
diff --git a/docs/release/README-1.8.6.adoc b/docs/release/README-1.8.6.adoc
index 9a2129414..780831ae7 100644
--- a/docs/release/README-1.8.6.adoc
+++ b/docs/release/README-1.8.6.adoc
@@ -1,4 +1,4 @@
-== AspectJ 1.8.6
+= AspectJ 1.8.6
 
 _© Copyright 2015 Contributors. All rights reserved._
 
diff --git a/docs/release/README-1.8.7.adoc b/docs/release/README-1.8.7.adoc
index 5d4c0de6b..89879236d 100644
--- a/docs/release/README-1.8.7.adoc
+++ b/docs/release/README-1.8.7.adoc
@@ -1,4 +1,4 @@
-== AspectJ 1.8.7
+= AspectJ 1.8.7
 
 _© Copyright 2015 Contributors. All rights reserved._
 
@@ -7,14 +7,14 @@ https://bugs.eclipse.org/bugs/buglist.cgi?query_format=advanced;bug_status=RESOL
 
 _Release info: 1.8.7 available 9-Sep-2015_
 
-=== Notable changes
+== Notable changes
 
-==== ajdoc
+=== ajdoc
 
 The ajdoc tool has been fixed! It is now working again if run on a 1.7
 JDK.
 
-==== Dynamic weaver attachment
+=== Dynamic weaver attachment
 
 The AspectJ loadtime weaving agent can now be dynamically attached to a
 JVM after it has started (you don't need to use -javaagent). This offers
diff --git a/docs/release/README-1.8.8.adoc b/docs/release/README-1.8.8.adoc
index 12b59eeb9..ee86e797e 100644
--- a/docs/release/README-1.8.8.adoc
+++ b/docs/release/README-1.8.8.adoc
@@ -1,4 +1,4 @@
-== AspectJ 1.8.8
+= AspectJ 1.8.8
 
 _© Copyright 2016 Contributors. All rights reserved._
 
@@ -7,9 +7,9 @@ https://bugs.eclipse.org/bugs/buglist.cgi?query_format=advanced;bug_status=RESOL
 
 _Release info: 1.8.8 available 7-Jan-2016_
 
-=== Notable changes
+== Notable changes
 
-==== Around advice on default methods
+=== Around advice on default methods
 
 In previous releases attempting to apply around advice to default
 methods would create methods with rogue modifiers in the interface
diff --git a/docs/release/README-1.8.9.adoc b/docs/release/README-1.8.9.adoc
index f24bb1223..0074a28a5 100644
--- a/docs/release/README-1.8.9.adoc
+++ b/docs/release/README-1.8.9.adoc
@@ -1,4 +1,4 @@
-== AspectJ 1.8.9
+= AspectJ 1.8.9
 
 _© Copyright 2016 Contributors. All rights reserved._
 
@@ -7,7 +7,7 @@ https://bugs.eclipse.org/bugs/buglist.cgi?query_format=advanced;bug_status=RESOL
 
 _Release info: 1.8.9 available 14-Mar-2016_
 
-=== Notable changes
+== Notable changes
 
 The JDT compiler inside AspectJ has been upgraded to the Eclipse Mars.2
 level (commit #a7bba8b1).
diff --git a/docs/release/README-1.9.0.adoc b/docs/release/README-1.9.0.adoc
index 06872691c..cc325f1f2 100644
--- a/docs/release/README-1.9.0.adoc
+++ b/docs/release/README-1.9.0.adoc
@@ -1,4 +1,8 @@
-== AspectJ 1.9.0
+= AspectJ 1.9.0
+:doctype: book
+:leveloffset: +1
+
+= AspectJ 1.9.0
 
 _© Copyright 2018 Contributors. All rights reserved._
 
@@ -7,7 +11,7 @@ https://bugs.eclipse.org/bugs/buglist.cgi?bug_status=RESOLVED&bug_status=VERIFIE
 
 _Release info: 1.9.0 available 2-Apr-2018_
 
-=== Improved runtime interface
+== Improved runtime interface
 
 New factory methods have been added to the AspectJ runtime. This is an
 attempt to more optimally create `thisJoinPoint` and
@@ -48,7 +52,7 @@ export ASPECTJ_OPTS="-Xajruntimetarget:1.9"
 
 And it should get picked up by AspectJ when it runs.
 
-== AspectJ 1.9.0.RC4
+= AspectJ 1.9.0.RC4
 
 _Release info: 1.9.0.RC4 available 21-Feb-2018_
 
@@ -75,14 +79,14 @@ For example, here is an `iajc` usage with `compilerArg` that is passing
 </iajc>
 ....
 
-== AspectJ 1.9.0.RC3
+= AspectJ 1.9.0.RC3
 
 _Release info: 1.9.0.RC3 available 5-Feb-2018_
 
 Primary changes in RC3 are to upgrade JDT and pickup all the fixes for
 Java9 that have gone into it over the last few months.
 
-== AspectJ 1.9.0.RC2
+= AspectJ 1.9.0.RC2
 
 _Release info: 1.9.0.RC2 available 9-Nov-2017_
 
@@ -91,7 +95,7 @@ version handling has been somewhat overhauled so AspectJ 9 will behave
 better on Java 10 and future JDKs. This should put AspectJ in a better
 place if new JDK versions are going to arrive thick and fast.
 
-== AspectJ 1.9.0.RC1
+= AspectJ 1.9.0.RC1
 
 _Release info: 1.9.0.RC1 available 20-Oct-2017_
 
@@ -99,7 +103,7 @@ This is the first release candidate of AspectJ 1.9.0 - the version of
 AspectJ to be based on Java9. It includes a recent version of the
 Eclipse Java9 compiler (from jdt core, commit #062ac5d7a6bf9).
 
-=== Automatic Modules
+== Automatic Modules
 
 AspectJ can now be used with the new module system available in Java9.
 The key jars in AspectJ have been given automatic module names. The
@@ -133,7 +137,7 @@ contains org.aspectj.asm.internal
 ...
 ....
 
-=== Building woven modules
+== Building woven modules
 
 AspectJ understands `module-info.java` source files and building modules
 that include aspects. Here is an example:
@@ -200,7 +204,7 @@ Demo running
 
 That's it!
 
-=== Binary weaving with modules
+== Binary weaving with modules
 
 A module is really just a jar with a _module-info_ descriptor. As such, you
 can simply pass a module on the _inpath_ and binary-weave it with other
@@ -242,7 +246,7 @@ AnotherAzpect running
 Demo running
 ....
 
-=== Faster Spring AOP
+== Faster Spring AOP
 
 Dave Syer recently created a https://github.com/dsyer/spring-boot-aspectj[series of benchmarks] for checking the speed
 of Spring-AspectJ.
@@ -319,7 +323,7 @@ StartupBenchmark.spring   a20_100  avgt   10  3.093 ~ 0.098   s/op
 Look at the a20_100 case - instead of impacting start time by 9 seconds,
 it impacts it by 1 second.
 
-=== More to come...
+== More to come...
 
 * Eclipse JDT Java 9 support is still being actively worked on and lots
 of fixes will be coming through over the next few months and included in
diff --git a/docs/release/README-1.9.1.adoc b/docs/release/README-1.9.1.adoc
index e5aeac249..8ffdce948 100644
--- a/docs/release/README-1.9.1.adoc
+++ b/docs/release/README-1.9.1.adoc
@@ -1,4 +1,4 @@
-== AspectJ 1.9.1
+= AspectJ 1.9.1
 
 _© Copyright 2018 Contributors. All rights reserved._
 
@@ -7,7 +7,7 @@ https://bugs.eclipse.org/bugs/buglist.cgi?bug_status=RESOLVED&bug_status=VERIFIE
 
 _Release info: 1.9.1 available 20-Apr-2018_
 
-=== Java 10 support
+== Java 10 support
 
 AspectJ has updated to a recent JDT compiler version (commit
 #abe06abe4ce1 - 9-Apr-2018). With this update it now supports Java10.
diff --git a/docs/release/README-1.9.19.adoc b/docs/release/README-1.9.19.adoc
index 07618a02c..c34786812 100644
--- a/docs/release/README-1.9.19.adoc
+++ b/docs/release/README-1.9.19.adoc
@@ -1,8 +1,4 @@
-== AspectJ 1.9.19
-
-_© Copyright 2022 Contributors. All rights reserved._
-
-== AspectJ 1.9.19
+= AspectJ 1.9.19
 
 _© Copyright 2022 Contributors. All rights reserved._
 
@@ -15,7 +11,7 @@ here:
 * https://github.com/eclipse/org.aspectj/issues?q=is%3Aissue+is%3Aclosed++milestone%3A1.9.19[GitHub 1.9.19]
 * https://bugs.eclipse.org/bugs/buglist.cgi?bug_status=RESOLVED&bug_status=VERIFIED&bug_status=CLOSED&f0=OP&f1=OP&f3=CP&f4=CP&j1=OR&list_id=16866879&product=AspectJ&query_format=advanced&target_milestone=1.9.19[Bugzilla 1.9.19]
 
-=== New features
+== New features
 
 AspectJ 1.9.19 supports https://openjdk.java.net/projects/jdk/19/[Java 19] and its final, preview and incubator
 features, such as:
@@ -30,13 +26,13 @@ open issues concerning Java 19 preview feature support, see the list in
 https://github.com/eclipse/org.aspectj/issues/184#issuecomment-1272254940[this comment]. AJC therefore inherits the same
 problems for the specific cases described in the linked issues.
 
-=== Improvements
+== Improvements
 
 * Improve condy (constant dynamic) support. Together with some custom compilation or weaving options, this helps to
   avoid a problem when using JaCoCo together with AspectJ, see
   https://github.com/eclipse/org.aspectj/issues/170#issuecomment-1214163297[this comment in #170] for more details.
 
-=== Code examples
+== Code examples
 
 You can find some sample code in the AspectJ test suite under the respective AspectJ version in which the features were
 first supported (possibly as JVM preview features):
@@ -50,7 +46,7 @@ first supported (possibly as JVM preview features):
   concurrency features elsewhere, e.g. in the corresponding JEPs. In AspectJ, they should just work transparently like
   any other Java API.
 
-=== Other changes and bug fixes
+== Other changes and bug fixes
 
 * Fix (or rather work around) an old bug occurring when compiling or weaving code using ITD to declare annotations with
   `SOURCE` retention on types, methods, constructors or fields. While declaring such annotations does not make sense to
@@ -62,9 +58,9 @@ first supported (possibly as JVM preview features):
 * Remove legacy AspectJ Browser code and documentation.
 * Thanks to Andrey Turbanov for several clean code contributions.
 
-=== AspectJ usage hints
+== AspectJ usage hints
 
-==== AspectJ compiler build system requirements
+=== AspectJ compiler build system requirements
 
 Since 1.9.8, the AspectJ compiler `ajc` (contained in the `aspectjtools` library) no longer works on JDKs 8 to 10. The
 minimum compile-time requirement is now JDK 11 due to upstream changes in the Eclipse Java Compiler (subset of JDT
@@ -73,7 +69,7 @@ plain Java code or using plain Java ITD constructs which do not require the Aspe
 compiler itself needs JDK 11+. Just like in previous AspectJ versions, both the runtime `aspectjrt` and the load-time
 weaver `aspectjweaver` still only require JRE 8+.
 
-==== Use LTW on Java 16+
+=== Use LTW on Java 16+
 
 Please note that if you want to use load-time weaving on Java 16+, the weaving agent collides with
 https://openjdk.java.net/jeps/396[JEP 396 (Strongly Encapsulate JDK Internals by Default)]. Therefore, you need to set
@@ -81,7 +77,7 @@ the JVM parameter `--add-opens java.base/java.lang=ALL-UNNAMED` in order to enab
 fact that the weaver uses internal APIs for which we have not found an adequate replacement yet when defining classes
 in different classloaders.
 
-==== Compile with Java preview features
+=== Compile with Java preview features
 
 For features marked as preview on a given JDK, you need to compile with `ajc --enable-preview` and run with
 `java --enable-preview` on that JDK.
diff --git a/docs/release/README-1.9.2.adoc b/docs/release/README-1.9.2.adoc
index 94da278bf..a6e1fa550 100644
--- a/docs/release/README-1.9.2.adoc
+++ b/docs/release/README-1.9.2.adoc
@@ -1,11 +1,11 @@
-== AspectJ 1.9.2
+= AspectJ 1.9.2
 
 _© Copyright 2018 Contributors. All rights reserved._
 
 The full list of resolved issues in 1.9.2 is available
 https://bugs.eclipse.org/bugs/buglist.cgi?bug_status=RESOLVED&bug_status=VERIFIED&bug_status=CLOSED&f0=OP&f1=OP&f3=CP&f4=CP&j1=OR&list_id=16866879&product=AspectJ&query_format=advanced&target_milestone=1.9.2[here]
 
-=== Java 11 support
+== Java 11 support
 
 AspectJ now supports Java11. It has been updated to a more recent JDT
 compiler that supports Java 11 (JDTCore #6373b82afa49b).
diff --git a/docs/release/README-1.9.20.adoc b/docs/release/README-1.9.20.adoc
index 51b9033e9..d44769238 100644
--- a/docs/release/README-1.9.20.adoc
+++ b/docs/release/README-1.9.20.adoc
@@ -1,4 +1,9 @@
-== AspectJ 1.9.20.1
+= AspectJ 1.9.20
+
+:doctype: book
+:leveloffset: +1
+
+= AspectJ 1.9.20.1
 
 _© Copyright 2023 Contributors. All rights reserved._
 
@@ -16,7 +21,7 @@ This is a bugfix release for 1.9.20, fixing two problems:
 The list of issues addressed for 1.9.20.1 can be found
 https://github.com/eclipse/org.aspectj/issues?q=is%3Aissue+is%3Aclosed++milestone%3A1.9.20.1[here].
 
-== AspectJ 1.9.20
+= AspectJ 1.9.20
 
 _© Copyright 2023 Contributors. All rights reserved._
 
@@ -30,7 +35,7 @@ here:
 * https://github.com/eclipse/org.aspectj/issues?q=is%3Aissue+is%3Aclosed++milestone%3A1.9.20.1[GitHub 1.9.20.1]
 * https://bugs.eclipse.org/bugs/buglist.cgi?bug_status=RESOLVED&bug_status=VERIFIED&bug_status=CLOSED&f0=OP&f1=OP&f3=CP&f4=CP&j1=OR&list_id=16866879&product=AspectJ&query_format=advanced&target_milestone=1.9.20[Bugzilla 1.9.20]
 
-=== New features
+== New features
 
 AspectJ 1.9.20 supports https://openjdk.java.net/projects/jdk/20/[Java 20] and its final, preview and incubator
 features, such as:
@@ -45,7 +50,7 @@ some open issues concerning Java 20 preview feature support, see the list in
 https://github.com/eclipse/org.aspectj/issues/184#issuecomment-1272254940[this comment]. AJC therefore inherits the same
 problems for the specific cases described in the linked issues.
 
-=== Improvements
+== Improvements
 
 * Since Java 9 and the introduction of the Java Module System, the upstream Eclipse Java Compiler (ECJ) and Eclipse Java
   Development Tools (JDT) had gone through some internal changes, enabling both the compiler and the IDE to handle new
@@ -58,7 +63,7 @@ problems for the specific cases described in the linked issues.
   matching has been improved considerably. You can find some examples
   https://github.com/eclipse-aspectj/aspectj/tree/master/tests/bugs1920/github_24[here].
 
-=== Code examples
+== Code examples
 
 You can find some sample code in the AspectJ test suite under the respective AspectJ version in which the features were
 first supported (possibly as JVM preview features):
@@ -74,14 +79,14 @@ first supported (possibly as JVM preview features):
   concurrency features elsewhere, e.g. in the corresponding JEPs. In AspectJ, they should just work transparently like
   any other Java API.
 
-=== Other changes and bug fixes
+== Other changes and bug fixes
 
 * About a dozen bugs have been fixed, some of them quite old. See "list of issues addressed" further above and follow
   the link to GitHub to find out if your issue is among them.
 
-=== AspectJ usage hints
+== AspectJ usage hints
 
-==== AspectJ compiler build system requirements
+=== AspectJ compiler build system requirements
 
 Since 1.9.8, the AspectJ compiler `ajc` (contained in the `aspectjtools` library) no longer works on JDKs 8 to 10. The
 minimum compile-time requirement is now JDK 11 due to upstream changes in the Eclipse Java Compiler (subset of JDT
@@ -90,7 +95,7 @@ plain Java code or using plain Java ITD constructs which do not require the Aspe
 compiler itself needs JDK 11+. Just like in previous AspectJ versions, both the runtime `aspectjrt` and the load-time
 weaver `aspectjweaver` still only require JRE 8+.
 
-==== Use LTW on Java 16+
+=== Use LTW on Java 16+
 
 Please note that if you want to use load-time weaving on Java 16+, the weaving agent collides with
 https://openjdk.java.net/jeps/396[JEP 396 (Strongly Encapsulate JDK Internals by Default)]. Therefore, you need to set
@@ -98,7 +103,7 @@ the JVM parameter `--add-opens java.base/java.lang=ALL-UNNAMED` in order to enab
 fact that the weaver uses internal APIs for which we have not found an adequate replacement yet when defining classes
 in different classloaders.
 
-==== Compile with Java preview features
+=== Compile with Java preview features
 
 For features marked as preview on a given JDK, you need to compile with `ajc --enable-preview` and run with
 `java --enable-preview` on that JDK.
diff --git a/docs/release/README-1.9.21.adoc b/docs/release/README-1.9.21.adoc
index d205ed36d..66a38162e 100644
--- a/docs/release/README-1.9.21.adoc
+++ b/docs/release/README-1.9.21.adoc
@@ -1,4 +1,4 @@
-== AspectJ 1.9.21
+= AspectJ 1.9.21
 
 _© Copyright 2023 Contributors. All rights reserved._
 
@@ -12,7 +12,7 @@ here:
 * https://github.com/eclipse/org.aspectj/issues?q=is%3Aissue+is%3Aclosed++milestone%3A1.9.21.1[GitHub 1.9.21.1]
 * https://bugs.eclipse.org/bugs/buglist.cgi?bug_status=RESOLVED&bug_status=VERIFIED&bug_status=CLOSED&f0=OP&f1=OP&f3=CP&f4=CP&j1=OR&list_id=16866879&product=AspectJ&query_format=advanced&target_milestone=1.9.21[Bugzilla 1.9.21]
 
-=== New features
+== New features
 
 AspectJ 1.9.21 supports https://openjdk.java.net/projects/jdk/21/[Java 21], its final features and a subset of preview
 features, such as:
@@ -35,18 +35,18 @@ officially supported in Eclipse 2023-12, some preview features are still unimple
 As soon as these preview features are part of the upstream ECJ we depend on, we hope to publish another AspectJ release
 to support them in the AspectJ Compiler (AJC), too.
 
-=== Improvements
+== Improvements
 
 * In https://github.com/eclipse-aspectj/aspectj/issues/266[GitHub issue 266], exception cause reporting has been
   improved in `ExtensibleURLClassLoader`. Thanks to Andy Russell (@euclio) for his contribution.
 
-=== Other changes and bug fixes
+== Other changes and bug fixes
 
 * No major bug fixes
 
-=== AspectJ usage hints
+== AspectJ usage hints
 
-==== AspectJ compiler build system requirements
+=== AspectJ compiler build system requirements
 
 Since 1.9.21, the AspectJ compiler `ajc` (contained in the `aspectjtools` library) no longer works on JDKs 11 to 16. The
 minimum compile-time requirement is now JDK 17 due to upstream changes in the Eclipse Java Compiler (subset of JDT
@@ -62,7 +62,7 @@ details.
 
 History: Since 1.9.8, the AspectJ compiler ajc needed JDK 11+, before then JDK 8+.
 
-==== Use LTW on Java 16+
+=== Use LTW on Java 16+
 
 Please note that if you want to use load-time weaving on Java 16+, the weaving agent collides with
 https://openjdk.java.net/jeps/396[JEP 396 (Strongly Encapsulate JDK Internals by Default)] and related subsequent
@@ -70,7 +70,7 @@ JEPs. Therefore, you need to set the JVM parameter `--add-opens java.base/java.l
 aspect weaving. This is due to the fact that the weaver uses internal APIs for which we have not found an adequate
 replacement yet when defining classes in different classloaders.
 
-==== Compile with Java preview features
+=== Compile with Java preview features
 
 For features marked as preview on a given JDK, you need to compile with `ajc --enable-preview` and run with
 `java --enable-preview` on that JDK.
diff --git a/docs/release/README-1.9.3.adoc b/docs/release/README-1.9.3.adoc
index aa130dbc5..a242634a0 100644
--- a/docs/release/README-1.9.3.adoc
+++ b/docs/release/README-1.9.3.adoc
@@ -1,4 +1,4 @@
-== AspectJ 1.9.3
+= AspectJ 1.9.3
 
 _© Copyright 2018 Contributors. All rights reserved._
 
diff --git a/docs/release/README-1.9.4.adoc b/docs/release/README-1.9.4.adoc
index 72d6ca404..be667957d 100644
--- a/docs/release/README-1.9.4.adoc
+++ b/docs/release/README-1.9.4.adoc
@@ -1,4 +1,4 @@
-== AspectJ 1.9.4
+= AspectJ 1.9.4
 
 _© Copyright 2019 Contributors. All rights reserved._
 
diff --git a/docs/release/README-1.9.5.adoc b/docs/release/README-1.9.5.adoc
index 662c561bc..ddc0654a8 100644
--- a/docs/release/README-1.9.5.adoc
+++ b/docs/release/README-1.9.5.adoc
@@ -1,4 +1,4 @@
-== AspectJ 1.9.5
+= AspectJ 1.9.5
 
 _© Copyright 2019 Contributors. All rights reserved._
 
diff --git a/docs/release/README-1.9.6.adoc b/docs/release/README-1.9.6.adoc
index 0ecbc8967..3f22fbd3e 100644
--- a/docs/release/README-1.9.6.adoc
+++ b/docs/release/README-1.9.6.adoc
@@ -1,4 +1,4 @@
-== AspectJ 1.9.6
+= AspectJ 1.9.6
 
 _© Copyright 2020 Contributors. All rights reserved._
 
diff --git a/docs/release/README-1.9.7.adoc b/docs/release/README-1.9.7.adoc
index 1f96cd5bb..c58c78b5d 100644
--- a/docs/release/README-1.9.7.adoc
+++ b/docs/release/README-1.9.7.adoc
@@ -1,4 +1,4 @@
-== AspectJ 1.9.7
+= AspectJ 1.9.7
 
 _© Copyright 2021 Contributors. All rights reserved._
 
@@ -17,7 +17,7 @@ for Bugzilla] and
 https://github.com/eclipse/org.aspectj/issues?q=is%3Aissue+is%3Aclosed++milestone%3A1.9.7[here
 for GitHub issues].
 
-=== New features
+== New features
 
 AspectJ 1.9.7 supports https://openjdk.java.net/projects/jdk/15/[Java
 15] & https://openjdk.java.net/projects/jdk/16/[Java 16] and their
@@ -50,7 +50,7 @@ respective AspectJ version in which the features were first supported
 * https://github.com/eclipse/org.aspectj/tree/master/tests/features197/java15[AspectJ
 1.9.7: hidden classes, sealed classes]
 
-=== Using LTW on Java 16+
+== Using LTW on Java 16+
 
 Please note that if you want to use load-time weaving on Java 16+, the
 weaving agent collides with https://openjdk.java.net/jeps/396[JEP 396
@@ -60,7 +60,7 @@ order to enable aspect weaving. This is due to the fact that the weaver
 uses internal APIs for which we have not found an adequate replacement
 yet when defining classes in different classloaders.
 
-=== Organisational and internal changes
+== Organisational and internal changes
 
 For AspectJ 1.9.7, we implemented a lot of internal changes concerning
 the build and release process, most of which are not visible in the
@@ -86,7 +86,7 @@ enable users to re-test fixed bugs or try new features.
 This enables developers and contributors to make a choice if they want
 to work on Linux or on Windows.
 
-=== Other changes and bug fixes
+== Other changes and bug fixes
 
 * Remove legacy JRockit support.
 * Support Windows 10 and Windows Server 2016/2019 in installer. Those
diff --git a/docs/release/README-1.9.8.adoc b/docs/release/README-1.9.8.adoc
index 29b04ef7c..f42916a7b 100644
--- a/docs/release/README-1.9.8.adoc
+++ b/docs/release/README-1.9.8.adoc
@@ -1,4 +1,4 @@
-== AspectJ 1.9.8
+= AspectJ 1.9.8
 
 _© Copyright 2022 Contributors. All rights reserved._
 
@@ -9,14 +9,14 @@ https://github.com/eclipse/org.aspectj/issues/new[GitHub issues]. The list of is
 https://bugs.eclipse.org/bugs/buglist.cgi?bug_status=RESOLVED&bug_status=VERIFIED&bug_status=CLOSED&f0=OP&f1=OP&f3=CP&f4=CP&j1=OR&list_id=16866879&product=AspectJ&query_format=advanced&target_milestone=1.9.8[here for Bugzilla] and
 https://github.com/eclipse/org.aspectj/issues?q=is%3Aissue+is%3Aclosed++milestone%3A1.9.8[here for GitHub issues].
 
-=== New features
+== New features
 
 AspectJ 1.9.8 supports https://openjdk.java.net/projects/jdk/17/[Java 17] and its final and review features, such as:
 
 * Sealed classes (final in Java 17, previews in Java 15, 16 and AspectJ 1.9.7)
 * Pattern matching for `switch`
 
-=== Improvements
+== Improvements
 
 The `--release N` compiler option for correct cross-compilation to previous JDK bytecode + API versions is now supported
 by AJC. Previously, the option existed (inherited by ECJ) but did not work correctly.
@@ -32,7 +32,7 @@ feedback is positive and no negative side effects are found. Please try using th
 questions (to the AspectJ users mailing list) or problems (as a GitHub issue), if any. Thanks to Stefan Starke for his
 contribution. See also https://github.com/eclipse/org.aspectj/pull/37[PR #37].
 
-=== Code examples
+== Code examples
 
 You can find some sample code in the AspectJ test suite under the respective AspectJ version in which the features were
 first supported (possibly as JVM preview features):
@@ -42,7 +42,7 @@ first supported (possibly as JVM preview features):
   the JDK. Simply `-source 8 -target 8` would not be enough in this case.
 * https://github.com/eclipse/org.aspectj/tree/master/tests/features198/java17[Pattern matching for `switch`]
 
-=== Other changes and bug fixes
+== Other changes and bug fixes
 
 * The AspectJ compiler `ajc` (contained in the `aspectjtools` library) no longer works on JDKs 8 to 10. The minimum
   compile-time requirement is now JDK 11 due to upstream changes in the Eclipse Java Compiler (subset of JDT Core),
@@ -65,9 +65,9 @@ first supported (possibly as JVM preview features):
 * Thanks to Andrey Turbanov for several clean code contributions and to Dmitry Mikhaylov for fixing a potential
   concurrency problem.
 
-=== AspectJ usage hints
+== AspectJ usage hints
 
-==== Use LTW on Java 16+
+=== Use LTW on Java 16+
 
 Please note that if you want to use load-time weaving on Java 16+, the weaving agent collides with
 https://openjdk.java.net/jeps/396[JEP 396 (Strongly Encapsulate JDK Internals by Default)]. Therefore, you need to set
@@ -75,7 +75,7 @@ the JVM parameter `--add-opens java.base/java.lang=ALL-UNNAMED` in order to enab
 fact that the weaver uses internal APIs for which we have not found an adequate replacement yet when defining classes
 in different classloaders.
 
-==== Compile with Java preview features
+=== Compile with Java preview features
 
 For features marked as preview on a given JDK, you need to compile with `ajc --enable-preview` and run with
 `java --enable-preview` on that JDK.
diff --git a/docs/release/README-1.9.9.adoc b/docs/release/README-1.9.9.adoc
index 900f70b89..b4dda99ba 100644
--- a/docs/release/README-1.9.9.adoc
+++ b/docs/release/README-1.9.9.adoc
@@ -1,4 +1,8 @@
-== AspectJ 1.9.9.1
+= AspectJ 1.9.9
+:doctype: book
+:leveloffset: +1
+
+= AspectJ 1.9.9.1
 
 _© Copyright 2022 Contributors. All rights reserved._
 
@@ -12,7 +16,7 @@ This probably was broken for a long time. AspectJ still is not boasting extensiv
 this improvement seems substantial enough to justify a minor release, instead of keeping users waiting for the next
 regular release.
 
-== AspectJ 1.9.9
+= AspectJ 1.9.9
 
 _© Copyright 2022 Contributors. All rights reserved._
 
@@ -26,13 +30,13 @@ here:
 * https://github.com/eclipse/org.aspectj/issues?q=is%3Aissue+is%3Aclosed++milestone%3A1.9.9.1[GitHub 1.9.9.1]
 * https://bugs.eclipse.org/bugs/buglist.cgi?bug_status=RESOLVED&bug_status=VERIFIED&bug_status=CLOSED&f0=OP&f1=OP&f3=CP&f4=CP&j1=OR&list_id=16866879&product=AspectJ&query_format=advanced&target_milestone=1.9.9[Bugzilla 1.9.9]
 
-=== New features
+== New features
 
 AspectJ 1.9.9 supports https://openjdk.java.net/projects/jdk/18/[Java 18] and its final and preview features, such as:
 
 * Pattern matching for `switch` (preview 2)
 
-=== Improvements
+== Improvements
 
 In annotation style aspects, asynchronous `proceed()` calls in `@Around` advice now works in threads created from within
 the advice. Previously, this was only working in native syntax aspects. There is still a limitation with regard to
@@ -42,7 +46,7 @@ own thread pool. This still is not working in annotation style aspects, only in
 See https://github.com/eclipse/org.aspectj/issues/128[issue #128] and
 https://github.com/eclipse/org.aspectj/pull/132[pull request #132] for more details.
 
-=== Code examples
+== Code examples
 
 You can find some sample code in the AspectJ test suite under the respective AspectJ version in which the features were
 first supported (possibly as JVM preview features):
@@ -52,7 +56,7 @@ first supported (possibly as JVM preview features):
 * https://github.com/eclipse/org.aspectj/tree/master/tests/bugs199/github_128[Asynchronous proceed in native vs.
   annotation style syntax]
 
-=== Other changes and bug fixes
+== Other changes and bug fixes
 
 * Fix a bug which led to ``NullPointerException``s, if too many JAR archives were on the classpath. Too many here means
   the value of system property `org.aspectj.weaver.openarchives` (1,000 by default). The AspectJ compiler is meant to
@@ -64,9 +68,9 @@ first supported (possibly as JVM preview features):
   https://github.com/eclipse/org.aspectj/issues/122[#122].
 * Thanks to Andrey Turbanov for several clean code contributions.
 
-=== AspectJ usage hints
+== AspectJ usage hints
 
-==== AspectJ compiler build system requirements
+=== AspectJ compiler build system requirements
 
 Since 1.9.8, the AspectJ compiler `ajc` (contained in the `aspectjtools` library) no longer works on JDKs 8 to 10. The
 minimum compile-time requirement is now JDK 11 due to upstream changes in the Eclipse Java Compiler (subset of JDT
@@ -75,7 +79,7 @@ plain Java code or using plain Java ITD constructs which do not require the Aspe
 compiler itself needs JDK 11+. Just like in previous AspectJ versions, both the runtime `aspectjrt` and the load-time
 weaver `aspectjweaver` still only require JRE 8+.
 
-==== Use LTW on Java 16+
+=== Use LTW on Java 16+
 
 Please note that if you want to use load-time weaving on Java 16+, the weaving agent collides with
 https://openjdk.java.net/jeps/396[JEP 396 (Strongly Encapsulate JDK Internals by Default)]. Therefore, you need to set
@@ -83,7 +87,7 @@ the JVM parameter `--add-opens java.base/java.lang=ALL-UNNAMED` in order to enab
 fact that the weaver uses internal APIs for which we have not found an adequate replacement yet when defining classes
 in different classloaders.
 
-==== Compile with Java preview features
+=== Compile with Java preview features
 
 For features marked as preview on a given JDK, you need to compile with `ajc --enable-preview` and run with
 `java --enable-preview` on that JDK.
diff --git a/docs/release/changes.adoc b/docs/release/changes.adoc
index 5b08e48ae..5a790a0ff 100644
--- a/docs/release/changes.adoc
+++ b/docs/release/changes.adoc
@@ -1,39 +1,38 @@
-== Changes in AspectJ
+= Changes in AspectJ
+:doctype: book
+:leveloffset: +1
 
 _© Copyright 1998-2002 Palo Alto Research Center Incorporated
 2003-2008 Contributors. All rights reserved._
 
-* xref:#_1_6_0[1.6.0] (released 2008-04)
-* xref:#_1_5_4[1.5.4] (released 2007-12)
-* xref:#_1_5_3[1.5.3] (released 2006-11)
-* xref:#_1_5_2[1.5.2] (released 2006-06)
-* xref:#_1_5_1[1.5.1] (released 2006-04)
-* xref:#_1_5_0[1.5.0] (released 2005-12)
-* xref:#_1_2_1[1.2.1] (released 2004-10)
-* xref:#_1_2[1.2] (released 2004-05)
-* xref:#_1_1_1[1.1.1] (released 2003-09)
-* 1.1.0 (released 2003-06-06) See xref:README-1.1.adoc#readme-1_1[1.1.0 release notes].
-* xref:#_1_0_6[1.0.6] (released 2002-07-24)
-** xref:#_1_0_6compiler[Compiler]
-** xref:#_1_0_6ajde[AJDE]
-** xref:#_1_0_6ajdoc[Ajdoc]
-* xref:#_1_0_5[1.0.5] (released 2002-06-27)
-* xref:#_1_0_4[1.0.4] (released 2002-04-17)
-* xref:#_1_0_3[1.0.3] (released 2002-02-08)
-* xref:#_1_0_2[1.0.2] (released 2002-02-06)
-* xref:#_1_0_1[1.0.1] (released 2001-12-18)
-* xref:#_1_0_0[1.0.0] (released 2001-11-30)
-* xref:#_1_0rc3[1.0rc3] (released 2001-11-14)
-* xref:#_1_0rc2[1.0rc2] (released 2001-10-12)
-* xref:#_1_0rc1[1.0rc1] (released 2001-10-5)
-* xref:#_1_0beta1[1.0beta1] (released 2001-08-29)
-* xref:#_1_0alpha1[1.0alpha1] (released 2001-08-09)
+* xref:#_1_6_0[AspectJ 1.6.0] (released 2008-04)
+* xref:#_1_5_4[AspectJ 1.5.4] (released 2007-12)
+* xref:#_1_5_3[AspectJ 1.5.3] (released 2006-11)
+* xref:#_1_5_2[AspectJ 1.5.2] (released 2006-06)
+* xref:#_1_5_1[AspectJ 1.5.1] (released 2006-04)
+* xref:#_1_5_0[AspectJ 1.5.0] (released 2005-12)
+* xref:#_1_2_1[AspectJ 1.2.1] (released 2004-10)
+* xref:#_1_2[AspectJ 1.2] (released 2004-05)
+* xref:#_1_1_1[AspectJ 1.1.1] (released 2003-09)
+* AspectJ 1.1.0 (released 2003-06-06) See xref:README-1.1.adoc#readme-1_1[release notes].
+* xref:#_1_0_6[AspectJ 1.0.6] (released 2002-07-24)
+* xref:#_1_0_5[AspectJ 1.0.5] (released 2002-06-27)
+* xref:#_1_0_4[AspectJ 1.0.4] (released 2002-04-17)
+* xref:#_1_0_3[AspectJ 1.0.3] (released 2002-02-08)
+* xref:#_1_0_2[AspectJ 1.0.2] (released 2002-02-06)
+* xref:#_1_0_1[AspectJ 1.0.1] (released 2001-12-18)
+* xref:#_1_0_0[AspectJ 1.0.0] (released 2001-11-30)
+* xref:#_1_0rc3[AspectJ 1.0rc3] (released 2001-11-14)
+* xref:#_1_0rc2[AspectJ 1.0rc2] (released 2001-10-12)
+* xref:#_1_0rc1[AspectJ 1.0rc1] (released 2001-10-5)
+* xref:#_1_0beta1[AspectJ 1.0beta1] (released 2001-08-29)
+* xref:#_1_0alpha1[AspectJ 1.0alpha1] (released 2001-08-09)
 * xref:porting.adoc[Porting and Transition]
 
 '''''
 
 [[_1_6_0]]
-== 1.6.0
+= AspectJ 1.6.0
 
 This release rebases AspectJ on the Eclipse Compiler version 785_R33X -
 making it Java6 compliant.
@@ -42,7 +41,7 @@ A full list of bugs fixed and enhancements implemented can be found in
 https://bugs.eclipse.org/bugs/buglist.cgi?query_format=advanced&short_desc_type=allwordssubstr&short_desc=&product=AspectJ&target_milestone=1.6.0+M1&target_milestone=1.6.0+M2&target_milestone=1.6.0+RC1&target_milestone=1.6.0&long_desc_type=allwordssubstr&long_desc=&bug_file_loc_type=allwordssubstr&bug_file_loc=&status_whiteboard_type=allwordssubstr&status_whiteboard=&keywords_type=allwords&keywords=&bug_status=RESOLVED&bug_status=VERIFIED&bug_status=CLOSED&emailtype1=substring&email1=&emailtype2=substring&email2=&bugidtype=include&bug_id=&votes=&chfieldfrom=&chfieldto=Now&chfieldvalue=&cmdtype=doit&order=Reuse+same+sort+as+last+time&field0-0-0=noop&type0-0-0=noop&value0-0-0=[Bugzilla].
 
 [[_1_5_4]]
-== 1.5.4
+= AspectJ 1.5.4
 
 This release contains around 40 bug fixes and enhancements since the
 1.5.3 release.
@@ -52,7 +51,7 @@ https://bugs.eclipse.org/bugs/buglist.cgi?query_format=advanced&product=AspectJ&
 Bugzilla
 
 [[_1_5_3]]
-== 1.5.3
+= AspectJ 1.5.3
 
 This release contains around 80 bug fixes and enhancements since the
 1.5.2 release.
@@ -62,7 +61,7 @@ https://bugs.eclipse.org/bugs/buglist.cgi?query_format=advanced&product=AspectJ&
 Bugzilla
 
 [[_1_5_2]]
-== 1.5.2
+= AspectJ 1.5.2
 
 This release contains around 60 bug fixes and enhancements since the
 1.5.1 release.
@@ -72,7 +71,7 @@ https://bugs.eclipse.org/bugs/buglist.cgi?query_format=advanced&product=AspectJ&
 Bugzilla
 
 [[_1_5_1]]
-== 1.5.1
+= AspectJ 1.5.1
 
 This release contains over 70 bug fixes and enhancements since the 1.5.0
 release.
@@ -82,19 +81,19 @@ https://bugs.eclipse.org/bugs/buglist.cgi?query_format=advanced&product=AspectJ&
 Bugzilla
 
 [[_1_5_0]]
-== 1.5.0
+= AspectJ 1.5.0
 
 This release contains nearly 400 bug fixes and enhancements since the
 1.2.1 release. Major updates to the language are documented in the
-xref:../../adk15notebook/adk15notebook.adoc[AspectJ 5 Developer's Notebook]. There are
+xref:../adk15notebook/adk15notebook.adoc[AspectJ 5 Developer's Notebook]. There are
 also a number of enhancements to accompanying tools documented in the
-link:devguide/index.html[Developer's Guide]
+xref:../devguide/index.adoc[Developer's Guide]
 
 A full list of bugs fixed in AspectJ 5 can be found in
 https://bugs.eclipse.org/bugs/buglist.cgi?query_format=advanced&short_desc_type=allwordssubstr&product=AspectJ&resolution=FIXED&chfieldfrom=2004-11-06&chfieldto=2005-12-20[bugzilla].
 
 [[_1_2_1]]
-== 1.2.1
+= AspectJ 1.2.1
 
 All known P1 and P2 bugs have been fixed in this release. The
 https://bugs.eclipse.org/bugs/buglist.cgi?product=AspectJ&target_milestone=1.2.1&bug_status=RESOLVED&resolution=FIXED[full
@@ -214,7 +213,7 @@ subset of aspectjtools.jar needed for weaving. The "aj" script is also
 moved into the bin directory.
 
 [[_1_2]]
-== 1.2
+= AspectJ 1.2
 
 All known P1 and P2 bugs have been fixed in this release. The
 https://bugs.eclipse.org/bugs/buglist.cgi?product=AspectJ&target_milestone=1.2[full
@@ -341,7 +340,7 @@ local storage used to manage cflow stacks when available - improves
 cflow performance when working with a multi-threaded application.
 
 [[_1_1_1]]
-== 1.1.1
+= AspectJ 1.1.1
 
 All known P1 and P2 bugs have been fixed in this release. The
 https://bugs.eclipse.org/bugs/buglist.cgi?product=AspectJ&target_milestone=1.1.1[full
@@ -398,12 +397,12 @@ ajc to compile JSP's in Tomcat. Thanks to Ron Bodkin for investigating
 how to integrate ajc with Tomcat.
 
 [[_1_0_6]]
-== 1.0.6
+= AspectJ 1.0.6
 
 This release contains mainly bug fixes for ajde and ajdoc.
 
 [[_1_0_6compiler]]
-=== Compiler
+== Compiler
 
 We fixed a bug with switch statements, thanks largely to Jason Rimmer's
 diligence in helping us isolate the problem. Also, to help Log4J parse
@@ -411,7 +410,7 @@ stack traces, we changed class file symbolic line references to use []
 instead of () for the virtual start lines of each file.
 
 [[_1_0_6ajde]]
-=== AJDE
+== AJDE
 
 *AJDE Framework, AJBrowser, and AJDE for Forte/NetBeans*
 
@@ -420,7 +419,7 @@ reduce footprint when working with large systems.  Error tolerance has
 also been improved for dealing with a structure model that is out of
 synch with resources on disk.
 
-==== AJDE for JBuilder
+=== AJDE for JBuilder
 
 JBuilder 7 is now supported.  All known bugs have been fixed including:
 
@@ -442,7 +441,7 @@ JBuilder OpenTools with AJDE/JBuilder, the OpenTool is now being built
 with itself.
 
 [[_1_0_6ajdoc]]
-=== Ajdoc
+== Ajdoc
 
 * Fixed http://aspectj.org/bugs/resolved?id=790[790] aspect code
 comments suppressed by fix to bug 710
@@ -451,7 +450,7 @@ comments suppressed by fix to bug 710
 '''''
 
 [[_1_0_5]]
-== 1.0.5
+= AspectJ 1.0.5
 
 This release includes significant improvements to AspectJ Development
 Environment (AJDE) support. The entire user interface has been revised
@@ -466,7 +465,7 @@ tool.
 * xref:#_1_0_5anttasks[Ant tasks]
 
 [[_1_0_5compiler]]
-=== Compiler
+== Compiler
 
 This was another compiler release primarily concerned with fixing corner
 cases in the language implementation. Our handling of nested classes,
@@ -475,9 +474,14 @@ Thanks to Nicholas Alex Leidenfrost and Patrick Chan for their clear and
 concise bug reports on some of these issues.
 
 [[_1_0_5ajde]]
-=== AJDE
+== AJDE
 
-==== This release includes significant improvements to AspectJ Development Environment (AJDE) support. All known bugs have been fixed, and the core framework quality has been significantly increased thanks to the adoption of a unit test suite. The following changes apply to all of the AJDE NetBeans/Forte, JBuilder, and the AspectJ Browser support. NetBeans/Forte and JBuilder-specific changes are listed below.
+This release includes significant improvements to AspectJ Development
+Environment (AJDE) support. All known bugs have been fixed, and the core
+framework quality has been significantly increased thanks to the adoption of a
+unit test suite. The following changes apply to all of the AJDE NetBeans/Forte,
+JBuilder, and the AspectJ Browser support. NetBeans/Forte and JBuilder-specific
+changes are listed below.
 
 * The entire user interface has been revised and streamlined.
 * The structure view and browser have a new UI, and offer both a
@@ -491,7 +495,7 @@ crosscutting structure.
 * Error messages have been improved, and the structure views include
 annotations of nodes with errors and warnings.
 
-==== AJDE for JBuilder
+=== AJDE for JBuilder
 
 Integration into the JBuilder IDE is more streamlined. In addition:
 
@@ -514,7 +518,7 @@ double-clicking ".lst" files that have been added to the project.
 * Error messages now match JBuilder's look-and-feel and behavior.
 Seeking to column numbers now works in addition to line numbers.
 
-==== AJDE for Forte/NetBeans
+=== AJDE for Forte/NetBeans
 
 Integration into the NetBeans IDE is more streamlined. In addition:
 
@@ -529,7 +533,7 @@ configuration.
 * Class files are generated beside source files (NetBeans/javac
 default). There is currently no way to specify a target directory.
 
-==== AJBrowser
+=== AJBrowser
 
 * The browser now supports main class execution. Set the main class in
 the options dialog, and make sure that both the Java executable is on
@@ -537,7 +541,7 @@ your path, and the class that you expect to execute on your classpath.
 * The error messages UI has been improved.
 
 [[_1_0_5ajdoc]]
-=== Ajdoc
+== Ajdoc
 
 Bug fixes:
 
@@ -552,7 +556,7 @@ docs for methods or constructors declared on other types.]
 resource]
 
 [[_1_0_5anttasks]]
-=== Ant tasks
+== Ant tasks
 
 Bug fixes:
 
@@ -562,7 +566,7 @@ ajc flags]
 '''''
 
 [[_1_0_4]]
-== 1.0.4
+= AspectJ 1.0.4
 
 * xref:#_1_0_4compiler[Compiler]
 * xref:#_1_0_4ajde[AJDE]
@@ -571,7 +575,7 @@ ajc flags]
 * xref:#_1_0_4doc[Documentation]
 
 [[_1_0_4compiler]]
-=== Compiler
+== Compiler
 
 * Over a dozen people independently reported a bug in error handling for
 the wrong number number of arguments to `proceed`. This has been turned
@@ -587,7 +591,7 @@ language spec.
 Language Spec have been fixed in this release. Thanks to Neal Gafter for
 reporting many of these.
 
-==== Incompatible changes
+=== Incompatible changes
 
 Two potentially surprising incompatible changes have been made to ajc in
 order to bring the compiler into compliance with the 1.0 language
@@ -609,19 +613,19 @@ of these changes can be found in the xref:porting.adoc#pre-1_0_4[porting
 notes].
 
 [[_1_0_4ajde]]
-=== AJDE
+== AJDE
 
 This is the first release of AJDE support with significant external
 contribution. A big thanks goes out to Phil Sager for porting the AJDE
 for Forte/NetBeans support to NetBeans 3.3.1 and improving the
 integration into NetBeans.
 
-==== AJDE for JBuilder
+=== AJDE for JBuilder
 
 * Updates
 ** This is a bug fix release only.
 
-==== AJDE for Forte/NetBeans
+=== AJDE for Forte/NetBeans
 
 * Updates
 ** NetBeans 3.3.1 is now supported in addition to NetBeans 3.2 and Forte
@@ -638,18 +642,18 @@ Explorer, right-click the class and select "Execute".
 source code. The "AspectJ" Explorer understands the structure of AspectJ
 projects and should be used for navigating structure instead.
 
-==== AJDE for Emacs
+=== AJDE for Emacs
 
 * This is a bug fix release only.
 
 [[_1_0_4ajdoc]]
-=== Ajdoc
+== Ajdoc
 
 Ajdoc now runs under J2SE 1.4, but still requires the tools.jar from
 J2SE 1.3 be on the classpath.
 
 [[_1_0_4taskdefs]]
-=== Ant tasks
+== Ant tasks
 
 * Repackaged to fit into the AspectJ product directory - e.g.,
 `aspectj-ant.jar` moved to `lib` as expected by `examples/build.xml`.
@@ -657,7 +661,7 @@ J2SE 1.3 be on the classpath.
 BuildException if failonerror and ajdoc detects misconfiguration.
 
 [[_1_0_4doc]]
-=== Documentation
+== Documentation
 
 Added a 1-page quick reference guide. Improved javadoc documentation for
 the org.aspectj.lang package.
@@ -665,13 +669,13 @@ the org.aspectj.lang package.
 '''''
 
 [[_1_0_3]]
-== 1.0.3
+= AspectJ 1.0.3
 
 * xref:#_1_0_3compiler[Compiler]
 * xref:#_1_0_3taskdefs[Ant taskdefs]
 
 [[_1_0_3compiler]]
-=== Compiler
+== Compiler
 
 This release fixes a single significant bug in 1.0.2 where ajc could
 generate unreachable code in `-usejavac` or `-preprocess` mode. This
@@ -681,7 +685,7 @@ flow-analysis for this case and generate code that is acceptable to
 javac. Thanks to Rich Price for reporting this bug.
 
 [[_1_0_3taskdefs]]
-=== Ant taskdefs
+== Ant taskdefs
 
 Added support to the Ajc taskdef for the -source 1.4 and -X options
 generally.
@@ -689,7 +693,7 @@ generally.
 '''''
 
 [[_1_0_2]]
-== 1.0.2
+= AspectJ 1.0.2
 
 This release is mainly about keeping up with the Joneses. To keep up
 with SUN's release candidate for J2SE1.4, we now officially support the
@@ -705,7 +709,7 @@ reported in 1.0.1.
 * xref:#_1_0_2ajdb[AJDB]
 
 [[_1_0_2compiler]]
-=== Compiler
+== Compiler
 
 * Official support for `-source 1.4` option to compile new
 http://java.sun.com/j2se/1.4/docs/guide/lang/assert.html[1.4
@@ -748,7 +752,7 @@ javac].
 using the latest `aspectjrt.jar`
 
 [[_1_0_2ajde]]
-=== AJDE
+== AJDE
 
 This is a bug fix release only.
 
@@ -760,7 +764,7 @@ view) have been fixed.
 * Other GUI and usability improvements have been made the AspectJ
 Browser and core framework.
 
-==== AJDE for JBuilder
+=== AJDE for JBuilder
 
 * Support has been extended to JBuilder 6, and support for Enterprise
 version features has been improved.
@@ -768,12 +772,12 @@ version features has been improved.
 not be updated after a recompile.
 * Keyboard shortcuts were fixed to work with Mac OSX.
 
-==== AJDE for Forte
+=== AJDE for Forte
 
 * Keyboard shortcuts were fixed to work with Mac OSX.
 
 [[_1_0_2ajdb]]
-==== AJDB
+=== AJDB
 
 Some minor bug fixes, but this is still early-access software. Please
 try using another JPDA-compliant debugger. If it uses JDI correctly,
@@ -784,14 +788,14 @@ would appreciate any reports of success or failure.
 '''''
 
 [[_1_0_1]]
-== 1.0.1
+= AspectJ 1.0.1
 
 * xref:#_1_0_1compiler[Compiler]
 * xref:#_1_0_1ajde[AJDE]
 * xref:#_1_0_1ajdb[AJDB]
 
 [[_1_0_1compiler]]
-=== Compiler
+== Compiler
 
 This release fixes a significant performance issue in the compiler,
 reported by Rich Price, that could lead to extremely long compiles in
@@ -809,7 +813,7 @@ expected that this prefix will either become the default compiler
 behavior in the future or a non-experimental flag will replace it.
 
 [[_1_0_1ajde]]
-=== AJDE
+== AJDE
 
 Minor bug fixes, including: AJDE for JBuilder failed to preserve
 application parameters from project settings when executing the
@@ -818,7 +822,7 @@ application.
 Source builds were cleaned up for JBuilder and Forte sources.
 
 [[_1_0_1ajdb]]
-=== AJDB
+== AJDB
 
 Two bugs were reported and have been fixed in this release. (Note that
 ajdb is still considered early-access software.)
@@ -827,7 +831,7 @@ ajdb is still considered early-access software.)
 * bug 617: -X and -D options not passed to debug VM correctly
 
 [[_1_0_0]]
-== 1.0.0
+= AspectJ 1.0.0
 
 * xref:#_1_0_0language[Language]
 * xref:#_1_0_0compiler[Compiler]
@@ -891,7 +895,7 @@ http://aspectj.org/docs
 * [AJDEE only] Improved filtering of legal code completions.
 
 [[_1_0_0ajdoc]]
-=== AJDoc
+== AJDoc
 
 * Runs only in J2SE 1.3 - not 1.2 or 1.4. You can document 1.x-reliant
 programs by using the options to compile using 1.x libraries.
@@ -899,12 +903,12 @@ programs by using the options to compile using 1.x libraries.
 the syntax message.
 
 [[_1_0_0taskdefs]]
-=== Ant taskdefs
+== Ant taskdefs
 
 * Fork is not supported in the AJDoc taskdef
 
 [[_1_0rc3]]
-== 1.0rc3
+= AspectJ 1.0rc3
 
 [[_1_0rc3language]]
 == Language
@@ -1003,7 +1007,7 @@ right-clicking to select the "Display Sources" command.
 completion, ajdoc launch, and speedbar.
 
 [[_1_0rc3ajdoc]]
-=== AJDoc
+== AJDoc
 
 Some of the more obvious NullPointerException bugs in Ajdoc were fixed,
 but Ajdoc does not implement all the functionality of Javadoc and has
@@ -1024,7 +1028,7 @@ Further, Ajdoc has not been testing on variants of the J2SE (it uses
 javadoc classes).
 
 [[_1_0rc3taskdefs]]
-=== Ant taskdefs
+== Ant taskdefs
 
 The Ajc taskdef was updated to support the new compiler options and the
 .aj extension, and some NullPointerException bugs were fixed (thanks to
@@ -1036,7 +1040,7 @@ $\{ant.home}/lib.
 '''''
 
 [[_1_0rc2]]
-== 1.0rc2
+= AspectJ 1.0rc2
 
 * xref:#_1_0rc2language[Language]
 * xref:#_1_0rc2compiler[Compiler]
@@ -1114,7 +1118,7 @@ properly when changing directories.
 '''''
 
 [[_1_0rc1]]
-== 1.0rc1
+= AspectJ 1.0rc1
 
 * xref:#_1_0rc1language[Language]
 * xref:#_1_0rc1compiler[Compiler]
@@ -1215,7 +1219,7 @@ computational overhead.
 '''''
 
 [[_1_0beta1]]
-== 1.0beta1
+= AspectJ 1.0beta1
 
 * xref:#_1_0beta1language[Language]
 * xref:#_1_0beta1compiler[Compiler]
@@ -1305,7 +1309,7 @@ beanshell is no longer required for use of these modes.
 '''''
 
 [[_1_0alpha1]]
-== 1.0alpha1
+= AspectJ 1.0alpha1
 
 This is the first alpha release of the 1.0 language and tools. There
 have been many changes in the language, and many improvements to the
@@ -1321,7 +1325,7 @@ volatility of AspectJ in the push to 1.0.
 * xref:#_1_0alpha1ajde[AJDE]
 
 [[_1_0alpha1language]]
-=== Language
+== Language
 
 There have been many changes to make the 1.0 language both simpler and
 more powerful. User feedback has driven most of these design changes.
@@ -1341,7 +1345,7 @@ pointcuts, more flexible dominates, and many other improvements).
 Note that entries into the xref:porting.adoc[porting notes] for this
 release are linked from the various language changes.
 
-==== Pointcuts
+=== Pointcuts
 
 Perhaps the least interesting -- but most pervasive -- change is that
 the names of the single-kinded pointcut designators (the ones that pick
@@ -1411,7 +1415,7 @@ Non-abstract pointcuts may now be declared `final`.
 We have finally added an extremely general pointcut,
 `if(BooleanExpression)`, that picks out join points programatically.
 
-==== Type patterns
+=== Type patterns
 
 Our treatment of xref:porting.adoc#_1_0a1-new-wildcards[* and ..] in type
 patterns is cleaner.
@@ -1421,7 +1425,7 @@ a new wildcard, +, to pick out all subtypes of a given type. Previously,
 the subtypes operator was only allowed in introduction, and was
 xref:porting.adoc#_1_0a1-subtypes-to-plus[spelled differently].
 
-==== Advice
+=== Advice
 
 Around advice is treated much more like a method, with a
 xref:porting.adoc#_1_0a1-around-returns[return value] and an optional
@@ -1442,7 +1446,7 @@ xref:porting.adoc#_1_0a1-this-static-join-point[renamed], and the
 `thisJoinPoint` object hierarchy has been
 xref:porting.adoc#_1_0a1-this-join-point[simplified].
 
-==== Introduction and static crosscutting
+=== Introduction and static crosscutting
 
 On the static side of the language, introduction hasn't changed, but
 there is now a new keyword, `declare`, that is used to declare various
@@ -1462,7 +1466,7 @@ checked exceptions into an unchecked form. This may affect some uses of
 xref:porting.adoc#_1_0a1-now-use-soft[around advice] that previously
 mucked with the exception checking system.
 
-==== Aspects
+=== Aspects
 
 The "of each" modifiers have been
 xref:porting.adoc#_1_0a1-aspects[renamed]. Apart from the spelling, the
@@ -1476,7 +1480,7 @@ dominate the advice of another aspect B as well as its subtypes, with
 the new + subtypes operator: `aspect A dominates B+`.
 
 [[_1_0alpha1compiler]]
-=== Compiler
+== Compiler
 
 The most important change in the compiler is that it supports the new
 language. In addition, all reported bugs in the last release have been
@@ -1487,7 +1491,7 @@ handling source files that are not in standard US-ASCII format. Thanks
 to Nakamura Tadashi for both suggesting this feature and for submitting
 a nice patch to implement it.
 
-==== Known Limitations
+=== Known Limitations
 
 The previous compiler's limitations regarding join points that occurred
 in anonymous classes have all been eliminated. Unfortunately,
@@ -1500,7 +1504,7 @@ Moreover, some errors regarding the initialization of final fields might
 never show up when using ajc. This will be fixed shortly.
 
 [[_1_0alpha1documentation]]
-=== Documentation
+== Documentation
 
 Although we spent much of our time this release cycle updating the
 documentation to the new language rather than improving its content, we
@@ -1511,7 +1515,7 @@ printable versions of both guides (in PDF) are finally included in the
 documentation package.
 
 [[_1_0alpha1ajdoc]]
-=== Ajdoc
+== Ajdoc
 
 Ajdoc was rewritten to conform with the language changes and provide
 support for other AspectJ/Java compilers. Our doclet is used by default
@@ -1520,29 +1524,29 @@ used by passing the '-standard' flag to Ajdoc to produce regular Javadoc
 documentation (excluding AspectJ-specifics).
 
 [[_1_0alpha1ant]]
-=== Ant
+== Ant
 
 An Ajdoc task is now available. The Ajc ant task was improved to be
 completely back-compatible with the Javac task.
 
 [[_1_0alpha1ajbrowser]]
-=== AJBrowser
+== AJBrowser
 
 The "AspectJ Browser" is a new standalone source code browsing
 application. It will let you compile ".lst" files, view the structure
 for those files and navigate the corresponding source code.
 
 [[_1_0alpha1ajde]]
-=== AJDE
+== AJDE
 
-==== AJDE for JBuilder
+=== AJDE for JBuilder
 
-===== Installation
+==== Installation
 
 * Use the installer to place the "ajdeForJBuilder.jar" and
 "aspectjrt.jar" in to JBuilder's lib/ext directory.
 
-===== Key Improvements
+==== Key Improvements
 
 * The "AspectJ Structure View" replaces JBuilder's structure view
 instead of being launched in a separate window.
@@ -1552,7 +1556,7 @@ removed.
 * Projects no longer require the manual adding of the "aspectjrt.jar"
 libarary.
 
-===== Known Bugs & Limitations
+==== Known Bugs & Limitations
 
 * There is no compiler progress dialog--the way to tell if the compile
 is finished is to watch the "status" area of the main window.
@@ -1564,9 +1568,9 @@ is limited.
 * There is no ajdoc tool support.
 * Linux testing has been very limited.
 
-==== AJDE for Forte
+=== AJDE for Forte
 
-===== Installation
+==== Installation
 
 * Use the installer to place the "ajdeForForte.jar" in Forte's modules
 directory and "aspectjrt.jar" in to Forte's lib/ext directory.
@@ -1575,7 +1579,7 @@ directory and "aspectjrt.jar" in to Forte's lib/ext directory.
 * Find the ajdeForForte.jar in the directory that you installed into
 (e.g. c:\forte4j\modules) and select it.
 
-===== Key Improvements
+==== Key Improvements
 
 * AJDE can be toggled on/off with the "AJ" button--when it is turned off
 all of the menus, resources, and event listeners that it uses will be
@@ -1583,7 +1587,7 @@ removed.
 * The AJDE functionality is now contained within it's own toolbar and
 menu.
 
-===== Known Bugs & Limitations
+==== Known Bugs & Limitations
 
 * "Mode" switching is not supported in this version--you must do all of
 your AspectJ work in the "Editing" mode. If you switch modes the IDE has
@@ -1598,7 +1602,7 @@ is limited.
 * There is no ajdoc tool support.
 * Linux testing has been very limited.
 
-==== AJDE for Emacs
+=== AJDE for Emacs
 
 AspectJ-mode now includes a toggle in the AspectJ menu that disables its
 intrusive functions, enabling easy switching between Java and AspectJ
diff --git a/docs/release/porting.adoc b/docs/release/porting.adoc
index 31f3016ae..b86a80d16 100644
--- a/docs/release/porting.adoc
+++ b/docs/release/porting.adoc
@@ -1,4 +1,4 @@
-== AspectJ Porting Notes
+= AspectJ Porting Notes
 
 _© Copyright 1998-2002 Palo Alto Research Center Incorporated,
 2003-2004 Contributors. All rights reserved._
@@ -15,7 +15,7 @@ _© Copyright 1998-2002 Palo Alto Research Center Incorporated,
 * xref:#pre07b10[Pre-0.7beta10 code]
 
 [[pre-1_2]]
-=== Porting pre-1.2 code to AspectJ 1.2
+== Porting pre-1.2 code to AspectJ 1.2
 
 README-1.2.html contains a discussion of the changes between 1.1 and 1.2.
 The key points are:
@@ -190,7 +190,7 @@ https://bugs.eclipse.org/bugs/show_bug.cgi?id=60389[60389],
 https://bugs.eclipse.org/bugs/show_bug.cgi?id=59921[59921].
 
 [[pre-1_1]]
-=== Porting pre-1.1 code to AspectJ 1.1
+== Porting pre-1.1 code to AspectJ 1.1
 
 README-1.1.html contains a discussion of the language changes from 1.0 to
 1.1. The high points:
@@ -244,7 +244,7 @@ used in declare error or declare warning statements, which might produce
 different results. (xref:README-1.1.adoc#WITHIN_MEMBER_TYPES[more info])
 
 The compiler will report an error that the form
-`aspect {name} dominates {list}...` is no longer supported. It has been
+`aspect \{name} dominates \{list}...` is no longer supported. It has been
 replaced by a new declare statement:
 
 [source, java]
@@ -265,7 +265,7 @@ because the end of exception handlers is ambiguous in bytecode. Try to
 use before advice. (xref:README-1.1.adoc#AFTER_HANDLER[more info])
 
 [[pre-1_0_4]]
-=== Porting pre-1.0.4 code
+== Porting pre-1.0.4 code
 
 In versions of AspectJ prior to 1.0.4, the compiler was not correctly
 implementing the AspectJ-1.0 language design for some uses of after
@@ -321,7 +321,7 @@ Uses of both of these forms are highleted with compiler warnings in the
 '''''
 
 [[pre-1_0rc1]]
-=== Porting pre-1.0rc1 code
+== Porting pre-1.0rc1 code
 
 Aspects can no longer be declared to implement the `Serializable` or
 `Cloneable` interfaces. If you previously used serializable or cloneable
@@ -331,7 +331,7 @@ serialize or clone in objects associated with the aspects.
 '''''
 
 [[pre-1_0beta1]]
-=== Porting pre-1.0beta1 code
+== Porting pre-1.0beta1 code
 
 The `static` modifier is no longer allowed on pointcut declarations
 anywhere. Porting is simple; just remove the static declarations when
@@ -345,7 +345,7 @@ now. If you used this feature, now is the right time to remove the
 '''''
 
 [[pre-1_0alpha1]]
-=== Porting pre-1.0alpha1 code
+== Porting pre-1.0alpha1 code
 
 The release of AspectJ 1.0alpha1 involved sweeping cleanups of the
 language to bring it to 1.0 status.
@@ -358,10 +358,10 @@ crosscutting]
 * xref:#_1_0a1-aspects[Aspects]
 
 [[_1_0a1-pointcuts]]
-==== Pointcuts
+=== Pointcuts
 
 [[_1_0a1-plural-to-singular]]
-===== Removing the "s" from pointcuts
+==== Removing the "s" from pointcuts
 
 One of the most pervasive changes in porting code written before
 1.0alpha1 is the change in some of the pointcut names from plural to
@@ -401,7 +401,7 @@ Of course, your naming conventions are your own, but throughout these
 porting notes we will be making these changes in our example ports.
 
 [[_1_0a1-remove-receptions]]
-===== Removing the receptions pointcut
+==== Removing the receptions pointcut
 
 Perhaps the largest semantic change in the 1.0 language is the removal
 of receptions join points. They have been merged with call join points
@@ -411,7 +411,7 @@ in AspectJ 1.0, so now a call join point doesn't represent the
 Changing code that used the `receptions` pointcut should be fairly
 straightforward, depending on whether the pointcut exposed state or not.
 
-====== Not exposing state
+===== Not exposing state
 
 Receptions pointcuts that did not expose state can simply be replaced by
 the new `call` and `target` pointcuts:
@@ -423,7 +423,7 @@ receptions(void Foo.m())
 target(Foo) && call(void m())
 ....
 
-====== Exposing state
+===== Exposing state
 
 Some receptions pointcuts exposed the receiving object by replacing the
 receiving type with a pointcut formal. These PCDs should be rewritten to
@@ -448,7 +448,7 @@ pointcut intPasser(int i, int j):
     args(i, j) && target(Foo) && call(void m(int, int));
 ....
 
-====== Constructor receptions
+===== Constructor receptions
 
 There are two issues with constructor receptions in particular.
 
@@ -499,7 +499,7 @@ after() returning (Point p): call(Point+.new(int, int)) { ... }
 ....
 
 [[_1_0a1-fixing-state-access]]
-===== Fixing state access
+==== Fixing state access
 
 In previous versions of AspectJ, state such as the currently executing
 object or a particular argument of a method call could be accessed from
@@ -508,7 +508,7 @@ AspectJ 1.0, all state accesses now use only three pointcuts `args, this, target
 which pick out argument values, the currently executing object, and the
 target object of a method call or field operation, respectively.
 
-====== Using args
+===== Using args
 
 Any time you have a pointcut that has a signature where one of the
 arguments was a pointcut or advice formal, just replace that formal with
@@ -528,7 +528,7 @@ pointcut stringPassers(String s): receptions(void Foo.m(s, ..));
 pointcut stringPasser(String s): args(s, ..) && call(void Foo.m(String, ..));
 ....
 
-====== Rewriting calls
+===== Rewriting calls
 
 If a calls pointcut exposed the the receiving object, such as
 
@@ -559,7 +559,7 @@ after(Point p) returning (): calls(p.new(int, int)) { ... }
 after() returning (Point p): call(Point+.new(int, int)) { ... }
 ....
 
-====== Rewriting gets and sets
+===== Rewriting gets and sets
 
 Exposing the target object of a `gets` or `sets` pointcut should be done
 the same way it was for `calls` pointcuts, with the new `target`
@@ -640,7 +640,7 @@ after(Color newColor): args(newColor) && set(Color Frame.color) { ... }
 Also, if the field was declared private, in order to get at its old
 value the aspect must be declared `privileged`.
 
-====== Rewriting handlers
+===== Rewriting handlers
 
 The value of the exception at an exception handler join point is now
 accessed through the `args` pointcut; all exception handler join points
@@ -653,7 +653,7 @@ before(NotFoundException e): handlers(e) { ... }
 before(NotFoundException e): args(e) && handler(NotFoundException) { ... }
 ....
 
-====== Rewriting within
+===== Rewriting within
 
 The `within` pointcut was not typically used to export context. Though
 it was accidentally possible to do so in versions of AspectJ before 1.0,
@@ -670,7 +670,7 @@ pointcut usesFoo(Foo f): this(f) && within(Foo);
 ....
 
 [[_1_0a1-no-subs-in-sigs]]
-===== Understanding signatures
+==== Understanding signatures
 
 Now that we have `this`, `target`, and `args` pointcuts, all of our
 signatures are composed of just types, names, and wildcards; there are
@@ -707,7 +707,7 @@ call(void m(Object+))
 ....
 
 [[_1_0a1-fixing-instanceof]]
-===== Removing the instanceof pointcut
+==== Removing the instanceof pointcut
 
 The intanceof pointcut has been split into two different pointcuts,
 `this` and `target`.
@@ -746,7 +746,7 @@ pointcut setup(Client c): this(c) && calls(Remote Naming.lookup(String));
 ....
 
 [[_1_0a1-initializations]]
-===== Rewriting the initializations pointcut
+==== Rewriting the initializations pointcut
 
 Object initialization join points are now more complicated, and more
 true to Java's execution model. Now they bracket all of the
@@ -766,7 +766,7 @@ initialization(A.new(..)) && !execution(A.new(..))
 ....
 
 [[_1_0a1-constructor-calls]]
-===== Understanding constructor calls
+==== Understanding constructor calls
 
 Previously, constructor call join points were matched by subtypes, so
 `calls(Foo.new())` would match both calls to create new `Foo` objects,
@@ -782,7 +782,7 @@ In both of these cases, think before using the + operator; it may be
 that you didn't intend subtype matching in the first place.
 
 [[_1_0a1-hasaspect]]
-===== Removing the hasaspect pointcut
+==== Removing the hasaspect pointcut
 
 The `hasaspect` pointcut is no longer defined, but you can get the same
 behaviour using the new `if` pointcut.
@@ -828,7 +828,7 @@ before(): if(A.hasAspect()) {
 ....
 
 [[_1_0a1-withinall]]
-===== Removing the withinall pointcut
+==== Removing the withinall pointcut
 
 The withinall poinctut is no longer defined. You can use a combination
 of within and the xref:#_1_0a1-subtypes-to-plus[new subtypes operator],
@@ -843,7 +843,7 @@ within(Foo+)
 ....
 
 [[_1_0a1-user-defined-returns]]
-===== Removing returns modifier from pointcuts
+==== Removing returns modifier from pointcuts
 
 The returns keyword is no longer necessary for user-defined pointcuts.
 Simply remove it when you find it.
@@ -856,7 +856,7 @@ pointcut publicIntCall(): call(public int *(..));
 ....
 
 [[_1_0a1-static-pointcuts]]
-===== Making some pointcuts static
+==== Making some pointcuts static
 
 In Java, only static members may be accessed by their declaring type
 name, like the static method `Math.max()` can be accessed.
@@ -874,10 +874,10 @@ classes `static`, and make any pointcut with a qualified reference
 static.
 
 [[_1_0a1-type-patterns]]
-==== Type patterns
+=== Type patterns
 
 [[_1_0a1-new-wildcards]]
-===== Understanding * and .. in type patterns
+==== Understanding * and .. in type patterns
 
 Previous versions of AspectJ treated * and .. too cleverly in type
 patterns, placing restrictions based on what is a package and what is a
@@ -908,7 +908,7 @@ pointcut unaryVoidMethod(): call(void *(*));
 ....
 
 [[_1_0a1-subtypes-to-plus]]
-===== Fixing subtypes in introduction
+==== Fixing subtypes in introduction
 
 The new + operator is used to normalize the many places you want to use
 subtypes of some types.
@@ -931,10 +931,10 @@ public void (Target0+ || Target1+).accept(Visitor v) {
 ....
 
 [[_1_0a1-advice]]
-==== Advice
+=== Advice
 
 [[_1_0a1-around-returns]]
-===== Moving the return type of around
+==== Moving the return type of around
 
 The returns keyword is no longer used for around advice. Instead, the
 return type is declared as it is for methods. So,
@@ -947,7 +947,7 @@ void around(Point p): setter(p) { ... }
 ....
 
 [[_1_0a1-around-throws]]
-===== Adding a throws clause to around
+==== Adding a throws clause to around
 
 Around advice must now declare the checked exceptions it throws with a
 `throws` clause, much like a method.
@@ -966,7 +966,7 @@ char around(char c) throws java.io.CharConversionException: converter(c) {
 ....
 
 [[_1_0a1-advice-precedence]]
-===== Understanding advice precedence
+==== Understanding advice precedence
 
 In previous versions of AspectJ, advice precedence within an aspect was
 simple: if a piece of advice appeared before another piece, it was more
@@ -1022,7 +1022,7 @@ Advice in _different_ aspects is ordered by the normal aspect precedence
 rules of subtyping and the `dominates` modifier.
 
 [[_1_0a1-after-returning]]
-===== Fixing after returning
+==== Fixing after returning
 
 If you use after returning advice and do not need to expose the return
 value, you no longer need to write an empty set of parentheses to
@@ -1044,14 +1044,14 @@ after(Formals) throwing: Pointcut { ... }
 ....
 
 [[_1_0a1-this-static-join-point]]
-===== Renaming thisStaticJoinPoint
+==== Renaming thisStaticJoinPoint
 
 `thisStaticJoinPoint` has been renamed `thisJoinPointStaticPart`, to
 reflect that it is now exactly the static part of `thisJoinPoint`: It
 will return the same object as `thisJoinPoint.getStaticPart()`.
 
 [[_1_0a1-this-join-point]]
-===== Converting access to thisJoinPoint
+==== Converting access to thisJoinPoint
 
 The `JoinPoint` object hierarchy has been folded into a single class,
 `org.aspectj.lang.JoinPoint`. A common pattern in logging, for example,
@@ -1083,10 +1083,10 @@ before() executions(* myMethod()) {
 Some of the method names of `JoinPoint` have been reorganized, as well.
 
 [[_1_0a1-introduction-and-static]]
-==== Introduction and static crosscutting
+=== Introduction and static crosscutting
 
 [[_1_0a1-plus-implements-extends]]
-===== Removing +implements and +extends
+==== Removing +implements and +extends
 
 The keywords `+implements` and `+extends` no longer exist. Instead,
 AspectJ uses the `declare` form for exactly the same functionality.
@@ -1106,7 +1106,7 @@ declare parents: MyButton extends ButtonAdaptor;
 ....
 
 [[_1_0a1-now-use-soft]]
-===== Using declare soft
+==== Using declare soft
 
 Around advice advice no longer effects the static exception checking of
 Java. This means that the following code previously compiled:
@@ -1156,7 +1156,7 @@ declare soft: IOException:
 ....
 
 [[_1_0a1-aspects]]
-==== Aspects
+=== Aspects
 
 The syntax of "of each" modifiers has changed. For `of eachcflow` and
 `of eachcflowbelow`, you can simply replace "of each" with "per". So,
@@ -1222,7 +1222,7 @@ object at such join points.
 '''''
 
 [[pre08b3]]
-=== Porting pre-0.8beta3 code
+== Porting pre-0.8beta3 code
 
 * xref:#cflowTerminology[Changing cflow terminology]
 * xref:#abstractPointcuts[Overriding abstract pointcuts]
@@ -1232,18 +1232,18 @@ The following changes are only required when porting code written prior
 to the 0.8beta3 release of AspectJ.
 
 [[cflowTerminology]]
-==== Changing cflow terminology
+=== Changing cflow terminology
 
 Changing pre-0.8beta3 code that uses AspectJ's control-flow-based
 features only requires rewriting occurrences of `eachcflowroot`,
 `cflow`, and `cflowtop`. No editing of other aspect code is necessary.
 
-===== eachcflowroot
+==== eachcflowroot
 
 The aspect modifier "`of eachcflowroot(Pointcut)`" should now be written
 more as "`percflow(Pointcut)`".
 
-===== cflow
+==== cflow
 
 In previous versions of AspectJ, the pointcut `cflow(Pointcut)` picked
 out all join points in the cflow below the join points of `Pointcut`.
@@ -1270,7 +1270,7 @@ definitely want to rewrite that as
 Pointcut && ! cflowbelow(Pointcut)
 ----
 
-===== cflowtop
+==== cflowtop
 
 The primitive pointcut designator `cflowtop(Pointcut)` has been removed
 from the language, as it is expressible with `cflow` or `cflowbelow`.
@@ -1289,7 +1289,7 @@ cflow(Pointcut && ! cflowbelow(Pointcut))
 ----
 
 [[abstractPointcuts]]
-==== Overriding abstract pointcuts
+=== Overriding abstract pointcuts
 
 In previous versions of AspectJ, a concrete aspect would implicitly
 override all of its abstract pointcuts with an empty pointcut. AspectJ
@@ -1328,7 +1328,7 @@ aspect B {
 ----
 
 [[recursiveAdvice]]
-==== Limiting recursive advice
+=== Limiting recursive advice
 
 Previously, the compiler silently refrained from applying a piece of
 advice to join points within its own advice body. So, for example, in
@@ -1401,7 +1401,7 @@ aspect A {
 '''''
 
 [[pre08b1]]
-=== Porting pre-0.8beta1 code
+== Porting pre-0.8beta1 code
 
 * xref:#introSyntax[Rewriting introductions]
 * xref:#staticAdvice[Removing static advice]
@@ -1412,9 +1412,9 @@ The following changes are only required when porting code written prior
 to the 0.8beta1 release of AspectJ.
 
 [[introSyntax]]
-==== Rewriting introductions
+=== Rewriting introductions
 
-===== Syntax
+==== Syntax
 
 The syntax of introduction has changed. Porting most programs should
 require some simple editing. Anywhere you have an introduction block
@@ -1481,7 +1481,7 @@ introduction subtypes(Foo) && !Goo {
 int (Foo+ && !Goo).x;
 ----
 
-===== Access
+==== Access
 
 If you had an introduction that was referring to private or protected
 members of the target class, this will no longer work. You will either
@@ -1547,7 +1547,7 @@ inherited from a superclass, you will have to make this introduction
 public.
 
 [[staticAdvice]]
-==== Removing static advice
+=== Removing static advice
 
 Static advice has been removed from the language. Now, every piece of
 advice is non-static, meaning that it will run in the context of an
@@ -1610,7 +1610,7 @@ aspect ComplexTracing of eachobject(cflow(executions(void Main.main(..)))) {
 ----
 
 [[aspect-aspect]]
-==== Fixing aspect-aspect inheritance
+=== Fixing aspect-aspect inheritance
 
 Aspects can now only extend abstract aspects. This restriction may cause
 some redesign of aspect hierarchies. You will probably find that for the
@@ -1670,7 +1670,7 @@ A better way to implement this kind of design aspect is to use private
 introduction, a new feature of AspectJ.
 
 [[usingPrivateIntroduction]]
-==== Using private introduction
+=== Using private introduction
 
 A common pattern for AspectJ programs that need to associate some state
 with every object of a particular type has been to use aspects that are
@@ -1722,7 +1722,7 @@ association may capture the crosscutting concern best.
 '''''
 
 [[pre07b11]]
-=== Porting pre-0.7beta11 code
+== Porting pre-0.7beta11 code
 
 * xref:#twoArgumentCalls[Removing two-argument calls]
 * xref:#adviceInClasses[Removing advice from Class declarations]
@@ -1731,13 +1731,13 @@ The following changes are only required when porting code written prior
 to the 0.7beta11 release of AspectJ.
 
 [[twoArgumentCalls]]
-==== Removing two-argument calls
+=== Removing two-argument calls
 
 In AspectJ 0.7beta11, the two-argument `calls` primitive pointcut
 designator was deprecated. Removing these designators will require
 different cases depending on what the original pointcut did.
 
-===== Calls to static methods
+==== Calls to static methods
 
 For pointcuts denoting calls to particular static methods, such as
 
@@ -1771,7 +1771,7 @@ should now be written
 call(static * my.package.*.get*(..))
 ....
 
-===== Calls to non-static methods
+==== Calls to non-static methods
 
 Many pointcuts denoting calls to non-static methods can be fixed the
 same way that those pointcuts denoting calls to static methods are
@@ -1815,7 +1815,7 @@ It will also denote any join points if the Thread type does not define
 (possibly abstractly) some `int getPriority()` method, though.
 
 [[adviceInClasses]]
-==== Removing advice from Class declarations
+=== Removing advice from Class declarations
 
 The simplest way to remove an advice declaration from a class is to
 simply define the advice declaration in an inner aspect. So, instead of
@@ -1860,7 +1860,7 @@ appropriate.
 '''''
 
 [[pre07b10]]
-=== Porting pre-0.7beta10 code
+== Porting pre-0.7beta10 code
 
 * xref:#joinPoints[Changing access to thisJoinPoint]
 
@@ -1868,7 +1868,7 @@ The following changes are only required when porting code written prior
 to the 0.7beta10 release of AspectJ.
 
 [[joinPoints]]
-==== Changing access to thisJoinPoint
+=== Changing access to thisJoinPoint
 
 In AspectJ 0.7beta10, access to the reflective object `thisJoinPoint`
 substantially changed. The two parts of this change were the elimination
@@ -1876,7 +1876,7 @@ of the `runNext()` static method, and the use of an interface hierarchy
 represent the join point object.
 
 [[proceed]]
-===== `thisJoinPoint.runNext()` to `proceed()`
+==== `thisJoinPoint.runNext()` to `proceed()`
 
 The elimination of the `runNext()` static method requires almost no
 porting work. An automatic replacement of the string
@@ -1901,7 +1901,7 @@ aspect name or `this`, depending on whether the field is static or
 not).
 
 [[thisJoinPoint]]
-===== Using `thisJoinPoint`
+==== Using `thisJoinPoint`
 
 While access to reflective information through `thisJoinPoint` is more
 powerful and regular through its interface hierarchy, the previous uses
diff --git a/docs/sandbox/ubc-design-patterns/patterns-readme.adoc b/docs/sandbox/ubc-design-patterns/patterns-readme.adoc
index ade559c2d..7820d8b01 100644
--- a/docs/sandbox/ubc-design-patterns/patterns-readme.adoc
+++ b/docs/sandbox/ubc-design-patterns/patterns-readme.adoc
@@ -1,4 +1,4 @@
-== AspectJ Patterns
+= AspectJ Patterns
 
 _Last updated: 2004-03-31 by wisberg_
 
diff --git a/docs/teaching/exercises/plugins/index.adoc b/docs/teaching/exercises/plugins/index.adoc
index 1cdf0fbc1..9a70bf6a9 100644
--- a/docs/teaching/exercises/plugins/index.adoc
+++ b/docs/teaching/exercises/plugins/index.adoc
@@ -1,4 +1,4 @@
-== Exercises plugin for the tutorial
+= Exercises plugin for the tutorial
 
 Download the appropriate version and unzip it in your eclipse\plugins
 directory: