More AsciiDoc improvements, mostly about code formatting (WIP)

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

docs/adk15ProgGuideDB/annotations.adoc

@@ -61,17 +61,13 @@ Annotations can have one of three retention policies:
 
 Source-file retention::
   Annotations with source-file retention are read by the compiler during
-  the compilation process, but are not rendered in the generated
-  `.class` files.
+  the compilation process, but are not rendered in the generated `.class` files.
 Class-file retention::
   This is the default retention policy. Annotations with class-file
-  retention are read by the compiler and also retained in the generated
-  `
-                          .class` files.
+  retention are read by the compiler and also retained in the generated `.class` files.
 Runtime retention::
   Annotations with runtime retention are read by the compiler, retained
-  in the generated `
-                          .class` files, and also made available at
+  in the generated `.class` files, and also made available at
   runtime.
 
 Local variable annotations are not retained in class files (or at
@@ -201,7 +197,6 @@ public aspect AnAspect {
 
   pointcut anInterfaceOperation() : execution(* AnInterface.*(..));
 
-
   @SuppressAjWarnings // may not match if there are no implementers of the interface...
   before() : anInterfaceOperation() {
      // do something...
@@ -229,8 +224,8 @@ etc.), an annotation pattern can be used to match against the set of
 annotations on the annotated element.An annotation pattern element has
 one of two basic forms:
 
-* @<qualified-name>, for example, @Foo, or @org.xyz.Foo.
-* @(<type-pattern>), for example, @(org.xyz..*), or @(Foo || Boo)
+* `@<qualified-name>`, for example, `@Foo`, or `@org.xyz.Foo`.
+* `@(<type-pattern>)`, for example, `@(org.xyz..*)`, or `@(Foo || Boo)`
 
 These simple elements may be negated using `!`, and combined by simple
 concatentation. The pattern `@Foo @Boo` matches an annotated element
@@ -239,21 +234,21 @@ that has both an annotation of type `Foo` and an annotation of type
 
 Some examples of annotation patterns follow:
 
-@Immutable::
+`@Immutable`::
   Matches any annotated element which has an annotation of type
   `Immutable`.
-!@Persistent::
+`!@Persistent`::
   Matches any annotated element which does not have an annotation of
   type `Persistent`.
-@Foo @Goo::
+`@Foo @Goo`::
   Matches any annotated element which has both an annotation of type
   `Foo` and an annotation of type `Goo`.
-@(Foo || Goo)::
+`@(Foo || Goo)`::
   Matches any annotated element which has either an annotation of a type
   matching the type pattern `(Foo || Goo)`. In other words, an annotated
   element with either an annotation of type `Foo` or an annotation of
   type `Goo` (or both). (The parenthesis are required in this example).
-@(org.xyz..*)::
+`@(org.xyz..*)`::
   Matches any annotated element which has either an annotation of a type
   matching the type pattern `(org.xyz..*)`. In other words, an annotated
   element with an annotation that is declared in the org.xyz package or
@@ -299,25 +294,25 @@ OptionalParensTypePattern := AnnotationPattern? TypePattern
 The following examples illustrate the use of annotations in type
 patterns:
 
-(@Immutable *)::
+`(@Immutable *)`::
   Matches any type with an `@Immutable` annotation.
-(!@Immutable *)::
+`(!@Immutable *)`::
   Matches any type which does not have an `@Immutable` annotation.
-(@Immutable (org.xyz.* || org.abc.*))::
+`(@Immutable (org.xyz.* || org.abc.*))`::
   Matches any type in the `org.xyz` or `org.abc` packages with the
   `@Immutable` annotation.
-((@Immutable Foo+) || Goo)::
+`((@Immutable Foo+) || Goo)`::
   Matches a type `Foo` or any of its subtypes, which have the
   `@Immutable` annotation, or a type `Goo`.
-((@(Immutable || NonPersistent) org.xyz..*)::
+`((@(Immutable || NonPersistent) org.xyz..*)`::
   Matches any type in a package beginning with the prefix `org.xyz`,
   which has either the `@Immutable` annotation or the `@NonPersistent`
   annotation.
-(@Immutable @NonPersistent org.xyz..*)::
+`(@Immutable @NonPersistent org.xyz..*)`::
   Matches any type in a package beginning with the prefix `org.xyz`,
   which has both an `@Immutable` annotation and an `@NonPersistent`
   annotation.
-(@(@Inherited *) org.xyz..*)::
+`(@(@Inherited *) org.xyz..*)`::
   Matches any type in a package beginning with the prefix `org.xyz`,
   which has an inheritable annotation. The annotation pattern
   `@(@Inherited *)` matches any annotation of a type matching the type
@@ -352,20 +347,20 @@ SimpleNamePattern := JavaIdentifierChar+ ('*' SimpleNamePattern)?
 If present, the `AnnotationPattern` restricts matches to fields with
 annotations that match the pattern. For example:
 
-@SensitiveData * *::
+`@SensitiveData * *`::
   Matches a field of any type and any name, that has an annotation of
   type `@SensitiveData`
-@SensitiveData List org.xyz..*.*::
+`@SensitiveData List org.xyz..*.*`::
   Matches a member field of a type in a package with prefix `org.xzy`,
   where the field is of type `List`, and has an annotation of type
   `@SensitiveData`
-(@SensitiveData *) org.xyz..*.*::
+`(@SensitiveData *) org.xyz..*.*`::
   Matches a member field of a type in a package with prefix `org.xzy`,
   where the field is of a type which has a `@SensitiveData` annotation.
-@Foo (@Goo *) (@Hoo *).*::
+`@Foo (@Goo *) (@Hoo *).*`::
   Matches a field with an annotation `@Foo`, of a type with an
   annotation `@Goo`, declared in a type with annotation `@Hoo`.
-@Persisted @Classified * *::
+`@Persisted @Classified * *`::
   Matches a field with an annotation `@Persisted` and an annotation
   `@Classified`.
 
@@ -418,37 +413,37 @@ The optional `AnnotationPattern` at the beginning of a method or
 constructor pattern restricts matches to methods/constructors with
 annotations that match the pattern. For example:
 
-@Oneway * *(..)::
+`@Oneway * *(..)`::
   Matches a method with any return type and any name, that has an
   annotation of type `@Oneway`.
-@Transaction * (@Persistent org.xyz..*).*(..)::
+`@Transaction * (@Persistent org.xyz..*).*(..)`::
   Matches a method with the `@Transaction` annotation, declared in a
   type with the `@Persistent` annotation, and in a package beginning
   with the `org.xyz` prefix.
-* *.*(@Immutable *,..)::
+`* *.*(@Immutable *,..)`::
   Matches any method taking at least one parameter, where the parameter
   type has an annotation `@Immutable`.
 
 ==== Example Pointcuts
 
-within(@Secure *)::
+`within(@Secure *)`::
   Matches any join point where the code executing is declared in a type
   with an `@Secure` annotation. The format of the `within` pointcut
   designator in AspectJ 5 is
   `'within' '(' OptionalParensTypePattern ')'`.
-staticinitialization(@Persistent *)::
+`staticinitialization(@Persistent *)`::
   Matches the staticinitialization join point of any type with the
   `@Persistent` annotation. The format of the `staticinitialization`
   pointcut designator in AspectJ 5 is
   `'staticinitialization' '(' OptionalParensTypePattern ')'`.
-call(@Oneway * *(..))::
+`call(@Oneway * *(..))`::
   Matches a call to a method with a `@Oneway` annotation.
-execution(public (@Immutable *) org.xyz..*.*(..))::
+`execution(public (@Immutable *) org.xyz..*.*(..))`::
   The execution of any public method in a package with prefix `org.xyz`,
   where the method returns an immutable result.
-set(@Cachable * *)::
+`set(@Cachable * *)`::
   Matches the set of any cachable field.
-handler(!@Catastrophic *)::
+`handler(!@Catastrophic *)`::
   Matches the handler join point for the handling of any exception that
   is not `Catastrophic`. The format of the `handler` pointcut designator
   in AspectJ 5 is `'handler' '(' OptionalParensTypePattern ')'`.
@@ -501,10 +496,10 @@ name are analogous to their counterparts that take a single type name.
 They match at join points where the object bound to `this` (or `target`,
 respectively) has an annotation of the specified type. For example:
 
-@this(Foo)::
+`@this(Foo)`::
   Matches any join point where the object currently bound to 'this' has
   an annotation of type `Foo`.
-call(* *(..)) && @target(Classified)::
+`call(* *(..)) && @target(Classified)`::
   Matches a call to any object where the target of the call has a
   `@Classified` annotation.
 
@@ -573,10 +568,10 @@ AtWithinCode := '@withincode' '(' AnnotationOrIdentifier ')'
 
 Some examples of using these designators follow:
 
-@within(Foo)::
+`@within(Foo)`::
   Matches any join point where the executing code is defined within a
   type which has an annotation of type `Foo`.
-pointcut insideCriticalMethod(Critical c) : @withincode(c);::
+`pointcut insideCriticalMethod(Critical c) : @withincode(c);`::
   Matches any join point where the executing code is defined in a method
   or constructor which has an annotation of type `@Critical`, and
   exposes the value of the annotation in the parameter `c`.
@@ -777,10 +772,10 @@ specification, it is now possible to match types based on the presence
 of annotations _with either class-file or runtime retention_. For
 example:
 
-declare parents : (@Secured *) implements SecuredObject;::
+`declare parents : (@Secured *) implements SecuredObject;`::
   All types with the `@Secured` annotation implement the `SecuredObject`
   inteface.
-declare parents : (@Secured BankAccount+) implements SecuredObject;::
+`declare parents : (@Secured BankAccount+) implements SecuredObject;`::
   The subset of types drawn from the `BankAccount` type and any subtype
   of `BankAccount`, where the `@Secured` annotation is present,
   implement the `SecuredObject` interface.
@@ -804,7 +799,7 @@ declare precedence : TypePatList;
 AspectJ 5 allows the type patterns in the list to include annotation
 information as part of the pattern specification. For example:
 
-declare precedence : (@Security *),*;::
+`declare precedence : (@Security *),*;`::
   All aspects with the `@Security` annotation take precedence over any
   other aspects in the system. (Or, more informally, all
   security-related aspects take precedence).
@@ -843,18 +838,18 @@ ElementPattern := TypePattern |
 
 The following examples illustrate the use of `declare annotation`.
 
-declare @type : org.xyz.model..* : @BusinessDomain ;::
+`declare @type : org.xyz.model..* : @BusinessDomain ;`::
   All types defined in a package with the prefix `org.xyz.model` have
   the `@BusinessDomain` annotation.
 declare @method : public * BankAccount+.*(..) :
-@Secured(role="supervisor")::
+`@Secured(role="supervisor")`::
   All public methods in `BankAccount` and its subtypes have the
   annotation `@Secured(role="supervisor")`.
 declare @constructor : BankAccount+.new(..) :
-@Secured(role="supervisor")::
+`@Secured(role="supervisor")`::
   All constructors in `BankAccount` and its subtypes have the annotation
   `@Secured(role="supervisor")`.
-declare @field : * DAO+.* : @Persisted;::
+`declare @field : * DAO+.* : @Persisted;`::
   All fields defined in `DAO` or its subtypes have the `@Persisted`
   annotation.
 

docs/adk15ProgGuideDB/covariance.adoc

@@ -52,31 +52,31 @@ B B.whoAreYou()
 
 Following the join point matching rules given in xref:joinpointsignatures.adoc#jpsigs[Join Point Signatures].
 
-call(* whoAreYou())::
+`call(* whoAreYou())`::
   Matches both calls, (since each call join point has at least one
   matching signature).
-call(* A.whoAreYou())::
+`call(* A.whoAreYou())`::
   Matches both calls, (since each call join point has at least one
   matching signature).
-call(A whoAreYou())::
+`call(A whoAreYou())`::
   Matches both calls, (since each call join point has at least one
   matching signature).
-call(A B.whoAreYou())::
+`call(A B.whoAreYou())`::
   Does not match anything - neither of the call join points has a
   signature matched by this pattern. A lint warning is given for the
   call `a.whoAreYou()` ("does not match because declaring type is A, if
   match required use target(B)").
-call(A+ B.whoAreYou())::
+`call(A+ B.whoAreYou())`::
   Matches the call to `b.whoAreYou()` since the signature pattern
   matches the signature `B B.whoAreYou()`. A lint warning is given for
   the call `a.whoAreYou()` ("does not match because declaring type is A,
   if match required use target(B)").
-call(B A.whoAreYou())::
+`call(B A.whoAreYou())`::
   Does not match anything since neither join point has a signature
   matched by this pattern.
-call(B whoAreYou())::
+`call(B whoAreYou())`::
   Matches the call to `b.whoAreYou()` only.
-call(B B.whoAreYou())::
+`call(B B.whoAreYou())`::
   Matches the call to `b.whoAreYou()` only.
 
 The rule for signature matching at call and execution join points is

docs/adk15ProgGuideDB/generics.adoc

@@ -41,18 +41,18 @@ addition to simple type parameter names, type parameter declarations can
 also constrain the set of types allowed by using the `extends` keyword.
 Some examples follow:
 
-class Foo<T> \{...}::
+`class Foo<T> {...}`::
   A class `Foo` with one type parameter, `T`.
-class Foo<T,S> \{...}::
+`class Foo<T,S> {...}`::
   A class `Foo` with two type parameters, `T` and `S`.
-class Foo<T extends Number> \{...}::
+`class Foo<T extends Number> {...}`::
   A class `Foo` with one type parameter `T`, where `T` must be
   instantiated as the type `Number` or a subtype of `Number`.
-class Foo<T, S extends T> \{...}::
+`class Foo<T, S extends T> {...}`::
   A class `Foo` with two type parameters, `T` and `S`. `Foo` must be
   instantiated with a type `S` that is a subtype of the type specified
   for parameter `T`.
-class Foo<T extends Number & Comparable> \{...}::
+`class Foo<T extends Number & Comparable> {...}`::
   A class `Foo` with one type parameter, `T`. `Foo` must be instantiated
   with a type that is a subtype of `Number` and that implements
   `Comparable`.
@@ -91,13 +91,13 @@ stands for "some type". The `extends` and `super` keywords may be used
 in conjunction with the wildcard to provide upper and lower bounds on
 the types that may satisfy the type constraints. For example:
 
-List<?>::
+`List<?>`::
   A list containing elements of some type, the type of the elements in
   the list is unknown.
-List<? extends Number>::
+`List<? extends Number>`::
   A list containing elements of some type that extends Number, the exact
   type of the elements in the list is unknown.
-List<? super Double>::
+`List<? super Double>`::
   A list containing elements of some type that is a super-type of
   Double, the exact type of the elements in the list is unknown.
 
@@ -105,24 +105,24 @@ A generic type may be extended as any other type. Given a generic type
 `Foo<T>` then a subtype `Goo` may be declared in one of the following
 ways:
 
-class Goo extends Foo::
+`class Goo extends Foo`::
   Here `Foo` is used as a raw type, and the appropriate warning messages
   will be issued by the compiler on attempting to invoke methods in
   `Foo`.
-class Goo<E> extends Foo::
+`class Goo<E> extends Foo`::
   `Goo` is a generic type, but the super-type `Foo` is used as a raw
   type and the appropriate warning messages will be issued by the
   compiler on attempting to invoke methods defined by `Foo`.
-class Goo<E> extends Foo<E>::
+`class Goo<E> extends Foo<E>`::
   This is the most usual form. `Goo` is a generic type with one
   parameter that extends the generic type `Foo` with that same
   parameter. So `Goo<String<` is a subclass of `Foo<String>`.
-class Goo<E,F> extends Foo<E>::
+`class Goo<E,F> extends Foo<E>`::
   `Goo` is a generic type with two parameters that extends the generic
   type `Foo` with the first type parameter of `Goo` being used to
   parameterize `Foo`. So `Goo<String,Integer<` is a subclass of
   `Foo<String>`.
-class Goo extends Foo<String>::
+`class Goo extends Foo<String>`::
   `Goo` is a type that extends the parameterized type `Foo<String>`.
 
 A generic type may implement one or more generic interfaces, following
@@ -416,14 +416,14 @@ class C {
 }
 ....
 
-execution(* C.*(List))::
+`execution(* C.*(List))`::
   Matches an execution join point for any of the three methods.
-execution(* C.*(List<? extends Number>))::
+`execution(* C.*(List<? extends Number>))`::
   matches only the execution of `foo`, and _not_ the execution of `goo`
   since `List<? extends Number>` and `List<Double>` are distinct types.
-execution(* C.*(List<?>))::
+`execution(* C.*(List<?>))`::
   matches only the execution of `bar`.
-execution(* C.*(List<? extends Object+>))::
+`execution(* C.*(List<? extends Object+>))`::
   matches both the execution of `foo` and the execution of `bar` since
   the upper bound of `List<?>` is implicitly `Object`.
 
@@ -507,11 +507,11 @@ public class C {
 }
 ....
 
-args(List)::
+`args(List)`::
   will match an execution or call join point for any of these methods
-args(List<String>)::
+`args(List<String>)`::
   will match an execution or call join point for `foo`.
-args(List<Double>)::
+`args(List<Double>)`::
   matches an execution or call join point for `bar`, and _may_ match at
   an execution or call join point for `goo` since it is legitimate to
   pass an object of type `List<Double>` to a method expecting a
@@ -761,17 +761,16 @@ members on generic types. For generic methods, the syntax is exactly as
 for a regular method declaration, with the addition of the target type
 specification:
 
-<T extends Number> T Utils.max(T first, T second) \{...}::
+`<T extends Number> T Utils.max(T first, T second) {...}`::
   Declares a generic instance method `max` on the class `Util`. The
   `max` method takes two arguments, `first` and `second` which must both
   be of the same type (and that type must be Number or a subtype of
   Number) and returns an instance of that type.
-static <E> E Utils.first(List<E> elements) \{...}::
+`static <E> E Utils.first(List<E> elements) {...}`::
   Declares a static generic method `first` on the class `Util`. The
   `first` method takes a list of elements of some type, and returns an
   instance of that type.
-<T> Sorter.new(List<T> elements,Comparator<? super T> comparator)
-\{...}::
+<T> Sorter.new(List<T> elements,Comparator<? super T> comparator) `{...}`::
   Declares a constructor on the class `Sorter`. The constructor takes a
   list of elements of some type, and a comparator that can compare
   instances of the element type.
@@ -783,17 +782,17 @@ match the number of type parameters in the generic type declaration.
 Type parameter _names_ do not have to match. For example, given the
 generic type `Foo<T,S extends Number>` then:
 
-String Foo.getName() \{...}::
+`String Foo.getName() {...}`::
   Declares a `getName` method on behalf of the type `Foo`. It is not
   possible to refer to the type parameters of Foo in such a declaration.
-public R Foo<Q, R>.getMagnitude() \{...}::
+`public R Foo<Q, R>.getMagnitude() {...}`::
   Declares a method `getMagnitude` on the generic class `Foo`. The
   method returns an instance of the type substituted for the second type
   parameter in an invocation of `Foo` If `Foo` is declared as
   `Foo<T,N extends Number> {...}` then this inter-type declaration is
   equivalent to the declaration of a method `public N getMagnitude()`
   within the body of `Foo`.
-R Foo<Q, R extends Number>.getMagnitude() \{...}::
+`R Foo<Q, R extends Number>.getMagnitude() {...}`::
   Results in a compilation error since a bounds specification is not
   allowed in this form of an inter-type declaration (the bounds are
   determined from the declaration of the target type).
@@ -814,7 +813,7 @@ would be well-formed in accordance with Java's sub-typing rules).
 Generic types may also be used as the target type of a `declare parents`
 statement.
 
-declare parents: Foo implements List<String>::
+`declare parents: Foo implements List<String>`::
   The `Foo` type implements the `List<String>` interface. If `Foo`
   already implements some other parameterization of the `List` interface
   (for example, `List<Integer>` then a compilation error will result
@@ -840,25 +839,22 @@ Given the aspect declaration:
 [source, java]
 ....
 public abstract aspect ParentChildRelationship<P,C> {
-    ...
+    // ...
 }
 ....
 
 then
 
-public aspect FilesInFolders extends
-ParentChildRelationship<Folder,File> \{...::
+`public aspect FilesInFolders extends ParentChildRelationship<Folder,File> {...`::
   declares a concrete sub-aspect, `FilesInFolders` which extends the
   parameterized abstract aspect `ParentChildRelationship<Folder,File>`.
-public aspect FilesInFolders extends ParentChildRelationship \{...::
+`public aspect FilesInFolders extends ParentChildRelationship {...`::
   results in a compilation error since the `ParentChildRelationship`
   aspect must be fully parameterized.
-public aspect ThingsInFolders<T> extends
-ParentChildRelationship<Folder,T>::
+`public aspect ThingsInFolders<T> extends ParentChildRelationship<Folder,T>`::
   results in a compilation error since concrete aspects may not have
   type parameters.
-public abstract aspect ThingsInFolders<T> extends
-ParentChildRelationship<Folder,T>::
+`public abstract aspect ThingsInFolders<T> extends ParentChildRelationship<Folder,T>`::
   declares a sub-aspect of `ParentChildRelationship` in which `Folder`
   plays the role of parent (is bound to the type variable `P`).
 

docs/adk15ProgGuideDB/joinpointsignatures.adoc

@@ -10,16 +10,13 @@ annotations, generics, covariance, varargs, and autoboxing.
 === Join Point Matching
 
 AspectJ supports 11 different kinds of join points. These are the
-`method call, method execution, constructor call,
-        constructor execution, field get, field set, pre-initialization,
-        initialization, static initialization, handler,` and
-`advice execution` join points.
+`method call, method execution, constructor call, constructor execution, field get,
+field set, pre-initialization, initialization, static initialization, handler,`
+and `advice execution` join points.
 
 The _kinded_ pointcut designators match based on the kind of a join
-point. These are the `call,
-        execution, get, set, preinitialization, initialization,
-        staticinitialization, handler,` and `adviceexecution`
-designators.
+point. These are the `call, execution, get, set, preinitialization, initialization,
+staticinitialization, handler,` and `adviceexecution` designators.
 
 A kinded pointcut is written using patterns, some of which match based
 on _signature_, and some of which match based on _modifiers_. For
@@ -100,7 +97,7 @@ of the target):
 [source, java]
 ....
 T t = new T();
-t.m("hello");  <= call join point occurs when this line is executed
+t.m("hello");  // <= call join point occurs when this line is executed
 ....
 
 Then the signature `R(T) T.m(parameter_types)` is a signature of the

docs/adk15ProgGuideDB/varargs.adoc

@@ -82,13 +82,13 @@ Method and constructor patterns are used in the `call`, `execution`,
 `initialization`, `preinitialization`, and `withincode` pointcut
 designators. Some examples of usage follow:
 
-call(* org.xyz.*.*(int, String...))::
+`call(* org.xyz.*.*(int, String...))`::
   Matches a call join point for a call to a method defined in the
   `org.xyz` package, taking an `int` and a `String vararg`.
-execution(* org.xyz.*.*(Integer...))::
+`execution(* org.xyz.*.*(Integer...))`::
   Matches an execution join point for the execution of a method defined
   in the `org.xyz` package, taking an `Integer vararg`.
-initialization(org.xyz.*.new((Foo || Goo)...))::
+`initialization(org.xyz.*.new((Foo || Goo)...))`::
   Matches the initialization join point for the construction of an
   object in the `org.xyz` package via a constructor taking either a
   variable number of `Foo` parameters or a variable number of `Goo`

docs/devGuideDB/ajc.adoc

@@ -40,22 +40,22 @@ destination directory on the inpath and rebuild.)
 [[ajc_options]]
 ==== Options
 
--injars <JarList>::
+`-injars <JarList>`::
   deprecated: since 1.2, use -inpath, which also takes directories.
--inpath <Path>::
+`-inpath <Path>`::
   Accept as source bytecode any .class files in the .jar files or
   directories on Path. The output will include these classes, possibly
   as woven with any applicable aspects. Path is a single argument
   containing a list of paths to zip files or directories, delimited by
   the platform-specific path delimiter.
--aspectpath <Path>::
+`-aspectpath <Path>`::
   Weave binary aspects from jar files and directories on path into all
   sources. The aspects should have been output by the same version of
   the compiler. When running the output classes, the run classpath
   should contain all aspectpath entries. Path, like classpath, is a
   single argument containing a list of paths to jar files, delimited by
   the platform- specific classpath delimiter.
--argfile <File>::
+`-argfile <File>`::
   The file contains a line-delimited list of arguments. Each line in the
   file should contain one option, filename, or argument string (e.g., a
   classpath or inpath). Arguments read from the file are inserted into
@@ -67,82 +67,82 @@ destination directory on the inpath and rebuild.)
   specifying options like <-classpath> in argument files unlike the
   argument file is the only build specification. The form <@file> is the
   same as specifying <-argfile file>.
--outjar <output.jar>::
+`-outjar <output.jar>`::
   Put output classes in zip file output.jar.
--outxml::
+`-outxml`::
   Generate aop.xml file for load-time weaving with default name.
--outxmlfile <custom/aop.xml>::
+`-outxmlfile <custom/aop.xml>`::
   Generate aop.xml file for load-time weaving with custom name.
--incremental::
+`-incremental`::
   Run the compiler continuously. After the initial compilation, the
   compiler will wait to recompile until it reads a newline from the
   standard input, and will quit when it reads a 'q'. It will only
   recompile necessary components, so a recompile should be much faster
   than doing a second compile. This requires -sourceroots.
--sourceroots <DirPaths>::
+`-sourceroots <DirPaths>`::
   Find and build all .java or .aj source files under any directory
   listed in DirPaths. DirPaths, like classpath, is a single argument
   containing a list of paths to directories, delimited by the platform-
   specific classpath delimiter. Required by -incremental.
--crossrefs::
+`-crossrefs`::
   Generate a build .ajsym file into the output directory. Used for
   viewing crosscutting references by tools like the AspectJ Browser.
--emacssym::
+`-emacssym`::
   Generate .ajesym symbol files for emacs support (deprecated).
--Xlint::
+`-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
   aspectjtools.jar, but does not override levels set using the
   -Xlintfile option.
--Xlintfile <PropertyFile>::
+`-Xlintfile <PropertyFile>`::
   Specify properties file to set levels for specific crosscutting
   messages. PropertyFile is a path to a Java .properties file that takes
   the same property names and values as
   org/aspectj/weaver/XlintDefault.properties from aspectjtools.jar,
   which it also overrides.
--help::
+`-help`::
   Emit information on compiler options and usage
--version::
+`-version`::
   Emit the version of the AspectJ compiler
--classpath <Path>::
+`-classpath <Path>`::
   Specify where to find user class files. Path is a single argument
   containing a list of paths to zip files or directories, delimited by
   the platform-specific path delimiter.
--bootclasspath <Path>::
+`-bootclasspath <Path>`::
   Override location of VM's bootclasspath for purposes of evaluating
   types when compiling. Path is a single argument containing a list of
   paths to zip files or directories, delimited by the platform-specific
   path delimiter.
--extdirs <Path>::
+`-extdirs <Path>`::
   Override location of VM's extension directories for purposes of
   evaluating types when compiling. Path is a single argument containing
   a list of paths to directories, delimited by the platform-specific
   path delimiter.
--d <Directory>::
+`-d <Directory>`::
   Specify where to place generated .class files. If not specified,
   <Directory> defaults to the current working dir.
--target <[1.1 to 1.5]>::
+`-target <[1.1 to 1.5]>`::
   Specify classfile target setting (1.1 to 1.5, default is 1.2)
--1.3::
+`-1.3`::
   Set compliance level to 1.3 This implies -source 1.3 and -target 1.1.
--1.4::
+`-1.4`::
   Set compliance level to 1.4 (default) This implies -source 1.4 and
   -target 1.2.
--1.5::
+`-1.5`::
   Set compliance level to 1.5. This implies -source 1.5 and -target 1.5.
--source <[1.3|1.4|1.5]>::
+`-source <[1.3|1.4|1.5]>`::
   Toggle assertions (1.3, 1.4, or 1.5 - default is 1.4). When using
   -source 1.3, an assert() statement valid under Java 1.4 will result in
   a compiler error. When using -source 1.4, treat `assert` as a keyword
   and implement assertions according to the 1.4 language spec. When
   using -source 1.5, Java 5 language features are permitted.
--nowarn::
+`-nowarn`::
   Emit no warnings (equivalent to '-warn:none') This does not suppress
   messages generated by `declare warning` or `Xlint`.
--warn: <items>::
+`-warn: <items>`::
   Emit warnings for any instances of the comma-delimited list of
   questionable code (eg '-warn:unusedLocals,deprecation'):
 +
@@ -160,13 +160,13 @@ none                   suppress all compiler warnings
 +
 `-warn:none` does not suppress messages generated by `declare warning`
   or `Xlint`.
--deprecation::
+`-deprecation`::
   Same as -warn:deprecation
--noImportError::
+`-noImportError`::
   Emit no errors for unresolved imports
--proceedOnError::
+`-proceedOnError`::
   Keep compiling after error, dumping class files with problem methods
--g<:[lines,vars,source]>::
+`-g<:[lines,vars,source]>`::
   debug attributes level, that may take three forms:
 +
 [source, text]
@@ -176,54 +176,54 @@ none                   suppress all compiler warnings
 -g:{items} debug info for any/all of [lines, vars, source], e.g.,
            -g:lines,source
 ....
--preserveAllLocals::
+`-preserveAllLocals`::
   Preserve all local variables during code generation (to facilitate
   debugging).
--referenceInfo::
+`-referenceInfo`::
   Compute reference information.
--encoding <format>::
+`-encoding <format>`::
   Specify default source encoding format. Specify custom encoding on a
   per file basis by suffixing each input source file/folder name with
   '[encoding]'.
--verbose::
+`-verbose`::
   Emit messages about accessed/processed compilation units
--showWeaveInfo::
+`-showWeaveInfo`::
   Emit messages about weaving
--log <file>::
+`-log <file>`::
   Specify a log file for compiler messages.
--progress::
+`-progress`::
   Show progress (requires -log mode).
--time::
+`-time`::
   Display speed information.
--noExit::
+`-noExit`::
   Do not call System.exit(n) at end of compilation (n=0 if no error)
--repeat <N>::
+`-repeat <N>`::
   Repeat compilation process N times (typically to do performance
   analysis).
--XterminateAfterCompilation::
+`-XterminateAfterCompilation`::
   Causes compiler to terminate before weaving
--XaddSerialVersionUID::
+`-XaddSerialVersionUID`::
   Causes the compiler to calculate and add the SerialVersionUID field to
   any type implementing Serializable that is affected by an aspect. The
   field is calculated based on the class before weaving has taken place.
--Xreweavable[:compress]::
+`-Xreweavable[:compress]`::
   (Experimental - deprecated as now default) Runs weaver in reweavable
   mode which causes it to create woven classes that can be rewoven,
   subject to the restriction that on attempting a reweave all the types
   that advised the woven type must be accessible.
--XnoInline::
+`-XnoInline`::
   (Experimental) do not inline around advice
--XincrementalFile <file>::
+`-XincrementalFile <file>`::
   (Experimental) This works like incremental mode, but using a file
   rather than standard input to control the compiler. It will recompile
   each time file is changed and and halt when file is deleted.
--XserializableAspects::
+`-XserializableAspects`::
   (Experimental) Normally it is an error to declare aspects
   Serializable. This option removes that restriction.
--XnotReweavable::
+`-XnotReweavable`::
   (Experimental) Create class files that can't be subsequently rewoven
   by AspectJ.
--Xajruntimelevel:1.2, ajruntimelevel:1.5::
+`-Xajruntimelevel:1.2, ajruntimelevel:1.5`::
   (Experimental) Allows code to be generated that targets a 1.2 or a 1.5
   level AspectJ runtime (default 1.5)
 

docs/devGuideDB/ltw.adoc

@@ -83,35 +83,37 @@ interfaces for integration of AspectJ load-time weaving in custom
 environments.
 
 Agents::
-  AspectJ 5 ships with a load-time weaving agent that enables load-time
-  weaving. This agent and its configuration is execution environment
-  dependent. Configuration for the supported environments is discussed
-  later in this chapter.
-  +
-  Using Java 5 JVMTI you can specify the
-  `-javaagent:pathto/aspectjweaver.jar` option to the JVM.
-  +
-  Since AspectJ 1.9.7, the obsolete Oracle/BEA JRockit agent is no
-  longer part of AspectJ. JRockit JDK never supported Java versions
-  higher than 1.6. Several JRockit JVM features are now part of HotSpot
-  and tools like Mission Control available for OpenJDK and Oracle JDK.
+AspectJ 5 ships with a load-time weaving agent that enables load-time
+weaving. This agent and its configuration is execution environment
+dependent. Configuration for the supported environments is discussed
+later in this chapter.
++
+Using Java 5 JVMTI you can specify the
+`-javaagent:pathto/aspectjweaver.jar` option to the JVM.
++
+Since AspectJ 1.9.7, the obsolete Oracle/BEA JRockit agent is no
+longer part of AspectJ. JRockit JDK never supported Java versions
+higher than 1.6. Several JRockit JVM features are now part of HotSpot
+and tools like Mission Control available for OpenJDK and Oracle JDK.
+
 Command-line wrapper scripts `aj`::
-  The `aj` command runs Java programs in Java 1.4 or later by setting up
-  `WeavingURLClassLoader` as the system class loader. For more
-  information, see xref:#aj[`aj`, the AspectJ load-time weaving launcher].
-  +
-  The `aj5` command runs Java programs in Java 5 by using the
-  `-javaagent:pathto/aspectjweaver.jar` option described above. For more
-  information, see xref:#aj[`aj`, the AspectJ load-time weaving launcher].
+The `aj` command runs Java programs in Java 1.4 or later by setting up
+`WeavingURLClassLoader` as the system class loader. For more
+information, see xref:#aj[`aj`, the AspectJ load-time weaving launcher].
++
+The `aj5` command runs Java programs in Java 5 by using the
+`-javaagent:pathto/aspectjweaver.jar` option described above. For more
+information, see xref:#aj[`aj`, the AspectJ load-time weaving launcher].
+
 Custom class loader::
-  A public interface is provided to allow a user written class loader to
-  instantiate a weaver and weave classes after loading and before
-  defining them in the JVM. This enables load-time weaving to be
-  supported in environments where no weaving agent is available. It also
-  allows the user to explicitly restrict by class loader which classes
-  can be woven. For more information, see xref:#aj[`aj`, the AspectJ load-time weaving launcher] and the API
-  documentation and source for `WeavingURLClassLoader` and
-  `WeavingAdapter`.
+A public interface is provided to allow a user written class loader to
+instantiate a weaver and weave classes after loading and before
+defining them in the JVM. This enables load-time weaving to be
+supported in environments where no weaving agent is available. It also
+allows the user to explicitly restrict by class loader which classes
+can be woven. For more information, see xref:#aj[`aj`, the AspectJ load-time weaving launcher] and the API
+documentation and source for `WeavingURLClassLoader` and
+`WeavingAdapter`.
 
 [[configuring-load-time-weaving-with-aopxml-files]]
 ==== Configuring Load-time Weaving with aop.xml files