Add asciidoc release notes up to 1.9.21

and fix some minor punctuation issues in older release notes.

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

10 files changed, 288 insertions, 478 deletions

diff --git a/docs/dist/doc/README-1919.adoc b/docs/dist/doc/README-1919.adoc
new file mode 100644
index 000000000..07618a02c
--- /dev/null
+++ b/docs/dist/doc/README-1919.adoc
@@ -0,0 +1,92 @@
+== AspectJ 1.9.19
+
+_© 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
+https://github.com/eclipse/org.aspectj/issues/new[GitHub issues]. The list of issues addressed for 1.9.19 can be found
+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
+
+AspectJ 1.9.19 supports https://openjdk.java.net/projects/jdk/19/[Java 19] and its final, preview and incubator
+features, such as:
+
+* Record patterns (preview)
+* Virtual threads (preview)
+* Pattern matching for `switch` (preview 3)
+* Structured concurrency (incubator)
+
+Please note that the upstream Eclipse Java Compiler (ECJ) which the AspectJ Compiler (AJC) is a fork of still has some
+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
+
+* 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
+
+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):
+
+* https://github.com/eclipse/org.aspectj/tree/master/tests/features198/java17[Pattern matching for switch (preview 1)]
+* https://github.com/eclipse/org.aspectj/tree/master/tests/features199/java18[Pattern matching for switch (preview 2)]
+* https://github.com/eclipse/org.aspectj/tree/master/tests/features1919/java19[Pattern matching for switch (preview 3),
+  record patterns (preview 1)]
+* Please note that presently there is no specific sample code for virtual threads and structured concurrency in the
+  AspectJ code base, because these are just new APIs, no Java language features. You can find sample code for these
+  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
+
+* 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
+  begin with, at least the AspectJ weaver or compiler should handle the situation gracefully, which now it does by
+  simply ignoring errors caused by it. See https://bugs.eclipse.org/bugs/show_bug.cgi?id=366085[Bugzilla #366085] and
+  https://github.com/eclipse/org.aspectj/pull/196[pull request #196]. Better than this workaround would be for the
+  compiler or weaver to actually print a warning when meeting source level annotations in declare statements. Hence,
+  follow-up issue https://github.com/eclipse/org.aspectj/issues/201[#201] was created.
+* Remove legacy AspectJ Browser code and documentation.
+* Thanks to Andrey Turbanov for several clean code contributions.
+
+=== AspectJ usage hints
+
+==== 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
+Core), which AspectJ is a fork of. You can still compile to legacy target versions as low as Java 1.3 when compiling
+plain Java code or using plain Java ITD constructs which do not require the AspectJ runtime `aspectjrt`, but the
+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+
+
+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
+the JVM parameter `--add-opens java.base/java.lang=ALL-UNNAMED` in 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.
+
+==== 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.
+
+Please note, that you cannot run code compiled with preview features on any other JDK than the one used for compilation.
+For example, records compiled with preview on JDK 15 cannot be used on JDK 16 without recompilation. This is a JVM
+limitation unrelated to AspectJ. Also, e.g. sealed classes are preview-1 on JDK 15 and preview-2 on JDK 16. You still
+need to recompile, no matter what.
diff --git a/docs/dist/doc/README-1919.html b/docs/dist/doc/README-1919.html
deleted file mode 100644
index 9861baf97..000000000
--- a/docs/dist/doc/README-1919.html
+++ /dev/null
@@ -1,158 +0,0 @@
-<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
-<html>
-
-<head>
-<title>AspectJ 1.9.19 Readme</title>
-<style type="text/css">
-  <!--
-  P   { margin-left:  20px; }
-  PRE { margin-left:  20px; }
-  LI  { margin-left:  20px; }
-  H4  { margin-left:  20px; }
-  H3  { margin-left:  10px; }
-  -->
-</style>
-</head>
-
-<body>
-<div align="right"><small>&copy; Copyright 2022 Contributors. All rights reserved.</small></div>
-
-<h1>AspectJ 1.9.19</h1>
-
-<p>
-  Please note that Bugzilla for issue management is deprecated and new issues should be filed as
-  <a href="https://github.com/eclipse/org.aspectj/issues/new">GitHub issues</a>.
-  The list of issues addressed for 1.9.19 can be found here:
-  <ul>
-    <li><a href="https://github.com/eclipse/org.aspectj/issues?q=is%3Aissue+is%3Aclosed++milestone%3A1.9.19">GitHub 1.9.19</a></li>
-    <li><a href="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</a></li>
-  </ul>
-</p>
-
-<h2>New features</h2>
-
-<p>
-  AspectJ 1.9.19 supports <a href="https://openjdk.java.net/projects/jdk/19/">Java 19</a> and its final, preview and
-  incubator features, such as:
-</p>
-<ul>
-  <li>Record patterns (preview)</li>
-  <li>Virtual threads (preview)</li>
-  <li>Pattern matching for <tt>switch</tt> (preview 3)</li>
-  <li>Structured concurrency (incubator)</li>
-</ul>
-
-<p>
-  Please note that the upstream Eclipse Java Compiler (ECJ) which the AspectJ Compiler (AJC) is a fork of still has some
-  open issues concerning Java 19 preview feature support, see the list in
-  <a href="https://github.com/eclipse/org.aspectj/issues/184#issuecomment-1272254940">this comment</a>. AJC therefore
-  inherits the same problems for the specific cases described in the linked issues.
-</p>
-
-<h2>Improvements</h2>
-
-<ul>
-  <li>
-    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
-    <a href="https://github.com/eclipse/org.aspectj/issues/170#issuecomment-1214163297">this comment in #170</a> for
-    more details.
-  </li>
-</ul>
-
-<h2>Code examples</h2>
-
-<p>
-  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):
-</p>
-<ul>
-  <li>
-    <a href="https://github.com/eclipse/org.aspectj/tree/master/tests/features198/java17">
-      Pattern matching for switch (preview 1)
-    </a>
-  </li>
-  <li>
-    <a href="https://github.com/eclipse/org.aspectj/tree/master/tests/features199/java18">
-      Pattern matching for switch (preview 2)
-    </a>
-  </li>
-  <li>
-    <a href="https://github.com/eclipse/org.aspectj/tree/master/tests/features1919/java19">
-      Pattern matching for switch (preview 3), record patterns (preview 1)
-    </a>
-  </li>
-  <li>
-    Please note that presently there is no specific sample code for virtual threads and structured concurrency in the
-    AspectJ code base, because these are just new APIs, no Java language features. You can find sample code for these
-    concurrency features elsewhere, e.g. in the corresponding JEPs. In AspectJ, they should just work transparently
-    like any other Java API.
-  </li>
-</ul>
-
-<h2>Other changes and bug fixes</h2>
-
-<ul>
-  <li>
-    Fix (or rather work around) an old bug occurring when compiling or weaving code using ITD to declare annotations
-    with <tt>SOURCE</tt> retention on types, methods, constructors or fields. While declaring such annotations does not
-    make sense to begin with, at least the AspectJ weaver or compiler should handle the situation gracefully, which now
-    it does by simply ignoring errors caused by it. See <a href="https://bugs.eclipse.org/bugs/show_bug.cgi?id=366085">
-    Bugzilla #366085</a> and <a href="https://github.com/eclipse/org.aspectj/pull/196">pull request #196</a>. Better
-    than this workaround would be for the compiler or weaver to actually print a warning when meeting source level
-    annotations in declare statements. Hence, follow-up issue
-    <a href="https://github.com/eclipse/org.aspectj/issues/201">#201</a> was created.
-  </li>
-  <li>
-    Remove legacy AspectJ Browser code and documentation.
-  </li>
-  <li>
-    Thanks to Andrey Turbanov for several clean code contributions.
-  </li>
-</ul>
-
-<h2>AspectJ usage hints</h2>
-
-<h3>AspectJ compiler build system requirements</h3>
-
-<p>
-  Since 1.9.7, the AspectJ compiler <tt>ajc</tt> (contained in the <tt>aspectjtools</tt> 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), which AspectJ is a fork of. You can still compile to legacy target versions as low as Java 1.3
-  when compiling plain Java code or using plain Java ITD constructs which do not require the AspectJ runtime
-  <tt>aspectjrt</tt>, but the compiler itself needs JDK 11+. Just like in previous AspectJ versions, both the runtime
-  <tt>aspectjrt</tt> and the load-time weaver <tt>aspectjweaver</tt> still only require JRE 8+.
-</p>
-
-<h3>Use LTW on Java 16+</h3>
-
-<p>
-  Please note that if you want to use load-time weaving on Java 16+, the weaving agent collides with
-  <a href="https://openjdk.java.net/jeps/396">JEP 396 (Strongly Encapsulate JDK Internals by Default)</a> and related
-  subsequent JEPs. Therefore, you need to set the JVM parameter <tt>--add-opens java.base/java.lang=ALL-UNNAMED</tt> in
-  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.
-</p>
-
-<h3>Compile with Java preview features</h3>
-
-<p>
-  For features marked as preview on a given JDK, you need to compile with <tt>ajc --enable-preview</tt> and run with
-  <tt>java --enable-preview</tt> on that JDK.
-</p>
-<p>
-  Please note that you cannot run code compiled with preview features on any other JDK than the one used for
-  compilation. For example, records compiled with preview on JDK 15 cannot be used on JDK 16 without recompilation. This
-  is a JVM limitation unrelated to AspectJ. Also, e.g. sealed classes are preview-1 on JDK 15 and preview-2 on JDK 16.
-  You still need to recompile, no matter what.
-</p>
-
-<hr>
-
-<p>
-  <b>Available:</b> 1.9.19 on 21-Dec-2022
-</p>
-
-</body>
-
-</html>
diff --git a/docs/dist/doc/README-1920.adoc b/docs/dist/doc/README-1920.adoc
new file mode 100644
index 000000000..51b9033e9
--- /dev/null
+++ b/docs/dist/doc/README-1920.adoc
@@ -0,0 +1,109 @@
+== AspectJ 1.9.20.1
+
+_© Copyright 2023 Contributors. All rights reserved._
+
+_Release info: 1.9.20.1 available 04-Sep-2023_
+
+This is a bugfix release for 1.9.20, fixing two problems:
+
+* https://github.com/eclipse-aspectj/aspectj/issues/257[Regression bug 257] introduced in 1.9.20 would match negated
+  type patterns like `!void` or `!String[]` incorrectly.
+* https://github.com/spring-projects/spring-framework/issues/27761[Spring issue 27761] describes a problem where
+  AspectJ, when used by Spring AOP, in rare cases falsely considered bridge methods for overridden generic methods for
+  matching, leading to falsely negative matching results. See also
+  https://github.com/eclipse-aspectj/aspectj/issues/256[AspectJ tracker issue 256]).
+
+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
+
+_© Copyright 2023 Contributors. All rights reserved._
+
+_Release info: 1.9.20 available 16-Aug-2023_
+
+Please note that Bugzilla for issue management is deprecated and new issues should be filed as
+https://github.com/eclipse/org.aspectj/issues/new[GitHub issues]. The list of issues addressed for 1.9.20 can be found
+here:
+
+* https://github.com/eclipse/org.aspectj/issues?q=is%3Aissue+is%3Aclosed++milestone%3A1.9.20[GitHub 1.9.20]
+* 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
+
+AspectJ 1.9.20 supports https://openjdk.java.net/projects/jdk/20/[Java 20] and its final, preview and incubator
+features, such as:
+
+* Record patterns (preview)
+* Virtual threads (preview)
+* Pattern matching for `switch` (preview 3)
+* Structured concurrency (incubator)
+
+Please note, that the upstream Eclipse Java Compiler (ECJ), which the AspectJ Compiler (AJC) is a fork of, still has
+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
+
+* 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
+  Java language features. In AspectJ, some of those internal changes have not been properly upgraded for quite a while,
+  but this is now fixed. However, it might *require you to recompile your aspects and projects/classes using them.*
+  Otherwise, you might get problems in Eclipse IDE or under certain circumstances even when running newly compiled
+  aspects in older AspectJ versions and vice versa. You are on the safe side if you simply rebuild your projects. We are
+  sorry for the inconvenience, but we have to follow upstream ECJ and JDT changes.
+* Along with fixing https://github.com/eclipse-aspectj/aspectj/issues/24[GitHub bug 24], the syntax for array type
+  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
+
+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):
+
+* https://github.com/eclipse/org.aspectj/tree/master/tests/features198/java17[Pattern matching for switch (preview 1)]
+* https://github.com/eclipse/org.aspectj/tree/master/tests/features199/java18[Pattern matching for switch (preview 2)]
+* https://github.com/eclipse/org.aspectj/tree/master/tests/features1919/java19[Pattern matching for switch (preview 3),
+  record patterns (preview 1)]
+* https://github.com/eclipse/org.aspectj/tree/master/tests/features1920/java20[Pattern matching for switch (preview 4),
+  record patterns (preview 2)]
+* Please note that presently there is no specific sample code for virtual threads and structured concurrency in the
+  AspectJ code base, because these are just new APIs, no Java language features. You can find sample code for these
+  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
+
+* 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 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
+Core), which AspectJ is a fork of. You can still compile to legacy target versions as low as Java 1.3 when compiling
+plain Java code or using plain Java ITD constructs which do not require the AspectJ runtime `aspectjrt`, but the
+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+
+
+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
+the JVM parameter `--add-opens java.base/java.lang=ALL-UNNAMED` in 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.
+
+==== 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.
+
+Please note, that you cannot run code compiled with preview features on any other JDK than the one used for compilation.
+For example, records compiled with preview on JDK 15 cannot be used on JDK 16 without recompilation. This is a JVM
+limitation unrelated to AspectJ. Also, e.g. sealed classes are preview-1 on JDK 15 and preview-2 on JDK 16. You still
+need to recompile, no matter what.
diff --git a/docs/dist/doc/README-1920.html b/docs/dist/doc/README-1920.html
deleted file mode 100644
index 604cb78c4..000000000
--- a/docs/dist/doc/README-1920.html
+++ /dev/null
@@ -1,182 +0,0 @@
-<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
-<html>
-
-<head>
-<title>AspectJ 1.9.20 Readme</title>
-<style type="text/css">
-  <!--
-  P   { margin-left:  20px; }
-  PRE { margin-left:  20px; }
-  LI  { margin-left:  20px; }
-  H4  { margin-left:  20px; }
-  H3  { margin-left:  10px; }
-  -->
-</style>
-</head>
-
-<body>
-<div align="right"><small>&copy; Copyright 2023 Contributors. All rights reserved.</small></div>
-
-<h1>AspectJ 1.9.20.1</h1>
-
-<p>
-  This is a bugfix release for 1.9.20, fixing two problems:
-  <ul>
-    <li>
-      <a href="https://github.com/eclipse-aspectj/aspectj/issues/257">Regression bug 257</a> introduced in 1.9.20 would
-      match negated type patterns like <tt>!void</tt> or <tt>!String[]</tt> incorrectly.
-    </li>
-    <li>
-      <a href="https://github.com/spring-projects/spring-framework/issues/27761">Spring issue 27761</a> describes a
-      problem where AspectJ, when used by Spring AOP, in rare cases falsely considered bridge methods for overridden
-      generic methods for matching, leading to falsely negative matching results. See also
-      <a href="https://github.com/eclipse-aspectj/aspectj/issues/256">AspectJ tracker issue 256</a>).
-    </li>
-  </ul>
-</p>
-<p>
-  The list of issues addressed for 1.9.20.1 can be found
-  <a href="https://github.com/eclipse/org.aspectj/issues?q=is%3Aissue+is%3Aclosed++milestone%3A1.9.20.1">here</a>.
-</p>
-
-<h1>AspectJ 1.9.20</h1>
-
-<p>
-  Please note that Bugzilla for issue management is deprecated and new issues should be filed as
-  <a href="https://github.com/eclipse/org.aspectj/issues/new">GitHub issues</a>.
-  The list of issues addressed for 1.9.20 can be found here:
-  <ul>
-    <li><a href="https://github.com/eclipse/org.aspectj/issues?q=is%3Aissue+is%3Aclosed++milestone%3A1.9.20">GitHub 1.9.20</a></li>
-    <li><a href="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</a></li>
-  </ul>
-</p>
-
-<h2>New features</h2>
-
-<p>
-  AspectJ 1.9.20 supports <a href="https://openjdk.java.net/projects/jdk/20/">Java 20</a> and its final, preview and
-  incubator features, such as:
-</p>
-<ul>
-  <li>Record patterns (preview)</li>
-  <li>Virtual threads (preview)</li>
-  <li>Pattern matching for <tt>switch</tt> (preview 3)</li>
-  <li>Structured concurrency (incubator)</li>
-</ul>
-
-<p>
-  Please note that the upstream Eclipse Java Compiler (ECJ) which the AspectJ Compiler (AJC) is a fork of still has some
-  open issues concerning Java 20 preview feature support, see the list in
-  <a href="https://github.com/eclipse/org.aspectj/issues/184#issuecomment-1272254940">this comment</a>. AJC therefore
-  inherits the same problems for the specific cases described in the linked issues.
-</p>
-
-<h2>Improvements</h2>
-
-<ul>
-  <li>
-    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 Java language features. In AspectJ, some of those internal changes have not been properly upgraded for
-    quite a while, but this is now fixed. However, it might <b>require you to recompile your aspects and
-    projects/classes using them.</b> Otherwise, you might get problems in Eclipse IDE or under certain circumstances
-    even when running newly compiled aspects in older AspectJ versions and vice versa. You are on the safe side if you
-    simply rebuild your projects. We are sorry for the inconvenience, but we have to follow upstream ECJ and JDT
-    changes.
-  </li>
-  <li>
-    Along with fixing <a href="https://github.com/eclipse-aspectj/aspectj/issues/24">GitHub bug 24</a>, the syntax for
-    array type matching has been improved considerably. You can find some examples
-    <a href="https://github.com/eclipse-aspectj/aspectj/tree/master/tests/bugs1920/github_24">here</a>.
-  </li>
-</ul>
-
-<h2>Code examples</h2>
-
-<p>
-  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):
-</p>
-<ul>
-  <li>
-    <a href="https://github.com/eclipse/org.aspectj/tree/master/tests/features198/java17">
-      Pattern matching for switch (preview 1)
-    </a>
-  </li>
-  <li>
-    <a href="https://github.com/eclipse/org.aspectj/tree/master/tests/features199/java18">
-      Pattern matching for switch (preview 2)
-    </a>
-  </li>
-  <li>
-    <a href="https://github.com/eclipse/org.aspectj/tree/master/tests/features1919/java19">
-      Pattern matching for switch (preview 3), record patterns (preview 1)
-    </a>
-  </li>
-  <li>
-    <a href="https://github.com/eclipse/org.aspectj/tree/master/tests/features1920/java20">
-      Pattern matching for switch (preview 4), record patterns (preview 2)
-    </a>
-  </li>
-  <li>
-    Please note that presently there is no specific sample code for virtual threads and structured concurrency in the
-    AspectJ code base, because these are just new APIs, no Java language features. You can find sample code for these
-    concurrency features elsewhere, e.g. in the corresponding JEPs. In AspectJ, they should just work transparently
-    like any other Java API.
-  </li>
-</ul>
-
-<h2>Other changes and bug fixes</h2>
-
-<ul>
-  <li>
-    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.
-  </li>
-</ul>
-
-<h2>AspectJ usage hints</h2>
-
-<h3>AspectJ compiler build system requirements</h3>
-
-<p>
-  Since 1.9.7, the AspectJ compiler <tt>ajc</tt> (contained in the <tt>aspectjtools</tt> 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), which AspectJ is a fork of. You can still compile to legacy target versions as low as Java 1.3
-  when compiling plain Java code or using plain Java ITD constructs which do not require the AspectJ runtime
-  <tt>aspectjrt</tt>, but the compiler itself needs JDK 11+. Just like in previous AspectJ versions, both the runtime
-  <tt>aspectjrt</tt> and the load-time weaver <tt>aspectjweaver</tt> still only require JRE 8+.
-</p>
-
-<h3>Use LTW on Java 16+</h3>
-
-<p>
-  Please note that if you want to use load-time weaving on Java 16+, the weaving agent collides with
-  <a href="https://openjdk.java.net/jeps/396">JEP 396 (Strongly Encapsulate JDK Internals by Default)</a> and related
-  subsequent JEPs. Therefore, you need to set the JVM parameter <tt>--add-opens java.base/java.lang=ALL-UNNAMED</tt> in
-  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.
-</p>
-
-<h3>Compile with Java preview features</h3>
-
-<p>
-  For features marked as preview on a given JDK, you need to compile with <tt>ajc --enable-preview</tt> and run with
-  <tt>java --enable-preview</tt> on that JDK.
-</p>
-<p>
-  Please note that you cannot run code compiled with preview features on any other JDK than the one used for
-  compilation. For example, records compiled with preview on JDK 15 cannot be used on JDK 16 without recompilation. This
-  is a JVM limitation unrelated to AspectJ. Also, e.g. sealed classes are preview-1 on JDK 15 and preview-2 on JDK 16.
-  You still need to recompile, no matter what.
-</p>
-
-<hr>
-
-<p>
-  <b>Available:</b> 1.9.20 on 16-Aug-2023
-</p>
-
-</body>
-
-</html>
diff --git a/docs/dist/doc/README-1921.adoc b/docs/dist/doc/README-1921.adoc
new file mode 100644
index 000000000..d205ed36d
--- /dev/null
+++ b/docs/dist/doc/README-1921.adoc
@@ -0,0 +1,81 @@
+== AspectJ 1.9.21
+
+_© Copyright 2023 Contributors. All rights reserved._
+
+_Release info: 1.9.21 available 11-Dec-2023_
+
+Please note that Bugzilla for issue management is deprecated and new issues should be filed as
+https://github.com/eclipse/org.aspectj/issues/new[GitHub issues]. The list of issues addressed for 1.9.21 can be found
+here:
+
+* https://github.com/eclipse/org.aspectj/issues?q=is%3Aissue+is%3Aclosed++milestone%3A1.9.21[GitHub 1.9.21]
+* 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
+
+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:
+
+* Record patterns
+* Pattern matching for switch
+* Virtual threads
+* Sequenced collections
+* Structured concurrency (preview)
+* String templates (preview)
+* Instance main methods (preview)
+
+Unfortunately, even after holding back the AspectJ release for 3 months after JDK 21 general availability, waiting for
+Eclipse JDT Core and the Eclipse Java Compiler (ECJ) to catch up with Java 21 language features, even with Java 21
+officially supported in Eclipse 2023-12, some preview features are still unimplemented in ECJ:
+
+* Unnamed classes (preview)
+* Unnamed patterns and variables (preview)
+
+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
+
+* 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
+
+* No major bug fixes
+
+=== AspectJ usage hints
+
+==== 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
+Core), which AspectJ is a fork of. You can still compile to legacy target versions as low as Java 1.3 when compiling
+plain Java code or using plain Java ITD constructs which do not require the AspectJ runtime `aspectjrt`, but the
+compiler itself needs JDK 17+. Just like in previous AspectJ versions, both the runtime `aspectjrt` and the load-time
+weaver `aspectjweaver` still only require JRE 8+.
+
+Please note: If you run `ajc` on JDKs 11-16, you will probably see an error like `java.lang.NoSuchFieldError:
+RELEASE_17`, and an _ajcore.*.txt_ dump file will be created, while running it on even older JDKs will rather yield an
+`UnsupportedClassVersionError`. See https://github.com/eclipse-aspectj/aspectj/issues/269[GitHub issue 269] for more
+details.
+
+History: Since 1.9.8, the AspectJ compiler ajc needed JDK 11+, before then JDK 8+.
+
+==== 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
+JEPs. Therefore, you need to set the JVM parameter `--add-opens java.base/java.lang=ALL-UNNAMED` in 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.
+
+==== 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.
+
+Please note, that you cannot run code compiled with preview features on any other JDK than the one used for compilation.
+For example, records compiled with preview on JDK 15 cannot be used on JDK 16 without recompilation. This is a JVM
+limitation unrelated to AspectJ. Also, e.g. sealed classes are preview-1 on JDK 15 and preview-2 on JDK 16. You still
+need to recompile, no matter what.
diff --git a/docs/dist/doc/README-1921.html b/docs/dist/doc/README-1921.html
deleted file mode 100644
index 7f443a25c..000000000
--- a/docs/dist/doc/README-1921.html
+++ /dev/null
@@ -1,133 +0,0 @@
-<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
-<html>
-
-<head>
-<title>AspectJ 1.9.21 Readme</title>
-<style type="text/css">
-  <!--
-  P   { margin-left:  20px; }
-  PRE { margin-left:  20px; }
-  LI  { margin-left:  20px; }
-  H4  { margin-left:  20px; }
-  H3  { margin-left:  10px; }
-  -->
-</style>
-</head>
-
-<body>
-<div align="right"><small>&copy; Copyright 2023 Contributors. All rights reserved.</small></div>
-
-<h1>AspectJ 1.9.21</h1>
-
-<p>
-  Please note that Bugzilla for issue management is deprecated and new issues should be filed as
-  <a href="https://github.com/eclipse/org.aspectj/issues/new">GitHub issues</a>.
-  The list of issues addressed for 1.9.21 can be found here:
-  <ul>
-    <li><a href="https://github.com/eclipse/org.aspectj/issues?q=is%3Aissue+is%3Aclosed++milestone%3A1.9.21">GitHub 1.9.21</a></li>
-    <li><a href="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</a></li>
-  </ul>
-</p>
-
-<h2>New features</h2>
-
-<p>
-  AspectJ 1.9.21 supports <a href="https://openjdk.java.net/projects/jdk/21/">Java 21</a>, its final features and a
-  subset of preview features, such as:
-</p>
-<ul>
-  <li>Record patterns</li>
-  <li>Pattern matching for <tt>switch</tt></li>
-  <li>Virtual threads</li>
-  <li>Sequenced collections</li>
-  <li>Structured concurrency (preview)</li>
-  <li>String templates (preview)</li>
-  <li>Instance main methods (preview)</li>
-</ul>
-
-<p>
-  Unfortunately, even after holding back the AspectJ release for 3 months after JDK 21 general availability, waiting for
-  Eclipse JDT Core and the Eclipse Java Compiler (ECJ) to catch up with Java 21 language features, even with Java 21
-  officially supported in Eclipse 2023-12, some preview features are still unimplemented in ECJ:
-</p>
-<ul>
-  <li>Unnamed classes (preview)</li>
-  <li>Unnamed patterns and variables (preview)</li>
-</ul>
-
-<p>
-  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.
-</p>
-
-<h2>Improvements</h2>
-
-<ul>
-  <li>
-    In <a href="https://github.com/eclipse-aspectj/aspectj/issues/266">GitHub issue 266</a>, exception cause reporting
-    has been improved in <tt>ExtensibleURLClassLoader</tt>. Thanks to Andy Russell (@euclio) for his contribution.
-  </li>
-</ul>
-
-<h2>Other changes and bug fixes</h2>
-
-<ul>
-  <li>
-    No major bug fixes
-  </li>
-</ul>
-
-<h2>AspectJ usage hints</h2>
-
-<h3>AspectJ compiler build system requirements</h3>
-
-<p>
-  Since 1.9.21, the AspectJ compiler <tt>ajc</tt> (contained in the <tt>aspectjtools</tt> 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 Core), which AspectJ is a fork of. You can still compile to legacy target versions as low as Java 1.3
-  when compiling plain Java code or using plain Java ITD constructs which do not require the AspectJ runtime
-  <tt>aspectjrt</tt>, but the compiler itself needs JDK 17+. Just like in previous AspectJ versions, both the runtime
-  <tt>aspectjrt</tt> and the load-time weaver <tt>aspectjweaver</tt> still only require JRE 8+.
-</p>
-<p>
-  Please note: If you run <tt>ajc</tt> on JDKs 11-16, you will probably see an error like
-  <tt>java.lang.NoSuchFieldError: RELEASE_17</tt>, and an <tt>ajcore.*.txt</tt> dump file will be created, while running
-  it on even older JDKs will rather yield an <tt>UnsupportedClassVersionError</tt>. See
-  <a href="https://github.com/eclipse-aspectj/aspectj/issues/269">GitHub issue 269</a> for more details.
-</p>
-<p>
-  History: Since 1.9.7, the AspectJ compiler <tt>ajc</tt> needed JDK 11+, before then JDK 8+.
-</p>
-
-<h3>Use LTW on Java 16+</h3>
-
-<p>
-  Please note that if you want to use load-time weaving on Java 16+, the weaving agent collides with
-  <a href="https://openjdk.java.net/jeps/396">JEP 396 (Strongly Encapsulate JDK Internals by Default)</a> and related
-  subsequent JEPs. Therefore, you need to set the JVM parameter <tt>--add-opens java.base/java.lang=ALL-UNNAMED</tt> in
-  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.
-</p>
-
-<h3>Compile with Java preview features</h3>
-
-<p>
-  For features marked as preview on a given JDK, you need to compile with <tt>ajc --enable-preview</tt> and run with
-  <tt>java --enable-preview</tt> on that JDK.
-</p>
-<p>
-  Please note that you cannot run code compiled with preview features on any other JDK than the one used for
-  compilation. For example, records compiled with preview on JDK 15 cannot be used on JDK 16 without recompilation. This
-  is a JVM limitation unrelated to AspectJ. Also, e.g. sealed classes are preview-1 on JDK 15 and preview-2 on JDK 16.
-  You still need to recompile, no matter what.
-</p>
-
-<hr>
-
-<p>
-  <b>Available:</b> 1.9.21 on 11-Dec-2023
-</p>
-
-</body>
-
-</html>
diff --git a/docs/dist/doc/README-197.adoc b/docs/dist/doc/README-197.adoc
index 48c421d36..1f96cd5bb 100644
--- a/docs/dist/doc/README-197.adoc
+++ b/docs/dist/doc/README-197.adoc
@@ -32,7 +32,7 @@ respective final and review 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.
 
-Please note that you cannot run code compiled with preview features on
+Please note, that you cannot run code compiled with preview features on
 any other JDK than the one used for compilation. For example, records
 compiled with preview on JDK 15 cannot be used on JDK 16 without
 recompilation. This is a JVM limitation unrelated to AspectJ. Also, e.g.
diff --git a/docs/dist/doc/README-198.adoc b/docs/dist/doc/README-198.adoc
index c700ee311..29b04ef7c 100644
--- a/docs/dist/doc/README-198.adoc
+++ b/docs/dist/doc/README-198.adoc
@@ -80,7 +80,7 @@ in different classloaders.
 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.
 
-Please note that you cannot run code compiled with preview features on any other JDK than the one used for compilation.
+Please note, that you cannot run code compiled with preview features on any other JDK than the one used for compilation.
 For example, records compiled with preview on JDK 15 cannot be used on JDK 16 without recompilation. This is a JVM
 limitation unrelated to AspectJ. Also, e.g. sealed classes are preview-1 on JDK 15 and preview-2 on JDK 16. You still
 need to recompile, no matter what.
diff --git a/docs/dist/doc/README-199.adoc b/docs/dist/doc/README-199.adoc
index 132f0e082..900f70b89 100644
--- a/docs/dist/doc/README-199.adoc
+++ b/docs/dist/doc/README-199.adoc
@@ -88,7 +88,7 @@ in different classloaders.
 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.
 
-Please note that you cannot run code compiled with preview features on any other JDK than the one used for compilation.
+Please note, that you cannot run code compiled with preview features on any other JDK than the one used for compilation.
 For example, records compiled with preview on JDK 15 cannot be used on JDK 16 without recompilation. This is a JVM
 limitation unrelated to AspectJ. Also, e.g. sealed classes are preview-1 on JDK 15 and preview-2 on JDK 16. You still
 need to recompile, no matter what.
diff --git a/docs/dist/doc/index.adoc b/docs/dist/doc/index.adoc
index 4c905ce2b..c1e4f1e98 100644
--- a/docs/dist/doc/index.adoc
+++ b/docs/dist/doc/index.adoc
@@ -87,8 +87,9 @@ each join point. See also the link:weaver-api/index.html[Weaver API]
 language, tools, and project.
 
 |README's |Changes and porting guide for AspectJ
-xref:README-199.adoc[1.9.9.1],
-xref:README-199.adoc[1.9.9], xref:README-198.adoc[1.9.8],
+xref:README-1921.adoc[1.9.21],
+xref:README-1920.adoc[1.9.20 and 1.9.20.1], xref:README-1919.adoc[1.9.19],
+xref:README-199.adoc[1.9.9 and 1.9.9.1], xref:README-198.adoc[1.9.8],
 xref:README-197.adoc[1.9.7], xref:README-196.adoc[1.9.6],
 xref:README-195.adoc[1.9.5], xref:README-194.adoc[1.9.4],
 xref:README-193.adoc[1.9.3], xref:README-192.adoc[1.9.2],