update for LTW and compatibility - minor updates

1 files changed, 30 insertions, 11 deletions

diff --git a/docs/devGuideDB/ltw.xml b/docs/devGuideDB/ltw.xml
index 29fc4e1a0..b0abbf37a 100644
--- a/docs/devGuideDB/ltw.xml
+++ b/docs/devGuideDB/ltw.xml
@@ -4,7 +4,7 @@
     <sect1 id="ltw-introduction">
         <title>Introduction</title>
         
-        <para> The AspectJ 5 weaver takes class files as input and produces class files as output.
+        <para> The AspectJ weaver takes class files as input and produces class files as output.
             The weaving process itself can take place at one of three different times: compile-time,
             post-compile time, and load-time. The class files produced by the weaving process (and
             hence the run-time behaviour of an application) are the same regardless of the approach
@@ -17,7 +17,8 @@
                 aspects themselves may be in source or binary form. </para></listitem>
             <listitem> <para>Post-compile weaving (also sometimes called binary weaving) is used to weave
                 existing class files and JAR files. As with compile-time weaving,
-                the aspects used for weaving may be in source or binary form. </para></listitem>
+                the aspects used for weaving may be in source or binary form,
+                and may themselves be woven by aspects. </para></listitem>
             <listitem> <para>Load-time weaving (LTW) is simply binary weaving defered until the point that
                 a class loader loads a class file and defines the class to the JVM. To support this,
                 one or more "weaving class loaders", either provided explicitly by the run-time
@@ -53,11 +54,14 @@
     
         <orderedlist>
             <listitem> <para>All aspects to be used for weaving must be defined to the weaver before any
-                types to be woven are loaded.</para></listitem>
-            <listitem> <para>All abstract and concrete aspects visible to the weaver
-                are available for extending (abstract aspects) and using for weaving. 
+                types to be woven are loaded.  This avoids types being "missed" by aspects added
+                later, with the result that invariants across types fail.</para></listitem>
+            <listitem> <para>All aspects visible to the weaver are usable.
                 A visible aspect is one defined by the
-                weaving class loader or one of its parent class loaders.</para></listitem>
+                weaving class loader or one of its parent class loaders.
+                All concrete visible aspects are woven and all abstract visible aspects
+                may be extended.
+            </para></listitem>
             <listitem><para>A class loader may only weave classes that it defines. It may not weave
                 classes loaded by a delegate or parent class loader.</para></listitem>    
         </orderedlist>
@@ -66,15 +70,15 @@
     
     <sect1 id="ltw-configuration">
         <title>Configuration</title>
-        <para>AspectJ 5 supports a number of mechanisms designed to make load-time weaving as
-        easy to use as possibe. The load-time weaving mechanism is chosen through JVM startup options. 
+        <para>New in AspectJ 5 are a number of mechanisms to make load-time weaving
+        easy to use. The load-time weaving mechanism is chosen through JVM startup options. 
         Configuration files determine the set of aspects to be used for weaving and which 
         types will be woven. Additional diagnostic options allow the user to debug the configuration and 
         weaving process. </para>
         
         <sect2 id="enabling-load-time-weaving" xreflabel="enabling-load-time-weaving">
             <title>Enabling Load-time Weaving</title>
-            <para> AspectJ 5 supports several different ways of enabling load-time weaving for
+            <para> AspectJ 5 supports several ways of enabling load-time weaving for
             an application: agents, a command-line launch script, and a set of interfaces for
             integration of AspectJ load-time weaving in custom environments. </para>
             <variablelist>
@@ -93,6 +97,16 @@
                         </para>
                     </listitem>
                 </varlistentry>
+                <varlistentry>
+                    <term>Command-line wrapper script <literal>aj</literal></term>
+                    <listitem>
+                        <para>The <command>aj</command> command runs Java programs in Java 1.4 or
+                        later by setting up <literal>WeavingURLClassLoader</literal> as the 
+                            system class loader.  
+                            For more information, see <xref linkend="aj"/>.
+                        </para>
+                    </listitem>
+                </varlistentry>
                 <!-- FIXME: must be made consistent (aop.xml , CL hierarchy etc) -->
 <!--                <varlistentry>-->
 <!--                    <term>Command line</term>-->
@@ -110,13 +124,18 @@
 <!--                    </listitem>-->
 <!--                </varlistentry>-->
                 <varlistentry>
-                    <term>Custom Integration</term>
+                    <term>Custom class loader</term>
                     <listitem>
                         <para> 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 explicity restrict by class loader which classes can be woven.</para>
+                            user to explicitly restrict by class loader which classes can be woven.
+                            For more information, see <xref linkend="aj"/> and the
+                            API documentation and source for
+                            <literal>WeavingURLClassLoader</literal> and
+                            <literal>WeavingAdapter</literal>.
+                        </para>
                     </listitem>
                 </varlistentry>
             </variablelist>