Bug 159854 "Problem Diagnosis Guide"

4 files changed, 186 insertions, 4 deletions

diff --git a/docs/pdGuideDB/ajcore.xml b/docs/pdGuideDB/ajcore.xml
index c78ce85e3..d600cb029 100644
--- a/docs/pdGuideDB/ajcore.xml
+++ b/docs/pdGuideDB/ajcore.xml
@@ -4,8 +4,8 @@
     <sect1 id="ajcore-introduction">
         <title>Introduction</title>
         
-        <para> When the compiler terminates abnormally, either because an abort message was
-        issued or an exception was thrown, a AspectJ core file will be produced. You will
+        <para> When the compiler terminates abnormally, either because a particular kind of message was
+        issued or an exception was thrown, an AspectJ core file will be produced. You will
         find it the working directory of the compiler and will have a name that contains
         the date and time that the file was produced 
         e.g. <literal>ajcore.20060810.173655.626.txt</literal>. </para>
diff --git a/docs/pdGuideDB/aspectj-docs.css b/docs/pdGuideDB/aspectj-docs.css
new file mode 100644
index 000000000..98842dfcd
--- /dev/null
+++ b/docs/pdGuideDB/aspectj-docs.css
@@ -0,0 +1,89 @@
+body { 

+  font-family: "Lucida Grande", "Trebuchet MS", sans-serif;

+  line-height: 1.1em;

+ }

+

+h1 {

+  margin-bottom: 3px;

+  padding-bottom: 0px;

+  line-height: 1.1em;

+}

+

+h2 { 

+     font-size: 130%; 

+     font-weight: bold ; 

+     line-height: 16px;

+     color: #FFFFFF;

+     background-color: #0080C0;

+     padding: 5px;

+}

+

+h3 { 

+     font-size: 110%; 

+     font-weight: bold ; 

+     line-height: 14px;

+     color: #FFFFFF;

+     background-color: orange;

+     padding: 5px;

+}

+

+tt { 

+  font-size: 120%;

+  color: #00AAF0;

+ }

+

+tt tt { 

+  font-size: 100%;

+ }

+

+.programlisting {

+  padding-top: 5px; 

+  border: 2px solid #ccc;

+  background: #eee;

+  font-size: 120%;

+  color: #111199;

+

+ }

+

+.term { 

+  color: #111199;

+ }

+

+.variablelist dd { 

+  margin-left: 18px;

+  padding-left: 20px;

+  background: url(dd_arrow.gif) no-repeat 0 2px;

+ }

+

+.toc dt { 

+  font-size: 110%;

+  padding-bottom: 0px;

+  margin-bottom: 5px;

+ }

+

+.toc dl dd dt { 

+  font-size: 100%;

+ }

+

+.toc dt { 

+  font-size: 100%

+  margin-bottom: 0;

+ }

+

+.informaltable table { 

+  margin-left: 5%;

+ }

+

+.informaltable th { 

+  background-color: orange;

+  padding: 1px;

+ }

+

+ul li { 

+  line-height: 1.2em; 

+ }

+

+.keyword { 

+  font-weight: bold;

+  color: purple;

+ }
\ No newline at end of file
diff --git a/docs/pdGuideDB/messages.xml b/docs/pdGuideDB/messages.xml
index 96512d362..d7fcf3ef7 100644
--- a/docs/pdGuideDB/messages.xml
+++ b/docs/pdGuideDB/messages.xml
@@ -5,6 +5,19 @@
         <title>Introduction</title>
         
         <para> By default only warning and error messages are issued by the compiler whether it is
-        being used for source code compilation, weaving, binary weaving or load-time weaving. </para>
+        being used for source code compilation, weaving, binary weaving or load-time weaving. Informational,
+        debug and weaving messages can also be obtained using compiler options or System properties. </para>
+
+        <sect2 id="configuration" xreflabel="configuration">
+            <title>Configuration</title>
+        
+            <para>  </para>
+        </sect2>
+
+        <sect2 id="examples" xreflabel="examples">
+            <title>Examples</title>
+        
+            <para>  </para>
+        </sect2>
     </sect1>
 </chapter>
diff --git a/docs/pdGuideDB/trace.xml b/docs/pdGuideDB/trace.xml
index 49f642444..85d51e97a 100644
--- a/docs/pdGuideDB/trace.xml
+++ b/docs/pdGuideDB/trace.xml
@@ -1,5 +1,5 @@
 <chapter id="trace" xreflabel="Trace">
-    <title>Trace</title>
+    <title>Tracing</title>
     
     <sect1 id="trace-introduction">
         <title>Introduction</title>
@@ -11,5 +11,85 @@
         the problem may relate to your specific environment where AspectJ is being used and will not be
         reproducible by the AspectJ team. In one of these situations you may be asked to produce a
         trace of the compiler when the problem occurs instead. This can then be attached to the bug report. </para>
+
+        <sect2 id="configuration" xreflabel="configuration">
+            <title>Configuration</title>
+        
+            <para> When available (Java 5 or later) AspectJ will use the 
+            <literal>java.util.logging</literal>
+            <ulink url="http://java.sun.com/j2se/1.5.0/docs/guide/logging/index.html">infrastructure</ulink> 
+            that is configured using a logging.properties file. By default only error
+            and fatal events will be logged but less severe warnings as well as fine grained
+            method entry and exit events can be obtained using the appropriate configuration. All
+            compiler messages can also be logged through the infrastructure by setting the
+            <literal>org.aspectj.weaving.messages</literal> System property. </para>
+            
+            <para> If you are using a JDK 1.4 or earlier AspectJ will use a simple built-in trace
+            infrastructure that logs to stderr. This is enabled by setting the 
+            <literal>org.aspectj.weaving.tracing.enabled</literal> System property. You may also override
+            the default behaviour or provide your own trace implementation using the
+            <literal>org.aspectj.weaving.tracing.factory</literal> System property. </para>
+            
+            <para> The table below lists the System properties that can be used to configure tracing. </para>
+            <informaltable>
+                <tgroup cols="2">
+                    <thead>
+                        <row>
+                            <entry>Property</entry>
+                            <entry>Description</entry>
+                        </row>
+                    </thead>
+                    <tbody>
+                        <row>
+                            <entry>
+                                <literal>org.aspectj.tracing.debug</literal>
+                            </entry>
+                            <entry>
+                            	Enable simple debugging of the trace infrastructure itself.
+                            	<para> Default: <literal>false</literal>. </para>
+                            </entry>
+                        </row>
+                        <row>
+                            <entry>
+                                <literal>org.aspectj.tracing.enabled</literal>
+                            </entry>
+                            <entry>
+                            	Enable the built-in AspectJ trace infrastructure.
+                            	<para> Default: <literal>false</literal>. </para>
+                            </entry>
+                        </row>
+                        <row>
+                            <entry>
+                                <literal>org.aspectj.tracing.factory</literal>
+                            </entry>
+                            <entry>
+                            	Select trace infrastructure. Specify the fully qualified class name
+                            	of the <literal>org.aspectj.weaver.tools.TraceFactory</literal> 
+                            	interface to use a custom infrastructure. Specify a value of
+                            	<literal>default</literal> to force AspectJ to use it's
+                            	built-in infrastructure. 
+                            </entry>
+                        </row>
+                        <row>
+                            <entry>
+                                <literal>org.aspectj.tracing.messages</literal>
+                            </entry>
+                            <entry>
+                            	Enable tracing of compiler messages. The kind of messages logged
+                            	is determined by the selected trace infrastructure not the message
+                            	configuration.
+                            	<para> Default: <literal>false</literal>. </para>
+                            </entry>
+                        </row>
+                    </tbody>
+                </tgroup>
+            </informaltable>
+        </sect2>
+
+        <sect2 id="examples" xreflabel="examples">
+            <title>Examples</title>
+        
+            <para>  </para>
+        </sect2>
     </sect1>
 </chapter>