--- modules/docs/devGuideDB/ajc.xml	2006-10-25 11:24:00.000000000 +0200
+++ modules/docs/devGuideDB/ajc.xml-gil	1970-01-01 01:00:00.000000000 +0100
@@ -1,834 +0,0 @@
-<refentry id="ajc-ref" xreflabel="The ajc Command-line Reference">
-	
-  <refnamediv>	
-    <refname>ajc</refname>
-    <refpurpose>compiler and bytecode weaver for the AspectJ and Java languages</refpurpose>
-  </refnamediv>  
-
-  <refsynopsisdiv>
-    <cmdsynopsis>
-       <command>ajc</command>
-      <arg><replaceable>Options</replaceable></arg>
-      <group>
-        <arg><replaceable>file...</replaceable></arg>
-        <arg>@<replaceable>file...</replaceable></arg>
-        <arg>-argfile <replaceable>file...</replaceable></arg>
-      </group>
-    </cmdsynopsis>
-  </refsynopsisdiv>
-  <refsect1 id="ajc" xreflabel="ajc">
-    <title>Description</title>
-
-    <para>The <command>ajc</command> command compiles and weaves AspectJ and 
-      Java source and .class files, producing .class files compliant with any 
-      Java VM (1.1 or later).  It combines compilation and bytecode weaving
-      and supports incremental builds; you can also weave bytecode
-      at run-time using <xref linkend="ltw"/>.
-      </para>
-
-    <para> The arguments after the options specify the source file(s) to compile.
-        To specify source classes, use <parameter>-inpath</parameter> (below).
-        Files may be listed directly on the command line or in a file.
-        The <parameter>-argfile <replaceable>file</replaceable></parameter> 
-        and <parameter>@<replaceable>file</replaceable></parameter> forms
-        are equivalent, and are interpreted as meaning all the arguments 
-        listed in the specified file. 
-    </para>
-
-    <para>	
-        <command>Note:</command> 
-        You must explicitly pass <command>ajc</command> all necessary sources.
-        Be sure to 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 <ulink url="../progguide/implementation.html">The AspectJ
-         Programming Guide, Implementation Appendix</ulink>.)
-    <para>
-    </para>
-        To specify sources, you can list source files as arguments or use the 
-        options <parameter>-sourceroots</parameter> or <parameter>-inpath</parameter>.
-        If there are multiple sources for any type, the result is undefined
-        since ajc has no way to determine which source is correct.  (This 
-        happens most often when users include the destination directory
-        on the inpath and rebuild.)
-    </para>
-
-    <refsect2 id="ajc_options" xreflabel="ajc_options">
-    <title>Options</title>
-
-     <variablelist>
-
-      <varlistentry>
-        <term>-injars <replaceable>JarList</replaceable></term>
-        <listitem><para>
-        deprecated: since 1.2, use -inpath, which also takes
-        directories.
-        </para></listitem>
-      </varlistentry>
-
-      <varlistentry>
-        <term>-inpath <replaceable>Path</replaceable></term>
-        <listitem><para>
-        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.
-        </para></listitem>
-      </varlistentry>
-
-      <varlistentry>
-        <term>-aspectpath <replaceable>Path</replaceable></term>
-        <listitem><para>
-        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.
-        </para></listitem>
-      </varlistentry>
-
-      <varlistentry>
-        <term>-argfile <replaceable>File</replaceable></term>
-        <listitem><para>
-          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 the argument list
-		  for the command.  Relative paths in the file are calculated from
-		  the directory containing the file (not the current working directory).
-		  Comments, as in Java, start with <literal>//</literal> and
-          extend to the end of the line.  Options specified in argument
-          files may override rather than extending existing option values,
-          so avoid specifying options like <replaceable>-classpath</replaceable>
-          in argument files unlike the argument file is the only build
-          specification.  The form <replaceable>@file</replaceable> is the same
-          as specifying <replaceable>-argfile file</replaceable>.
-        </para></listitem>
-      </varlistentry>
-
-      <varlistentry>
-        <term>-outjar <replaceable>output.jar</replaceable></term>
-        <listitem><para>Put output classes in zip file output.jar.
-        </para></listitem>
-      </varlistentry>
-
-      <varlistentry>
-        <term>-outxml</term>
-        <listitem><para>Generate aop.xml file for load-time weaving with default name.
-        </para></listitem>
-      </varlistentry>
-
-      <varlistentry>
-        <term>-outxmlfile <replaceable>custom/aop.xml</replaceable></term>
-        <listitem><para>Generate aop.xml file for load-time weaving with custom name.
-        </para></listitem>
-      </varlistentry>
-
-      <varlistentry>
-        <term>-incremental</term>
-        <listitem><para>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.
-        </para></listitem>
-      </varlistentry>
-
-      <varlistentry>
-        <term>-sourceroots <replaceable>DirPaths</replaceable></term>
-        <listitem><para>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.
-        </para></listitem>
-      </varlistentry>
-
-      <varlistentry>
-        <term>-crossrefs</term>
-        <listitem><para>
-          Generate a build .ajsym file into the output directory.  Used for
-          viewing crosscutting references by tools like the AspectJ
-          Browser.
-        </para></listitem>
-      </varlistentry>
-
-
-      <varlistentry>
-        <term>-emacssym</term>
-        <listitem><para>
-          Generate .ajesym symbol files for emacs support (deprecated).
-        </para></listitem>
-      </varlistentry>
-
-      <varlistentry>
-        <term>-Xlint</term>
-        <listitem><para>Same as -Xlint:warning (enabled by default)
-        </para></listitem>
-      </varlistentry>
-
-      <varlistentry>
-        <term>-Xlint:{level}</term>
-        <listitem><para>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.
-        </para></listitem>
-      </varlistentry>
-
-      <varlistentry>
-        <term>-Xlintfile <replaceable>PropertyFile</replaceable></term>
-        <listitem><para>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.
-        </para></listitem>
-      </varlistentry>
-
-      <varlistentry>
-        <term>-help</term>
-        <listitem><para>
-          Emit information on compiler options and usage
-        </para></listitem>
-      </varlistentry>
-
-      <varlistentry>
-        <term>-version</term>
-        <listitem><para>
-          Emit the version of the AspectJ compiler
-        </para></listitem>
-      </varlistentry>
-
-      <varlistentry>
-        <term>-classpath <replaceable>Path</replaceable></term>
-        <listitem><para>
-          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.
-        </para></listitem>
-      </varlistentry>
-
-      <varlistentry>
-        <term>-bootclasspath <replaceable>Path</replaceable></term>
-        <listitem><para>
-          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.
-        </para></listitem>
-      </varlistentry>
-
-      <varlistentry>
-        <term>-extdirs <replaceable>Path</replaceable></term>
-        <listitem><para>
-          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.
-        </para></listitem>
-      </varlistentry>
-
-      <varlistentry>
-        <term>-d <replaceable>Directory</replaceable></term>
-        <listitem><para>
-          Specify where to place generated .class files.
-          If not specified, <replaceable>Directory</replaceable> 
-          defaults to the current working dir.
-        </para></listitem>
-      </varlistentry>
-
-      <varlistentry>
-        <term>-target <replaceable>[1.1 to 1.5]</replaceable></term>
-        <listitem><para>Specify classfile target setting (1.1 to 1.5, default is 1.2)
-        </para></listitem>
-      </varlistentry>
-
-      <varlistentry>
-        <term>-1.3</term>
-        <listitem><para>Set compliance level to 1.3 
-            This implies -source 1.3 and -target 1.1.
-        </para></listitem>
-      </varlistentry>
-
-      <varlistentry>
-        <term>-1.4</term>
-        <listitem><para>Set compliance level to 1.4 (default)
-            This implies -source 1.4 and -target 1.2.
-        </para></listitem>
-      </varlistentry>
-
-      <varlistentry>
-        <term>-1.5</term>
-        <listitem><para>Set compliance level to 1.5.
-            This implies -source 1.5 and -target 1.5.
-        </para></listitem>
-      </varlistentry>
-
-      <varlistentry>
-        <term>-source <replaceable>[1.3|1.4|1.5]</replaceable></term>
-        <listitem><para>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 <literal>assert</literal> as a keyword and 
-          implement assertions according to the 1.4 language spec.
-          When using -source 1.5,
-            Java 5 language features are permitted. 
-        </para></listitem>
-      </varlistentry>
-
-      <varlistentry>
-        <term>-nowarn</term>
-        <listitem><para>Emit no warnings (equivalent to '-warn:none')
-        This does not suppress messages
-        generated by <literal>declare warning</literal> or
-        <literal>Xlint</literal>.
-        </para></listitem>
-      </varlistentry>
-
-      <varlistentry>
-        <term>-warn: <replaceable>items</replaceable></term>
-        <listitem><para>Emit warnings for any instances of
-        the comma-delimited list of questionable code 
-        (eg '-warn:unusedLocals,deprecation'):
-        <programlisting><!-- unable to embed itemizedlist? -->
-    constructorName        method with constructor name
-    packageDefaultMethod   attempt to override package-default method
-    deprecation            usage of deprecated type or member
-    maskedCatchBlocks      hidden catch block
-    unusedLocals           local variable never read
-    unusedArguments        method argument never read
-    unusedImports          import statement not used by code in file
-    none                   suppress all compiler warnings
-        </programlisting>
-        <literal>-warn:none</literal> does not suppress messages
-        generated by <literal>declare warning</literal> or
-        <literal>Xlint</literal>.
-        
-        </para></listitem>
-      </varlistentry>
-
-      <varlistentry>
-        <term>-deprecation</term>
-        <listitem><para>Same as -warn:deprecation
-        </para></listitem>
-      </varlistentry>
-
-      <varlistentry>
-        <term>-noImportError</term>
-        <listitem><para>Emit no errors for unresolved imports
-        </para></listitem>
-      </varlistentry>
-
-      <varlistentry>
-        <term>-proceedOnError</term>
-        <listitem><para>Keep compiling after error, 
-                        dumping class files with problem methods
-        </para></listitem>
-      </varlistentry>
-
-      <varlistentry>
-        <term>-g<replaceable>:[lines,vars,source]</replaceable></term>
-        <listitem>
-        	<para>debug attributes level, that may take three forms:
-        <programlisting>
-    -g         all debug info ('-g:lines,vars,source')
-    -g:none    no debug info
-    -g:{items} debug info for any/all of [lines, vars, source], e.g.,
-               -g:lines,source
-        </programlisting>
-            
-        </para></listitem>
-      </varlistentry>
-
-      <varlistentry>
-        <term>-preserveAllLocals</term>
-        <listitem><para>Preserve all local variables during code generation
-        (to facilitate debugging).
-        </para></listitem>
-      </varlistentry>
-
-      <varlistentry>
-        <term>-referenceInfo</term>
-        <listitem><para>Compute reference information.
-        </para></listitem>
-      </varlistentry>
-
-      <varlistentry>
-	    <term>-encoding <replaceable>format</replaceable></term>
-        <listitem><para>Specify default source encoding format.
-            Specify custom encoding on a per file basis by suffixing
-			each input source file/folder name with '[encoding]'.
-        </para></listitem>
-      </varlistentry>
-
-      <varlistentry>
-        <term>-verbose</term>
-        <listitem><para>Emit messages about accessed/processed compilation units 
-        </para></listitem>
-      </varlistentry>
-
-      <varlistentry>
-        <term>-showWeaveInfo</term>
-        <listitem><para>Emit messages about weaving 
-        </para></listitem>
-      </varlistentry>
-	  
-      <varlistentry>
-        <term>-log <replaceable>file</replaceable></term>
-        <listitem><para>Specify a log file for compiler messages.
-        </para></listitem>
-      </varlistentry>
-
-      <varlistentry>
-        <term>-progress</term>
-        <listitem><para>Show progress (requires -log mode).
-        </para></listitem>
-      </varlistentry>
-
-      <varlistentry>
-        <term>-time</term>
-        <listitem><para>Display speed information.
-        </para></listitem>
-      </varlistentry>
-
-      <varlistentry>
-        <term>-noExit</term>
-        <listitem><para>Do not call System.exit(n) at end of compilation
-			(n=0 if no error)
-        </para></listitem>
-      </varlistentry>
-
-      <varlistentry>
-        <term>-repeat <replaceable>N</replaceable></term>
-        <listitem><para>Repeat compilation process N times 
-        (typically to do performance analysis).
-        </para></listitem>
-      </varlistentry>
-
-      <varlistentry>
-        <term>-XterminateAfterCompilation</term>
-        <listitem><para>Causes compiler to terminate before weaving
-        </para></listitem>
-      </varlistentry>
-      
-      <varlistentry>
-        <term>-XaddSerialVersionUID</term>
-        <listitem><para>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.
-        </para></listitem>
-      </varlistentry>
-      
-      <varlistentry>
-        <term>-Xreweavable[:compress]</term>
-        <listitem><para>(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.
-        </para></listitem>
-      </varlistentry>
-
-      <varlistentry>
-        <term>-XnoInline</term>
-        <listitem><para>(Experimental) do not inline around advice
-        </para></listitem>
-      </varlistentry>
-
-      <varlistentry>
-        <term>-XincrementalFile <replaceable>file</replaceable></term>
-        <listitem><para>(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.
-        </para></listitem>
-      </varlistentry>
-
-      <varlistentry>
-        <term>-XserializableAspects</term>
-        <listitem><para>
-        (Experimental) Normally it is an error to declare
-        aspects Serializable.  This option removes that restriction.
-        </para></listitem>
-      </varlistentry>
-      <varlistentry>
-        <term>-XnotReweavable</term>
-        <listitem><para>
-    (Experimental) Create class files that can't be subsequently rewoven by AspectJ.
-        </para></listitem>
-      </varlistentry>
-      <!-- not documenting this feature yet -->
-      <!--
-      <varlistentry>
-        <term>-XhasMember</term>
-        <listitem><para>
-            (Experimental) Allow hasmethod() and hasfield type patterns in declare parents and declare @type.
-        </para></listitem>
-      </varlistentry>
-      -->
-      <varlistentry>
-        <term>-Xajruntimelevel:1.2, ajruntimelevel:1.5</term>
-        <listitem><para>
-        (Experimental) Allows code to be generated that targets a 1.2 or a 1.5 level AspectJ runtime (default 1.5)
-         </para></listitem>
-      </varlistentry>
-    </variablelist>
-
-    </refsect2>
-
-    <refsect2> 
-    <title>File names</title>
-
-    <para>ajc accepts source files with either the <filename>.java</filename>
-    extension or the <filename>.aj</filename> extension.  We normally use
-    <filename>.java</filename> for all of our files in an AspectJ system -- files
-    that contain aspects as well as files that contain classes.  However, if
-    you have a need to mechanically distinguish files that use AspectJ's
-    additional functionality from those that are pure Java we recommend using
-    the <filename>.aj</filename> extension for those files.</para>
-
-    <para>We'd like to discourage other means of mechanical distinction such as
-    naming conventions or sub-packages in favor of the <filename>.aj</filename>
-    extension.</para>
-    
-    <itemizedlist>
-
-    <listitem><para>Filename conventions are hard to enforce and lead to awkward names
-    for your aspects.  Instead of <filename>TracingAspect.java</filename> we
-    recommend using <filename>Tracing.aj</filename> (or just
-    <filename>Tracing.java</filename>) instead.</para></listitem>
-
-    <listitem><para>Sub-packages move aspects out of their natural place in a system
-    and can create an artificial need for privileged aspects.  Instead of
-    adding a sub-package like <filename>aspects</filename> we recommend using the
-    <filename>.aj</filename> extension and including these files in your existing
-    packages instead.</para></listitem>
-
-    </itemizedlist>
-
-    </refsect2>
-
-    <refsect2>
-      <title>Compatibility</title>
-
-      <para>
-        AspectJ is a compatible extension to the Java programming language. The
-        AspectJ compiler adheres to the <ulink
-        url="http://java.sun.com/docs/books/jls/index.html"> <citetitle
-        pubwork="book">The Java Language Specfication, Second
-        Edition</citetitle></ulink> and to the <ulink
-        url="http://java.sun.com/docs/books/vmspec/index.html"><citetitle
-        pubwork="book">The Java Virtual Machine Specification, Second
-        Edition</citetitle></ulink> and runs on any Java 2 compatible
-        platform. The code it generates runs on any Java 1.1 or later
-        compatible platform.
-        For more information on compatibility with
-          Java and with previous releases of AspectJ,
-          see
-          <xref linkend="versionCompatibility"/>.
-      </para>
-
-    </refsect2>
-
-    <refsect2>
-      <title>Examples</title>
-
-      <example id="simpleexample">
-        <title>A simple example</title>
-
-        <para>Compile two files:</para>
-
-        <programlisting>
-        ajc HelloWorld.java Trace.java
-        </programlisting>
-
-      </example>
-
-      <example id="exampleusingargfile">
-        <title>An example using -argfile/@</title>
-
-        <para>
-          To avoid specifying file names on the command line, 
-          list source files in a line-delimited text argfile.
-          Source file paths may be absolute or relative to the argfile,
-          and may include other argfiles by @-reference.
-          The following file <literal>sources.lst</literal>
-          contains absolute and relative files and @-references:
-          </para>
-		  <programlisting>
-Gui.java
-/home/user/src/Library.java
-data/Repository.java
-data/Access.java
-@../../common/common.lst
-@/home/user/src/lib.lst
-view/body/ArrayView.java</programlisting>
-
-          <para>Compile the files using either the -argfile or @ form:</para>
-          <programlisting>
-ajc -argfile sources.lst
-ajc @sources.lst</programlisting>
-        <para>
-        Argfiles are also supported by jikes and javac, so you 
-        can use the files in hybrid builds.  However, the support varies:
-        </para>
-	    <itemizedlist>
-            <listitem><para>Only ajc accepts command-line options</para></listitem>
-            <listitem><para>Jikes and Javac do not accept internal @argfile references.
-            </para></listitem>
-            <listitem><para>Jikes and Javac only accept the @file form on the command line.</para></listitem>
-	    </itemizedlist>
-
-      </example>
-      <example id="examplebytecode">
-        <title>An example using -inpath and -aspectpath</title>
-        <para>Bytecode weaving using -inpath:
-          AspectJ 1.2 supports weaving .class files in input zip/jar files 
-          and directories. 
-          Using input jars is like compiling the corresponding 
-          source files, and all binaries are emitted to output.  Although 
-          Java-compliant compilers may differ in their output, ajc should 
-          take as input any class files produced by javac, jikes, eclipse, 
-          and, of course, ajc.  Aspects included in -inpath will be woven into
-          like other .class files, and they will affect other types as usual.
-        </para>
-        <para>Aspect libraries using -aspectpath:
-          AspectJ 1.1 supports weaving from read-only libraries containing 
-          aspects.  Like input jars, they affect all input; unlike input 
-          jars, they themselves are not affected or emitted as output.  
-          Sources compiled with aspect libraries must be run with the same 
-          aspect libraries on their classpath. 
-        </para>
-        <para>The following example builds the tracing example in a 
-        command-line environment; it creates a read-only aspect library, 
-      compiles some classes for use as input bytecode, and 
-       compiles the classes and other sources with the aspect library.
-        </para>
-        <para>The tracing example is in the AspectJ distribution 
-        ({aspectj}/doc/examples/tracing).  This uses the following files:
-        </para>
-        <para><programlisting>
- aspectj1.1/ 
-   bin/ 
-     ajc 
-   lib/ 
-     aspectjrt.jar 
-   examples/ 
-     tracing/ 
-       Circle.java 
-       ExampleMain.java 
-       lib/ 
-         AbstractTrace.java 
-         TraceMyClasses.java 
-       notrace.lst 
-       Square.java 
-       tracelib.lst 
-       tracev3.lst 
-       TwoDShape.java 
-       version3/ 
-         Trace.java 
-         TraceMyClasses.java 
-        </programlisting></para>
-
-<para>Below, the path separator is taken as ";", but file separators 
-are "/".  All commands are on one line.  Adjust paths and 
-commands to your environment as needed. 
-
-</para><para>Setup the path, classpath, and current directory:</para> 
-    
-        <programlisting>
-    cd examples 
-    export ajrt=../lib/aspectjrt.jar 
-    export CLASSPATH="$ajrt" 
-    export PATH="../bin:$PATH" 
-        </programlisting>
-
-<para>Build a read-only tracing library:</para> 
-        <programlisting>
-    ajc -argfile tracing/tracelib.lst -outjar tracelib.jar 
-        </programlisting>
-
-<para>Build the application with tracing in one step:</para> 
-
-        <programlisting>
-    ajc -aspectpath tracelib.jar -argfile tracing/notrace.lst -outjar tracedapp.jar 
-        </programlisting>
-
-<para>Run the application with tracing:</para> 
-
-        <programlisting>
-    java -classpath "$ajrt;tracedapp.jar;tracelib.jar" tracing.ExampleMain 
-        </programlisting>
-
-<para>Build the application with tracing from binaries in two steps:</para> 
-    <itemizedlist><listitem><para>
-(a) Build the application classes (using javac for demonstration's sake):</para> 
-        <programlisting>
-    mkdir classes 
-    javac -d classes tracing/*.java 
-    jar cfM app.jar -C classes . 
-        </programlisting>
-
-    </listitem>
-    <listitem><para>
-(b) Build the application with tracing:</para> 
-        <programlisting>
-    ajc -inpath app.jar -aspectpath tracelib.jar -outjar tracedapp.jar 
-        </programlisting>
-    </listitem></itemizedlist>
-
-<para>Run the application with tracing (same as above):</para> 
-
-        <programlisting>
-    java -classpath "$ajrt;tracedapp.jar;tracelib.jar" tracing.ExampleMain 
-        </programlisting>
-
-<para>Run the application without tracing:</para> 
-
-        <programlisting>
-    java -classpath "app.jar" tracing.ExampleMain
-        </programlisting>
-
-      </example>
-
-    </refsect2>
-
-    <refsect2>
-      <title>The AspectJ compiler API</title>
-
-      <para>The AspectJ compiler is implemented completely in Java and can be
-        called as a Java class.  The only interface that should be considered
-        public are the public methods in <literal>org.aspectj.tools.ajc.Main</literal>.
-        E.g., <literal>main(String[] args)</literal> takes the
-        the standard <command>ajc</command> command line arguments. 
-        This means that an alternative way to run the
-        compiler is </para>
-
-      <cmdsynopsis>
-        <command><literal>java org.aspectj.tools.ajc.Main</literal></command>
-        <arg><replaceable>option...</replaceable></arg>
-        <arg><replaceable>file...</replaceable></arg>
-      </cmdsynopsis>
-      <para>To access compiler messages programmatically, use the methods
-         <literal>setHolder(IMessageHolder holder)</literal> and/or
-         <literal>run(String[] args, IMessageHolder holder)</literal>.
-		  <literal>ajc</literal> reports each message to the holder
-		  using <literal>IMessageHolder.handleMessage(..)</literal>.
-		  If you just want to collect the messages, use
-		  <literal>MessageHandler</literal> as your		  
-		  <literal>IMessageHolder</literal>.
-		  For example, compile and run the following with 
-		  <literal>aspectjtools.jar</literal> on the classpath:
-      </para>
-        <programlisting>
-import org.aspectj.bridge.*;
-import org.aspectj.tools.ajc.Main;
-import java.util.Arrays;
-
-public class WrapAjc {
-  public static void main(String[] args) {
-    Main compiler = new Main();
-    MessageHandler m = new MessageHandler();
-    compiler.run(args, m);
-    IMessage[] ms = m.getMessages(null, true);
-    System.out.println("messages: " + Arrays.asList(ms));
-  }
-}
-        </programlisting>
-    </refsect2>
-
-    <refsect2>
-      <title>Stack Traces and the SourceFile attribute</title>
-
-      <para>Unlike traditional java compilers, the AspectJ compiler may in
-            certain cases generate classfiles from multiple source files.
-            Unfortunately, the original Java class file format does not support 
-            multiple
-            SourceFile attributes.  In order to make sure all source file
-            information is available, the AspectJ compiler may in some cases
-            encode multiple filenames in the SourceFile attribute.  
-            When the Java VM generates stack traces, it uses this attribute
-            to specify the source file.
-      </para>
-      <para>(The AspectJ 1.0 compiler also supports the .class file extensions of JSR-45.
-      These permit compliant debuggers (such as jdb in Java 1.4.1) to identify 
-      the right file and line even given many source files for a single class.
-      JSR-45 support is planned for ajc in AspectJ 1.1, but is not in the initial
-      release.  To get fully debuggable .class files, use the -XnoInline option.)  
-      </para>
-
-      <para>Probably the only time you may see this format is when you view
-            stack traces, where you may encounter traces of the format
-      </para>
-
-<programlisting>
-java.lang.NullPointerException
-  at Main.new$constructor_call37(Main.java;SynchAspect.java[1k]:1030)
-</programlisting>
-
-      <para>where instead of the usual 
-      </para>
-
-<programlisting>
-File:LineNumber
-</programlisting>
-
-      <para>format, you see
-      </para>
-
-<programlisting>
-File0;File1[Number1];File2[Number2] ... :LineNumber
-</programlisting>
-
-      <para>In this case, LineNumber is the usual offset in lines plus the 
-      "start line" of the actual source file.  That means you use LineNumber 
-      both to identify the source file and to find the line at issue. 
-      The number in [brackets] after each file tells you the
-      virtual "start line" for that file (the first file has a start of 0).  
-      </para>
-
-      <para> In our example from the null pointer exception trace, 
-      the virtual start line is 1030.  Since the file SynchAspect.java
-      "starts" at line 1000 [1k], the LineNumber points to line 30 of
-      SynchAspect.java.
-      </para>
-
-      <para> So, when faced with such stack traces, the way to find the actual
-      source location is to look through the list of "start line" numbers to
-      find the one just under the shown line number.  That is the file where
-      the source location can actually be found.  Then, subtract that "start
-      line" from the shown line number to find the actual line number within
-      that file.
-      </para>
-
-      <para>In a class file that comes from only a single source file, the AspectJ
-            compiler generates SourceFile attributes consistent with
-            traditional Java compilers.
-      </para>
-
-    </refsect2>
-
-
-  </refsect1>
-</refentry>