Fix several structural asciidoc warnings

In changes.adoc, also make headlines and TOC more readable.

To avoid some "image not found" warnings, move images directory in ROOT
module to the canonical level. This also required a small change in
IDE.md.

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

33 files changed, 220 insertions, 206 deletions

diff --git a/docs/modules/ROOT/pages/developer/images/EclipseSoftwareSitesAJDT.png b/docs/modules/ROOT/images/EclipseSoftwareSitesAJDT.png
index 9ab1e13b3..9ab1e13b3 100644
--- a/docs/modules/ROOT/pages/developer/images/EclipseSoftwareSitesAJDT.png
+++ b/docs/modules/ROOT/images/EclipseSoftwareSitesAJDT.png
diff --git a/docs/modules/ROOT/pages/developer/images/advice-dec.png b/docs/modules/ROOT/images/advice-dec.png
index 4261f8b10..4261f8b10 100644
--- a/docs/modules/ROOT/pages/developer/images/advice-dec.png
+++ b/docs/modules/ROOT/images/advice-dec.png
diff --git a/docs/modules/ROOT/pages/developer/images/ajdt-uml.png b/docs/modules/ROOT/images/ajdt-uml.png
index a8ac5b410..a8ac5b410 100644
--- a/docs/modules/ROOT/pages/developer/images/ajdt-uml.png
+++ b/docs/modules/ROOT/images/ajdt-uml.png
diff --git a/docs/modules/ROOT/pages/developer/images/ajdt-uml.vsd b/docs/modules/ROOT/images/ajdt-uml.vsd
index d3fa03dea..d3fa03dea 100644
--- a/docs/modules/ROOT/pages/developer/images/ajdt-uml.vsd
+++ b/docs/modules/ROOT/images/ajdt-uml.vsd
diff --git a/docs/modules/ROOT/pages/developer/images/overview.png b/docs/modules/ROOT/images/overview.png
index f03e01c9f..f03e01c9f 100644
--- a/docs/modules/ROOT/pages/developer/images/overview.png
+++ b/docs/modules/ROOT/images/overview.png
diff --git a/docs/modules/ROOT/pages/developer/images/overview.vsd b/docs/modules/ROOT/images/overview.vsd
index 5636872df..5636872df 100644
--- a/docs/modules/ROOT/pages/developer/images/overview.vsd
+++ b/docs/modules/ROOT/images/overview.vsd
diff --git a/docs/modules/ROOT/pages/developer/images/pointcut-dec.png b/docs/modules/ROOT/images/pointcut-dec.png
index a59676d66..a59676d66 100644
--- a/docs/modules/ROOT/pages/developer/images/pointcut-dec.png
+++ b/docs/modules/ROOT/images/pointcut-dec.png
diff --git a/docs/modules/ROOT/pages/developer/images/top-tree.png b/docs/modules/ROOT/images/top-tree.png
index 51632c435..51632c435 100644
--- a/docs/modules/ROOT/pages/developer/images/top-tree.png
+++ b/docs/modules/ROOT/images/top-tree.png
diff --git a/docs/modules/ROOT/pages/LICENSE-AspectJ.adoc b/docs/modules/ROOT/pages/LICENSE-AspectJ.adoc
index 8f3a4ac30..387a985e5 100644
--- a/docs/modules/ROOT/pages/LICENSE-AspectJ.adoc
+++ b/docs/modules/ROOT/pages/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,7 +17,7 @@ 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
 
@@ -27,8 +27,6 @@ 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
 
 This product contains software developed by the Apache Software
diff --git a/docs/modules/ROOT/pages/developer/IDE.md b/docs/modules/ROOT/pages/developer/IDE.md
index d34f1c404..1772f509f 100644
--- a/docs/modules/ROOT/pages/developer/IDE.md
+++ b/docs/modules/ROOT/pages/developer/IDE.md
@@ -58,7 +58,7 @@ update sites:
 
 Your AspectJ-related list of Eclipse update sites could look like this for Eclipse 2023-12:
 
-![Eclipse IDE filtered list of update sites](images/EclipseSoftwareSitesAJDT.png)
+![Eclipse IDE filtered list of update sites](../../images/EclipseSoftwareSitesAJDT.png)
 
 ### IntelliJ IDEA
 
@@ -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/modules/ROOT/pages/developer/compiler-weaver.adoc b/docs/modules/ROOT/pages/developer/compiler-weaver.adoc
index be3eb0a94..718215508 100644
--- a/docs/modules/ROOT/pages/developer/compiler-weaver.adoc
+++ b/docs/modules/ROOT/pages/developer/compiler-weaver.adoc
@@ -1,4 +1,8 @@
 = 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_
 
diff --git a/docs/modules/ROOT/pages/index.adoc b/docs/modules/ROOT/pages/index.adoc
index 32a8d2001..37ea5464c 100644
--- a/docs/modules/ROOT/pages/index.adoc
+++ b/docs/modules/ROOT/pages/index.adoc
@@ -10,10 +10,10 @@ materials, see https://eclipse.org/aspectj. Not all of these materials have been
 |+++Section+++ |+++Contents+++
 
 |xref:#documentation[Documentation]
-|xref:faq/faq.adoc#faq[FAQ], xref:quickref/quick5.pdf[Quick Reference (AspectJ 5)],
-xref:quickref/quick.pdf[Quick Reference (1.2.1)], xref:adk15notebook/index.adoc[AspectJ 5 Developer's Notebook],
-xref:progguide/index.adoc[programming], xref:devguide/index.adoc[development] and
-xref:pdguide/index.adoc[problem diagnosis] guides, link:runtime-api/index.html[runtime API],
+|xref:faq:faq.adoc#faq[FAQ], xref:quickref/quick5.pdf[Quick Reference (AspectJ 5)],
+xref:quickref/quick.pdf[Quick Reference (1.2.1)], xref:adk15notebook:index.adoc[AspectJ 5 Developer's Notebook],
+xref:progguide:index.adoc[programming], xref:devguide:index.adoc[development] and
+xref:pdguide:index.adoc[problem diagnosis] guides, link:runtime-api/index.html[runtime API],
 link:weaver-api/index.html[weaver API] and link:examples[example code]
 
 |xref:#distributions[Distributions]
@@ -42,39 +42,39 @@ mailto:aspectj-users@eclipse.org[users] and mailto:aspectj-dev@eclipse.org[devel
 
 a|AspectJ 5 Developer's Notebook
 
-* xref:adk15notebook/index.adoc[HTML multi-page]
-* xref:adk15notebook/adk15notebook.adoc[HTML single page]
+* xref:adk15notebook:index.adoc[HTML multi-page]
+* xref:adk15notebook:adk15notebook.adoc[HTML single page]
 * xref:adk15notebook/adk15notebook.pdf[PDF]
 |Describes the changes to the AspectJ language and tools introduced in the AspectJ 5 Development Kit. These changes are
 additive, and are not yet reflected in the programming guide or quick reference.
 
 a|Programming Guide
 
-* xref:progguide/index.adoc[HTML multi-page]
-* xref:progguide/progguide.adoc[HTML single page]
+* xref:progguide:index.adoc[HTML multi-page]
+* xref:progguide:progguide.adoc[HTML single page]
 * xref:progguide/progguide.pdf[PDF]
-|Introduces AOP and the AspectJ language. xref:progguide/gettingstarted.adoc[Getting Started] describes basic semantics
-and shows development- and production-time applications. xref:progguide/language.adoc[The AspectJ Language] describes
-join points, pointcuts, advice, and introduction, all features new to AOP. xref:progguide/examples.adoc[Examples] walks
+|Introduces AOP and the AspectJ language. xref:progguide:gettingstarted.adoc[Getting Started] describes basic semantics
+and shows development- and production-time applications. xref:progguide:language.adoc[The AspectJ Language] describes
+join points, pointcuts, advice, and introduction, all features new to AOP. xref:progguide:examples.adoc[Examples] walks
 you through the examples included with the documentation, and there are two short chapters on useful
-xref:progguide/idioms.adoc[Idioms] and a few xref:progguide/pitfalls.html[Pitfalls]. +
-The appendices have reference information: the xref:progguide/quickreference.adoc[Quick Reference] summarizes AspectJ
-syntax, the xref:progguide/semantics.adoc[Language Semantics] best describes AspectJ usage, and
-xref:progguide/implementation.adoc[Implementation Notes] describes how the current version is limited to code the
+xref:progguide:idioms.adoc[Idioms] and a few xref:progguide:pitfalls.adoc[Pitfalls]. +
+The appendices have reference information: the xref:progguide:quickreference.adoc[Quick Reference] summarizes AspectJ
+syntax, the xref:progguide:semantics.adoc[Language Semantics] best describes AspectJ usage, and
+xref:progguide:implementation.adoc[Implementation Notes] describes how the current version is limited to code the
 compiler controls.
 
 a|Development Environment Guide
 
-* xref:devguide/index.adoc[HTML multi-page]
-* xref:devguide/devguide.adoc[HTML single page]
+* xref:devguide:index.adoc[HTML multi-page]
+* xref:devguide:devguide.adoc[HTML single page]
 * xref:devguide/devguide.pdf[PDF]
-|Guide to the command-line compiler xref:devguide/ajc.adoc[ajc] and the xref:devguide/antsupport.adoc[Ant tasks] for
+|Guide to the command-line compiler xref:devguide:ajc.adoc[ajc] and the xref:devguide:antsupport.adoc[Ant tasks] for
 building AspectJ programs
 
 a|Problem Diagnosis Guide
 
-* xref:pdguide/index.adoc[HTML multi-page]
-* xref:pdguide/pdguide.adoc[HTML single page]
+* xref:pdguide:index.adoc[HTML multi-page]
+* xref:pdguide:pdguide.adoc[HTML single page]
 * xref:pdguide/pdguide.pdf[PDF]
 |Guide to various debugging features available, such as messages and trace to help you both solve problems with you own
 programs and report bugs to the AspectJ team
@@ -88,46 +88,46 @@ programs and report bugs to the AspectJ team
 used for byte code weaving, both during compilation from source code and binary weaving during post-compile and
 load-time weaving.
 
-|xref:faq/faq.adoc#faq[FAQ]
+|xref:faq:faq.adoc#faq[FAQ]
 |Frequently asked questions about the AspectJ language, tools, and project
 
-|xref:release/JavaVersionCompatibility.adoc[Java version compatibility]
+|xref:release:JavaVersionCompatibility.adoc[Java version compatibility]
 |Compatibility matrix, explaining which AspectJ compiler version supports which Java language version and needs which
 JDK to run
 
 |Release notes |Release notes, describing new features, improvements, bugfixes per AspectJ version: +
  +
-xref:release/README-1.9.21.adoc[1.9.21],
-xref:release/README-1.9.20.adoc[1.9.20 and 1.9.20.1], xref:release/README-1.9.19.adoc[1.9.19],
-xref:release/README-1.9.9.adoc[1.9.9 and 1.9.9.1], xref:release/README-1.9.8.adoc[1.9.8],
-xref:release/README-1.9.7.adoc[1.9.7], xref:release/README-1.9.6.adoc[1.9.6],
-xref:release/README-1.9.5.adoc[1.9.5], xref:release/README-1.9.4.adoc[1.9.4],
-xref:release/README-1.9.3.adoc[1.9.3], xref:release/README-1.9.2.adoc[1.9.2],
-xref:release/README-1.9.1.adoc[1.9.1], xref:release/README-1.9.0.adoc[1.9.0],
-xref:release/README-1.8.11.adoc[1.8.11], xref:release/README-1.8.10.adoc[1.8.10],
-xref:release/README-1.8.9.adoc[1.8.9], xref:release/README-1.8.8.adoc[1.8.8],
-xref:release/README-1.8.7.adoc[1.8.7], xref:release/README-1.8.6.adoc[1.8.6],
-xref:release/README-1.8.5.adoc[1.8.5], xref:release/README-1.8.4.adoc[1.8.4],
-xref:release/README-1.8.3.adoc[1.8.3], xref:release/README-1.8.2.adoc[1.8.2],
-xref:release/README-1.8.1.adoc[1.8.1], xref:release/README-1.8.0.adoc[1.8.0],
-xref:release/README-1.7.4.adoc[1.7.4], xref:release/README-1.7.3.adoc[1.7.3],
-xref:release/README-1.7.2.adoc[1.7.2], xref:release/README-1.7.1.adoc[1.7.1],
-xref:release/README-1.7.0.adoc[1.7.0], xref:release/README-1.6.12.adoc[1.6.12],
-xref:release/README-1.6.11.adoc[1.6.11], xref:release/README-1.6.10.adoc[1.6.10],
-xref:release/README-1.6.9.adoc[1.6.9], xref:release/README-1.6.8.adoc[1.6.8],
-xref:release/README-1.6.7.adoc[1.6.7], xref:release/README-1.6.6.adoc[1.6.6],
-xref:release/README-1.6.5.adoc[1.6.5], xref:release/README-1.6.4.adoc[1.6.4],
-xref:release/README-1.6.3.adoc[1.6.3], xref:release/README-1.6.2.adoc[1.6.2],
-xref:release/README-1.6.1.adoc[1.6.1], xref:release/README-1.6.0.adoc[1.6.0],
-xref:release/README-1.5.4.adoc[1.5.4], xref:release/README-1.5.3.adoc[1.5.3],
-xref:release/README-1.5.2.adoc[1.5.2], xref:release/README-1.5.1.adoc[1.5.1],
-xref:release/README-1.5.0.adoc[1.5.0], xref:release/README-1.2.1.adoc[1.2.1],
-xref:release/README-1.2.adoc[1.2], xref:release/README-1.1.adoc[1.1].
-
-|xref:release/changes.adoc[Changes] (historical)
+xref:release:README-1.9.21.adoc[1.9.21],
+xref:release:README-1.9.20.adoc[1.9.20 and 1.9.20.1], xref:release:README-1.9.19.adoc[1.9.19],
+xref:release:README-1.9.9.adoc[1.9.9 and 1.9.9.1], xref:release:README-1.9.8.adoc[1.9.8],
+xref:release:README-1.9.7.adoc[1.9.7], xref:release:README-1.9.6.adoc[1.9.6],
+xref:release:README-1.9.5.adoc[1.9.5], xref:release:README-1.9.4.adoc[1.9.4],
+xref:release:README-1.9.3.adoc[1.9.3], xref:release:README-1.9.2.adoc[1.9.2],
+xref:release:README-1.9.1.adoc[1.9.1], xref:release:README-1.9.0.adoc[1.9.0],
+xref:release:README-1.8.11.adoc[1.8.11], xref:release:README-1.8.10.adoc[1.8.10],
+xref:release:README-1.8.9.adoc[1.8.9], xref:release:README-1.8.8.adoc[1.8.8],
+xref:release:README-1.8.7.adoc[1.8.7], xref:release:README-1.8.6.adoc[1.8.6],
+xref:release:README-1.8.5.adoc[1.8.5], xref:release:README-1.8.4.adoc[1.8.4],
+xref:release:README-1.8.3.adoc[1.8.3], xref:release:README-1.8.2.adoc[1.8.2],
+xref:release:README-1.8.1.adoc[1.8.1], xref:release:README-1.8.0.adoc[1.8.0],
+xref:release:README-1.7.4.adoc[1.7.4], xref:release:README-1.7.3.adoc[1.7.3],
+xref:release:README-1.7.2.adoc[1.7.2], xref:release:README-1.7.1.adoc[1.7.1],
+xref:release:README-1.7.0.adoc[1.7.0], xref:release:README-1.6.12.adoc[1.6.12],
+xref:release:README-1.6.11.adoc[1.6.11], xref:release:README-1.6.10.adoc[1.6.10],
+xref:release:README-1.6.9.adoc[1.6.9], xref:release:README-1.6.8.adoc[1.6.8],
+xref:release:README-1.6.7.adoc[1.6.7], xref:release:README-1.6.6.adoc[1.6.6],
+xref:release:README-1.6.5.adoc[1.6.5], xref:release:README-1.6.4.adoc[1.6.4],
+xref:release:README-1.6.3.adoc[1.6.3], xref:release:README-1.6.2.adoc[1.6.2],
+xref:release:README-1.6.1.adoc[1.6.1], xref:release:README-1.6.0.adoc[1.6.0],
+xref:release:README-1.5.4.adoc[1.5.4], xref:release:README-1.5.3.adoc[1.5.3],
+xref:release:README-1.5.2.adoc[1.5.2], xref:release:README-1.5.1.adoc[1.5.1],
+xref:release:README-1.5.0.adoc[1.5.0], xref:release:README-1.2.1.adoc[1.2.1],
+xref:release:README-1.2.adoc[1.2], xref:release:README-1.1.adoc[1.1].
+
+|xref:release:changes.adoc[Changes] (historical)
 |Changes between historical releases up to 1.6.0
 
-|xref:release/porting.adoc[Porting guide] (historical)
+|xref:release:porting.adoc[Porting guide] (historical)
 |Porting guide for historical releases to 1.2
 
 |link:examples[Examples]
@@ -158,7 +158,7 @@ documentation and examples.
 |https://eclipse.org/aspectj[AspectJ source code]
 |Source code for AspectJ is available under the open-source
 https://www.eclipse.org/org/documents/epl-2.0/EPL-2.0.txt[Eclipse Public License v 2.0] license from the Git
-repositories for the AspectJ project. See the xref:faq/faq.adoc#buildingsource[FAQ entry].
+repositories for the AspectJ project. See the xref:faq:faq.adoc#buildingsource[FAQ entry].
 
 |https://eclipse.org/ajdt[AspectJ for Eclipse]
 |AspectJ Development Environment support for Eclipse is available under Eclipse Public License v 1.0 from the
@@ -189,28 +189,28 @@ https://bugs.eclipse.org/bugs/buglist.cgi?product=AspectJ&component=Ant[Ant] (fo
 https://bugs.eclipse.org/bugs/buglist.cgi?product=AspectJ&component=Docs[Docs] (for the documentation).
 Bugs all users should know about are
 https://bugs.eclipse.org/bugs/buglist.cgi?product=AspectJ&keywords=info[flagged with the "info" keyword].
-See the xref:faq/faq.adoc#ajcbugs[FAQ entry] for instructions on submitting compiler bugs.
+See the xref:faq:faq.adoc#ajcbugs[FAQ entry] for instructions on submitting compiler bugs.
 |===
 
 [[paths]]
 == 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
+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
 join point model and pointcuts, concepts AOP adds to OOP. To read about how the link:examples[examples] work, see the
-xref:progguide/examples.adoc[Examples] section in the xref:progguide/index.adoc[Programming Guide]. View and navigate
+xref:progguide:examples.adoc[Examples] section in the xref:progguide:index.adoc[Programming Guide]. View and navigate
 the crosscutting structure using https://eclipse.org/ajdt[AJDT].
 
 To start using AspectJ with your own code, modify the example aspects to apply to your classes. As you learn, use the
 compiler's `-Xlint` flags to catch some common mistakes. (Understand that the
-xref:progguide/implementation.adoc[current implementation] is limited to code the compiler controls.)
-
-To plan how to adopt AspectJ into a project, read the xref:progguide/index.adoc[Programming Guide] on development- and
-production-time aspects and the FAQ entries for xref:faq/faq.adoc#howToStartUsing[How should I start using AspectJ?],
-xref:faq/faq.adoc#adoption[Deciding to adopt AspectJ], the Development tools sections
-(xref:faq/faq.adoc#integrateWithDevTools[How does AspectJ integrate with existing Java development tools?],
-xref:faq/faq.adoc#devtools[Integrating AspectJ into your development environment],
-xref:faq/faq.adoc#ltw[Load-time weaving]), and xref:faq/faq.adoc#opensource[AspectJ as open-source]).
+xref:progguide:implementation.adoc[current implementation] is limited to code the compiler controls.)
+
+To plan how to adopt AspectJ into a project, read the xref:progguide:index.adoc[Programming Guide] on development- and
+production-time aspects and the FAQ entries for xref:faq:faq.adoc#howToStartUsing[How should I start using AspectJ?],
+xref:faq:faq.adoc#adoption[Deciding to adopt AspectJ], the Development tools sections
+(xref:faq:faq.adoc#integrateWithDevTools[How does AspectJ integrate with existing Java development tools?],
+xref:faq:faq.adoc#devtools[Integrating AspectJ into your development environment],
+xref:faq:faq.adoc#ltw[Load-time weaving]), and xref:faq:faq.adoc#opensource[AspectJ as open-source]).
 
 Enjoy the language!
 
diff --git a/docs/modules/ROOT/pages/sandbox/trails/j2ee.adoc b/docs/modules/ROOT/pages/sandbox/trails/j2ee.adoc
index efca55e77..c862b53d0 100644
--- a/docs/modules/ROOT/pages/sandbox/trails/j2ee.adoc
+++ b/docs/modules/ROOT/pages/sandbox/trails/j2ee.adoc
@@ -21,19 +21,19 @@ In Tomcat, you can deploy application servlets in WAR's or in exploded
 web directories and share code across applications.
 
 . Use `ajc` to compile the servlets, and deploy the classes as usual
-  into `{WebRoot}/WEB-INF/classes`.
+  into `\{WebRoot}/WEB-INF/classes`.
 . If your web applications or aspects do not interact, deploy
-  `aspectjrt.jar` into `{WebRoot}/WEB-INF/lib`.
+  `aspectjrt.jar` into `\{WebRoot}/WEB-INF/lib`.
 . If your web applications or aspects might interact, deploy them to
-`${CATALINA_BASE}/shared/lib`.
+`$\{CATALINA_BASE}/shared/lib`.
 
 Tomcat 4.x uses the Jasper engine based on Ant to compile JSP's. To set
 up ajc as the compiler, do the following before starting Tomcat:
 
-. Put `aspectjtools.jar` in `${CATALINA_HOME}/common/lib` so that it can
+. Put `aspectjtools.jar` in `$\{CATALINA_HOME}/common/lib` so that it can
   be loaded by Jasper.
 
-. Update Jasper servlet parameters in `${CATALINA_HOME}/conf/web.xml` to
+. Update Jasper servlet parameters in `$\{CATALINA_HOME}/conf/web.xml` to
   tell Ant to use `ajc` by setting the compiler property to the AspectJ
   compiler adapter:
 +
@@ -50,7 +50,7 @@ up ajc as the compiler, do the following before starting Tomcat:
 ....
 
 . The classpath is dynamically generated from the webapp deployment, so
-  `aspectjrt.jar` should be in `{webapp}/WEB-INF/lib` or some shared or
+  `aspectjrt.jar` should be in `\{webapp}/WEB-INF/lib` or some shared or
   common directory supported by the server.
 
 . Alternatively, you can precompile JSP's using
diff --git a/docs/modules/ROOT/pages/sandbox/trails/links.adoc b/docs/modules/ROOT/pages/sandbox/trails/links.adoc
index 7ec1e7459..7dadc56e6 100644
--- a/docs/modules/ROOT/pages/sandbox/trails/links.adoc
+++ b/docs/modules/ROOT/pages/sandbox/trails/links.adoc
@@ -26,7 +26,7 @@ AspectJ web site as ubc-design-patterns.zip. The latest version is
 checked into the CVS repository along with other sample code at
 `org.aspectj/modules/docs/sandbox/ubc-design-patterns`. For instructions
 on downloading code from the CVS repository, see the FAQ entry
-xref:../../faq/faq.adoc#buildingsource[How do I get and compile the source code for AspectJ?].
+xref:faq:faq.adoc#buildingsource[How do I get and compile the source code for AspectJ?].
 
 The https://atrack.dev.java.net/[*aTrack project*] aims to create an open
 source bug tracking application that demonstrates use of Aspect-Oriented
diff --git a/docs/modules/adk15notebook/pages/joinpointsignatures.adoc b/docs/modules/adk15notebook/pages/joinpointsignatures.adoc
index 9daf279e2..eca1b86b5 100644
--- a/docs/modules/adk15notebook/pages/joinpointsignatures.adoc
+++ b/docs/modules/adk15notebook/pages/joinpointsignatures.adoc
@@ -280,8 +280,8 @@ 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
diff --git a/docs/modules/adk15notebook/pages/ltw.adoc b/docs/modules/adk15notebook/pages/ltw.adoc
index ddf5af356..46b7d99b8 100644
--- a/docs/modules/adk15notebook/pages/ltw.adoc
+++ b/docs/modules/adk15notebook/pages/ltw.adoc
@@ -4,5 +4,5 @@
 [[ltw-introduction]]
 == Introduction
 
-See xref:../devguide/ltw.adoc#ltw[Developer's Guide] for information on
+See xref:devguide:ltw.adoc#ltw[Developer's Guide] for information on
 load-time weaving support in AspectJ 5.
diff --git a/docs/modules/devguide/pages/ajc.adoc b/docs/modules/devguide/pages/ajc.adoc
index 078ef5ff4..09cf44a3c 100644
--- a/docs/modules/devguide/pages/ajc.adoc
+++ b/docs/modules/devguide/pages/ajc.adoc
@@ -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
@@ -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
diff --git a/docs/modules/devguide/pages/antsupport.adoc b/docs/modules/devguide/pages/antsupport.adoc
index ba74d32dd..9a13b56ab 100644
--- a/docs/modules/devguide/pages/antsupport.adoc
+++ b/docs/modules/devguide/pages/antsupport.adoc
@@ -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]
 ....
@@ -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]
@@ -510,7 +510,7 @@ that can be handled by iajc/ajc.
 === 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`.
 
@@ -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:
@@ -735,7 +735,7 @@ argfile).
 
 ==== 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
@@ -818,8 +818,8 @@ 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.
 
diff --git a/docs/modules/devguide/pages/compatibility.adoc b/docs/modules/devguide/pages/compatibility.adoc
index ea96ebf3c..f96811f30 100644
--- a/docs/modules/devguide/pages/compatibility.adoc
+++ b/docs/modules/devguide/pages/compatibility.adoc
@@ -87,7 +87,7 @@ were necessary when moving to binary weaving in the 1.1 release, but at
 this time we don't anticipate more in the future. You might also find
 that the program behaves differently if you relied on behavior specific
 to that compiler/weaver, but which is not specified in the
-xref:../progguide/semantics.html[Semantics appendix to the Programming
+xref:progguide:semantics.adoc[Semantics appendix to the Programming
 Guide].
 
 [[upgrading]]
diff --git a/docs/modules/devguide/pages/devguide.adoc b/docs/modules/devguide/pages/devguide.adoc
index 2dda421e8..2ca13a01c 100644
--- a/docs/modules/devguide/pages/devguide.adoc
+++ b/docs/modules/devguide/pages/devguide.adoc
@@ -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:progguide.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/modules/devguide/pages/index.adoc b/docs/modules/devguide/pages/index.adoc
index 4d74c3261..152cb1762 100644
--- a/docs/modules/devguide/pages/index.adoc
+++ b/docs/modules/devguide/pages/index.adoc
@@ -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:progguide.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/modules/devguide/pages/tools-intro.adoc b/docs/modules/devguide/pages/tools-intro.adoc
index c9bd34ea5..b9946c94f 100644
--- a/docs/modules/devguide/pages/tools-intro.adoc
+++ b/docs/modules/devguide/pages/tools-intro.adoc
@@ -4,7 +4,7 @@
 [[eclipse-aspectj]]
 == The Eclipse AspectJ implementation
 
-The xref:../progguide/index.html[AspectJ Programming Guide] describes
+The xref:progguide:index.adoc[AspectJ Programming Guide] describes
 the AspectJ language. This guide describes the AspectJ tools produced by
 the AspectJ team on https://eclipse.org/aspectj. The AspectJ tools
 include - ajc, the compiler/weaver; ajdoc, a documentation tool;
@@ -24,7 +24,7 @@ files that run in a Java VM. There are other ways to implement the
 language (e.g., compiler preprocessor, VM support); the AspectJ team has
 always tried to distinguish the language and the implementation so other
 groups could build alternative implementations of AspectJ. To that end,
-xref:../progguide/implementation.html[The AspectJ Programming Guide,
+xref:progguide:implementation.adoc[The AspectJ Programming Guide,
 Implementation Notes] describes how the Java bytecode form affects
 language semantics. VM- or source-based implementations may be free of
 these limits or impose limits of their own, but most should be fairly
diff --git a/docs/modules/faq/pages/faq.adoc b/docs/modules/faq/pages/faq.adoc
index a5a76e804..962af0b7c 100644
--- a/docs/modules/faq/pages/faq.adoc
+++ b/docs/modules/faq/pages/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/modules/pdguide/pages/ltwdump.adoc b/docs/modules/pdguide/pages/ltwdump.adoc
index 43d71805f..4a2f2953f 100644
--- a/docs/modules/pdguide/pages/ltwdump.adoc
+++ b/docs/modules/pdguide/pages/ltwdump.adoc
@@ -20,7 +20,7 @@ configure the weaver to dump the input classes as well.
 
 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]]
diff --git a/docs/modules/pdguide/pages/messages.adoc b/docs/modules/pdguide/pages/messages.adoc
index c32d07f07..cedf1858a 100644
--- a/docs/modules/pdguide/pages/messages.adoc
+++ b/docs/modules/pdguide/pages/messages.adoc
@@ -19,9 +19,9 @@ summarizes some of the more relevant messages.
 The compiler offers `-verbose`, `-warning`, and `-XLint` options when
 invoked using the command-line, Ant, or embedded in an IDE. All options
 are listed in the AspectJ Development Environment Guide sections for
-xref:../devguide/ajc.adoc#ajc[Ajc] and
-xref:../devguide/antsupport.adoc#antTasks[Ant Tasks]. The
-xref:../devguide/ltw.adoc#ltw[Load-time Weaving] section describes how to
+xref:devguide:ajc.adoc#ajc[Ajc] and
+xref:devguide:antsupport.adoc#antTasks[Ant Tasks]. The
+xref:devguide:ltw.adoc#ltw[Load-time Weaving] section describes how to
 use XML configuration files and system properties to pass options to the
 weaver. (You can also pass options to the weaver using system properties
 in build- time weaving.) The `-verbose` option has the effect of
@@ -38,9 +38,9 @@ compiler and weaver messages.
 The tables below list some options, System Properties (for LTW only) and
 Java 5 annotations used to control AspectJ messages. The method of
 configuration depends on your environment so please refer to the
-relevant documentation for xref:../devguide/ajc.adoc[ajc],
-xref:../devguide/antsupport.adoc#antTasks[Ant] or
-xref:../devguide/ltw.adoc#weaver-options[LTW].
+relevant documentation for xref:devguide:ajc.adoc[ajc],
+xref:devguide:antsupport.adoc#antTasks[Ant] or
+xref:devguide:ltw.adoc#weaver-options[LTW].
 
 [cols=",",options="header",]
 |===
@@ -59,9 +59,9 @@ output .class files.)
 
 |`messageHolderClass`/ `-XmessageHolderClass:` |In Ant tasks and LTW
 respectively specify the class to receive all messages. See
-xref:../devguide/antsupport.adoc#antTasks-iajc-options[iajc task
+xref:devguide:antsupport.adoc#antTasks-iajc-options[iajc task
 options] or
-xref:../devguide/ltw.adoc#weaver-options[Weaver Options].
+xref:devguide:ltw.adoc#weaver-options[Weaver Options].
 |===
 
 [cols=",",options="header",]
diff --git a/docs/modules/pdguide/pages/pointcuts.adoc b/docs/modules/pdguide/pages/pointcuts.adoc
index e5199fc95..2a93f86e9 100644
--- a/docs/modules/pdguide/pages/pointcuts.adoc
+++ b/docs/modules/pdguide/pages/pointcuts.adoc
@@ -49,7 +49,7 @@ each join point? This translates to `this()`, `target()`, `args()`,
 . Are there any advice or implementation limitations at issue? This
 involves knowing the few constraints on AspectJ imposed by Java bytecode
 as listed in the AspectJ Programming Guide section on
-xref:../progguide/implementation.adoc#implementation[Implementation Notes].
+xref:progguide:implementation.adoc#implementation[Implementation Notes].
 
 It's much faster to iterate a pointcut at compile-time using declare
 warning (even better, some errors are identified at parse-time in the
diff --git a/docs/modules/release/pages/README-1.5.0.adoc b/docs/modules/release/pages/README-1.5.0.adoc
index 6cab50115..5e2d1a2e5 100644
--- a/docs/modules/release/pages/README-1.5.0.adoc
+++ b/docs/modules/release/pages/README-1.5.0.adoc
@@ -4,11 +4,10 @@ _© 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
-AspectJ 5].
+general. For language changes, see xref:adk15notebook:adk15notebook.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
 the latest documentation, see
diff --git a/docs/modules/release/pages/README-1.9.0.adoc b/docs/modules/release/pages/README-1.9.0.adoc
index 1bb02ea33..cc325f1f2 100644
--- a/docs/modules/release/pages/README-1.9.0.adoc
+++ b/docs/modules/release/pages/README-1.9.0.adoc
@@ -1,4 +1,8 @@
 = AspectJ 1.9.0
+:doctype: book
+:leveloffset: +1
+
+= AspectJ 1.9.0
 
 _© Copyright 2018 Contributors. All rights reserved._
 
diff --git a/docs/modules/release/pages/README-1.9.19.adoc b/docs/modules/release/pages/README-1.9.19.adoc
index 563bf9d0d..c34786812 100644
--- a/docs/modules/release/pages/README-1.9.19.adoc
+++ b/docs/modules/release/pages/README-1.9.19.adoc
@@ -2,10 +2,6 @@
 
 _© Copyright 2022 Contributors. All rights reserved._
 
-= AspectJ 1.9.19
-
-_© Copyright 2022 Contributors. All rights reserved._
-
 _Release info: 1.9.19 available 21-Dec-2022_
 
 Please note that Bugzilla for issue management is deprecated and new issues should be filed as
diff --git a/docs/modules/release/pages/README-1.9.20.adoc b/docs/modules/release/pages/README-1.9.20.adoc
index 34ff738ea..d44769238 100644
--- a/docs/modules/release/pages/README-1.9.20.adoc
+++ b/docs/modules/release/pages/README-1.9.20.adoc
@@ -1,3 +1,8 @@
+= AspectJ 1.9.20
+
+:doctype: book
+:leveloffset: +1
+
 = AspectJ 1.9.20.1
 
 _© Copyright 2023 Contributors. All rights reserved._
diff --git a/docs/modules/release/pages/README-1.9.9.adoc b/docs/modules/release/pages/README-1.9.9.adoc
index 2404b31f9..b4dda99ba 100644
--- a/docs/modules/release/pages/README-1.9.9.adoc
+++ b/docs/modules/release/pages/README-1.9.9.adoc
@@ -1,3 +1,7 @@
+= AspectJ 1.9.9
+:doctype: book
+:leveloffset: +1
+
 = AspectJ 1.9.9.1
 
 _© Copyright 2022 Contributors. All rights reserved._
diff --git a/docs/modules/release/pages/changes.adoc b/docs/modules/release/pages/changes.adoc
index 9bfcc9cd7..60f9f6105 100644
--- a/docs/modules/release/pages/changes.adoc
+++ b/docs/modules/release/pages/changes.adoc
@@ -1,39 +1,38 @@
 = 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,7 +397,7 @@ 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.
 
@@ -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
@@ -477,7 +476,12 @@ concise bug reports on some of these issues.
 [[_1_0_5ajde]]
 == 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
@@ -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]
@@ -665,7 +669,7 @@ 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]
@@ -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
@@ -784,7 +788,7 @@ 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]
@@ -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]
@@ -836,12 +840,12 @@ ajdb is still considered early-access software.)
 * xref:#_1_0_0taskdefs[Ant taskdefs]
 
 [[_1_0_0language]]
-= Language
+== Language
 
 There were no language changes for this release.
 
 [[_1_0_0compiler]]
-= Compiler
+== Compiler
 
 Several minor bugs primarily in error handling were reported and have
 been fixed in this release. The two most serious bugs are described
@@ -861,30 +865,30 @@ class overrode introduced methods on an interface implemented by that
 class. This is now fixed.
 
 [[_1_0_0ajde]]
-= AJDE
+== AJDE
 
 Numerous user interface refinements were made to the browser and core
 AJDE functionality. Error handling and reporting has been improved. All
 of the AJDE tools now support the ".aj" file extension.
 
-== AJDE for JBuilder
+=== AJDE for JBuilder
 
 * The AspectJ Browser now uses JBuilder's icons and distinguishes nodes
 by visibility.
 * Project-setting VM parameters are now supported by the "AJDE Run"
 button.
 
-== AJDE for Forte
+=== AJDE for Forte
 
 * The AspectJ Browser now uses Forte's icons and distinguishes nodes by
 visibility
 
-== AJBrowser
+=== AJBrowser
 
 * Documentation for the browser is now available at
 http://aspectj.org/docs
 
-== Emacs Support: aspectj-mode and AJDEE
+=== Emacs Support: aspectj-mode and AJDEE
 
 * Improved updating of annotations during editing.
 * Pop-up jump menu now placed (with mouse pointer) near cursor.
@@ -904,10 +908,10 @@ the syntax message.
 * Fork is not supported in the AJDoc taskdef
 
 [[_1_0rc3]]
-= 1.0rc3
+= AspectJ 1.0rc3
 
 [[_1_0rc3language]]
-= Language
+== Language
 
 There have been several minor clarifications/changes to the language.
 
@@ -921,7 +925,7 @@ to this language feature.
 http://aspectj.org/pipermail/users/2001/001258.html[More details...]
 
 [[_1_0rc3compiler]]
-= Compiler
+== Compiler
 
 This release saw several changes to the compiler in order to work-around
 known bugs in different JVMs, or to otherwise mimic the behavior of
@@ -960,7 +964,7 @@ the jikes group, and had added the feature days before getting our first
 bug report for it not being there.
 
 [[_1_0rc3ajde]]
-= AJDE
+== AJDE
 
 * The structure view has been improved.
 * Multiple user-configurable views are supported.
@@ -974,7 +978,7 @@ current file or the project root.
 associations are now navigable.
 * A depth slider for controlling tree-expansion has been added.
 
-== AJDE for JBuilder
+=== AJDE for JBuilder
 
 * Changes:
 * Inline annotations support have been improved and made consistent with
@@ -983,20 +987,20 @@ structure).
 * The current structure view persists across IDE launches.
 * An enabled AJDE no longer slows down JBuilder shutdown.
 
-== AJDE for Forte
+=== AJDE for Forte
 
 * Execution remembers main class.
 * The bug causing an error during a "Mode" and "Explorer" switch has
 been fixed.
 
-== AJBrowser
+=== AJBrowser
 
 * AJBrowser is currently an undocumented demonstration application. To
 use it type: ajbrowser <lst file1> <lst file2> ...
 * Multiple source locations can be shown by selecting multiple nodes and
 right-clicking to select the "Display Sources" command.
 
-== Emacs Support: aspectj-mode and AJDEE
+=== Emacs Support: aspectj-mode and AJDEE
 
 * Numerous jump-menu improvements, including operation of pop-ups.
 * For AJDEE, compatibility with JDEE 2.2.9beta4. Also, fixes in
@@ -1036,30 +1040,30 @@ $\{ant.home}/lib.
 '''''
 
 [[_1_0rc2]]
-= 1.0rc2
+= AspectJ 1.0rc2
 
 * xref:#_1_0rc2language[Language]
 * xref:#_1_0rc2compiler[Compiler]
 * xref:#_1_0rc2ajde[AJDE]
 
 [[_1_0rc2language]]
-= Language
+== Language
 
 There are no language changes in this release. This is a bug fix release
 only.
 
 [[_1_0rc2compiler]]
-= Compiler
+== Compiler
 
 A bug in handling inner type names that conflict with enclosing type
 names was fixed. Many error messages were improved.
 
 [[_1_0rc2ajde]]
-= AJDE
+== AJDE
 
 * This is a bug fix release only.
 
-== AJDE for JBuilder
+=== AJDE for JBuilder
 
 * Changes:
 ** Fixed bug causing the output path to be ignored and .class files to
@@ -1077,7 +1081,7 @@ placed in the project's "Working directory".
 ** The debugger has not seen much use and it's stability and performance
 is limited.
 
-== AJDE for Forte
+=== AJDE for Forte
 
 * Changes:
 ** Moved the "AspectJ" menu into the "Tools" menu in order to make it
@@ -1091,7 +1095,7 @@ Switching to a different tab in the ProjectExplorer has the same effect.
 ** The debugger has not seen much use and it's stability and performance
 is limited.
 
-== AJBrowser
+=== AJBrowser
 
 * Changes:
 ** ...
@@ -1104,7 +1108,7 @@ use it type:
 ajbrowser <lst file1> <lst file2> ...
 ....
 
-== Emacs Support: aspectj-mode and AJDEE
+=== Emacs Support: aspectj-mode and AJDEE
 
 This release now properly displays annotations for call sites and
 introductions. Robustness has been improved in several dimensions,
@@ -1114,14 +1118,14 @@ properly when changing directories.
 '''''
 
 [[_1_0rc1]]
-= 1.0rc1
+= AspectJ 1.0rc1
 
 * xref:#_1_0rc1language[Language]
 * xref:#_1_0rc1compiler[Compiler]
 * xref:#_1_0rc1ajde[AJDE]
 
 [[_1_0rc1language]]
-= Language
+== Language
 
 Some of the details of the specification for perthis and pertarget have
 changed. These changes make these language constructs implementable on
@@ -1138,7 +1142,7 @@ now we've chosen to leave the most room to design them right in a future
 release.
 
 [[_1_0rc1compiler]]
-= Compiler
+== Compiler
 
 ajc now directly generates .class files without using javac as a
 back-end. This should result in improved compiler performance, better
@@ -1157,7 +1161,7 @@ release of ajc will run under SUN's jdk1.4beta2. However, we still
 strongly recommend that most users use the non-beta jdk1.3.
 
 [[_1_0rc1ajde]]
-= AJDE
+== AJDE
 
 * The structure view can now be configured (using the "Options" dialog)
 to display different kinds of associations between program elements that
@@ -1166,7 +1170,7 @@ appear in the tree.
 * When navigating links the structure view will stay synchronized with
 the editor.
 
-== AJDE for JBuilder
+=== AJDE for JBuilder
 
 * Changes:
 ** Inline structural navigation annotations appear in the gutter of the
@@ -1177,7 +1181,7 @@ introduction.
 ** The debugger has not seen much use and it's stability and performance
 is limited.
 
-== AJDE for Forte
+=== AJDE for Forte
 
 * Changes:
 ** Support for Forte 3 and Netbeans 3.2 has been added.
@@ -1191,7 +1195,7 @@ Switching to a different tab in the ProjectExplorer has the same effect.
 ** The debugger has not seen much use and it's stability and performance
 is limited.
 
-== AJBrowser
+=== AJBrowser
 
 * Changes:
 ** Build configuration file editor added.
@@ -1204,7 +1208,7 @@ use it type:
 ajbrowser <lst file1> <lst file2> ...
 ....
 
-== Aspectj-mode and AJDEE: AspectJ support in Emacs
+=== Aspectj-mode and AJDEE: AspectJ support in Emacs
 
 This release of AspectJ support for Emacs includes corrections to the
 documentation and the appearance of annotations and jumps in the editing
@@ -1215,7 +1219,7 @@ computational overhead.
 '''''
 
 [[_1_0beta1]]
-= 1.0beta1
+= AspectJ 1.0beta1
 
 * xref:#_1_0beta1language[Language]
 * xref:#_1_0beta1compiler[Compiler]
@@ -1223,7 +1227,7 @@ computational overhead.
 * xref:#_1_0beta1ajde[AJDE]
 
 [[_1_0beta1language]]
-= Language
+== Language
 
 There is one language change since 1.0alpha1. The static modifier is no
 longer needed or allowed on pointcut declarations. Name binding for
@@ -1237,7 +1241,7 @@ changes in the next release to address issues of implementability on the
 JVM as well as related issues.
 
 [[_1_0beta1compiler]]
-= Compiler
+== Compiler
 
 The ajc compiler should now catch all errors in source code and you
 should no longer see errors coming from files in 'ajworkingdir'. Please
@@ -1250,7 +1254,7 @@ very thorough bug report on this broken feature days after the 1.0alpha1
 release.
 
 [[_1_0beta1ajbrowser]]
-= AJBrowser
+== AJBrowser
 
 * Support for executing classes has been added.
 * .lst can now be passed as arguments on the command line.
@@ -1260,7 +1264,7 @@ release.
 that the browser is launched with.
 
 [[_1_0beta1ajde]]
-= AJDE
+== AJDE
 
 * The performance and UI of the structure tree has been improved.
 * Compilation now runs in a separate thread and a progress monitor is
@@ -1273,7 +1277,7 @@ the console that the IDE was launched from. No more errors should be
 passed to javac, so please report this behavior and the corresponding
 error message as a bug.
 
-== AJDE for JBuilder
+=== AJDE for JBuilder
 
 * Known bugs have been fixed.
 * Classpath separator character is no longer hardcoded.
@@ -1283,7 +1287,7 @@ have been added.
 ** The debugger has not seen much use and it's stability and performance
 is limited.
 
-== AJDE for Forte
+=== AJDE for Forte
 
 * Known bugs have been fixed.
 * Limitations:
@@ -1294,7 +1298,7 @@ to be restarted for the AspectJ window to show again.
 ** The debugger has not seen much use and it's stability and performance
 is limited.
 
-== Aspectj-mode and AJDEE: AspectJ support in Emacs
+=== Aspectj-mode and AJDEE: AspectJ support in Emacs
 
 AspectJ Development Environment for Emacs has been split into two
 pieces, aspectj-mode (an extension of java-mode), and AJDEE (an
@@ -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
diff --git a/docs/modules/release/pages/porting.adoc b/docs/modules/release/pages/porting.adoc
index a78b7f2a2..b86a80d16 100644
--- a/docs/modules/release/pages/porting.adoc
+++ b/docs/modules/release/pages/porting.adoc
@@ -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]