Add initial set of AsciiDoc files, converted from HTML/XML

Some originals have been deleted already. Others, especially the user
guides, still exist in both formats because they have not been
proof-read and probably lots of links do not function as expected. But I
want to see what the files look like directly on GitHun.

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

1 files changed, 89 insertions, 0 deletions

diff --git a/docs/dist/doc/README-168.adoc b/docs/dist/doc/README-168.adoc
new file mode 100644
index 000000000..eee958509
--- /dev/null
+++ b/docs/dist/doc/README-168.adoc
@@ -0,0 +1,89 @@
+[.small]#© Copyright 2009 Contributors. All rights reserved.#
+
+== AspectJ 1.6.8 Readme
+
+The first sentence in the 1.6.7 readme was 'AspectJ 1.6.7 includes some
+radical internal changes.'
+
+Unfortunately not enough testing was done on 1.6.7 and two nasty issues
+were found that really needed addressing. Fixes for these issues are all
+that is new in 1.6.8.
+
+=== Incorrect treatment of some aop.xml include/exclude patterns
+
+See https://bugs.eclipse.org/bugs/show_bug.cgi?id=298786[Bug 298786]
+
+Basically, if a certain combination of includes and excludes were
+specified in the within section, then the weaver would fail to merge
+them correctly. The conditions for the failure are:
+
+* you need an exclude pattern that the weaver is not optimizing for
+(basically a pattern that could not be matched based upon the typename
+alone, eg. based on whether the type has an annotation)
+* you need two include patterns - one that is being optimized and one
+that is not
+
+These three meet that spec:
+
+``
+
+....
+    <include within="*"/>
+    <include within="@Foo *"/>
+    <exclude within="*Funk*y*"/>
+....
+
+The include="*" can be optimized. The include="@Foo *" is not optimized.
+The exclude="*Funk*y*" is not optimized (this one could be but isn't
+right now as it includes multiple wildcards).
+
+With that configuration any types that the include="*" would have
+accepted are not accepted.
+
+=== Stack overflow problem in ReferenceType.isAssignableFrom()
+
+See https://bugs.eclipse.org/bugs/show_bug.cgi?id=298908[Bug 298908]
+
+This is actually a problem AspectJ has had for a long time, but has
+always proved elusive to recreate. It turns out that it is memory
+related and the more aggressive policy in 1.6.7 causes it to occur much
+more frequently.
+
+The stack trace when this is hit looks like:
+
+``
+
+....
+    ...
+    at org.aspectj.weaver.ReferenceType.isAssignableFrom(ReferenceType.java:393)
+    at org.aspectj.weaver.ReferenceType.isAssignableFrom(ReferenceType.java:427)
+    at org.aspectj.weaver.ReferenceType.isAssignableFrom(ReferenceType.java:393)
+    at org.aspectj.weaver.ReferenceType.isAssignableFrom(ReferenceType.java:427)
+    at org.aspectj.weaver.ReferenceType.isAssignableFrom(ReferenceType.java:393)
+    at org.aspectj.weaver.ReferenceType.isAssignableFrom(ReferenceType.java:427)
+    at org.aspectj.weaver.ReferenceType.isAssignableFrom(ReferenceType.java:393)
+    at org.aspectj.weaver.ReferenceType.isAssignableFrom(ReferenceType.java:427)
+    at org.aspectj.weaver.ReferenceType.isAssignableFrom(ReferenceType.java:393)
+    at org.aspectj.weaver.ReferenceType.isAssignableFrom(ReferenceType.java:427)
+    at org.aspectj.weaver.ReferenceType.isAssignableFrom(ReferenceType.java:393)
+    ...
+....
+
+The weaver has changed over the 1.5 and 1.6 releases and is now reaching
+a point where it really shrinks quite small when not in use (maybe in a
+loadtime environment you have finished loading all your classes). The
+aim is that it can rebuild any required state that is needed later. With
+the move in 1.6.7 from Soft to Weak references, things are being
+discarded much sooner and this is exercising the state rebuilding code
+that wasn't used that often prior to 1.6.7.
+
+The problem is actually because the call on a generic type to get the
+raw type was actually broken and returning the generic type. This then
+loops forever trying to get the raw type from the generic type. This
+happens because the world should store only raw types (which point to
+their generic form) but there was a bug in state rebuilding that instead
+put the generic type directly in the world.
+
+'''''
+
+Thanks to everyone who helped get to the bottom of these problems.