Bug 159854 "Problem Diagnosis Guide" (skeleton)

docs/build.xml

@@ -203,7 +203,7 @@
     </target>
 
     <target name="do-local-dist"
-            depends="init,init-filters,api,faq,devguide,progguide, adk15guide"
+            depends="init,init-filters,api,faq,devguide,progguide, adk15guide, pdguide"
             description="finish products by copying dist files and library sources"
     >
 
@@ -321,6 +321,28 @@
         </delete>
     </target>
 
+    <target name="pdguide" depends="init">
+
+        <copy todir="${docs.src.dir}/pdGuideDB" filtering="off">
+            <fileset dir="${devguide.icons.dir}"
+                     includes="${include.pdguide.icons}"
+            />
+        </copy>
+
+        <antcall target="build-guide">
+            <param name="xml-html-copy"
+                   value="dd_arrow.gif,aspectj-docs.css,ajbrowser-building.gif,ajbrowser-options.gif,${include.pdguide.icons}"
+            />
+            <param name="guide.dir" value="pdGuideDB" />
+            <param name="guide.name" value="pdguide" />
+        </antcall>
+        <delete quiet="on">
+            <fileset dir="${docs.src.dir}/pdGuideDB"
+                     includes="${include.pdguide.icons}"
+            />
+        </delete>
+    </target>
+
     <target name="build-guide"
             depends="init"
             description="build prog or dev guide, using guide.dir and guide.name"

docs/dist/doc/index.html

@@ -25,8 +25,9 @@
        <a href="quick5.pdf">Quick Reference (AspectJ 5)</a>,
        <a href="quick.pdf">Quick Reference (1.2.1)</a>, 
        <a href="adk15notebook/index.html">AspectJ 5 Developer's Notebook</a>,
-       <a href="progguide/index.html">programming</a> and 
-       <a href="devguide/index.html">development</a> guides, 
+       <a href="progguide/index.html">programming</a>, 
+       <a href="devguide/index.html">development</a> and 
+       <a href="pdguide/index.html">problem diagnosis</a> guides, 
        <a href="runtime-api/index.html">API</a> and
        <a href="examples/">example code</a>.
 	   </td></tr>
@@ -111,6 +112,17 @@
      </td>
      </tr>
 
+<tr> <td><a href="pdguide/index.html">Problem Diagnosis Guide</a>
+<br/>
+         
+         (printable <a href="pdguide/printable.html">html</a>)
+     </td>
+     <td>This has a guide to  
+     the various features available such as message and trace to help you both solve problems
+     with you own programs and report bugs to the AspectJ team.
+     </td>
+     </tr>
+
 <tr> <td><a href="runtime-api/index.html">AspectJ API</a>
      </td>
      <td>API documentation for AspectJ runtime classes. <tt>JoinPoint</tt>

docs/pdGuideDB/ajcore.xml

@@ -0,0 +1,15 @@
+<chapter id="ajcore" xreflabel="AspectJ Core">
+    <title>AspectJ Core Files</title>
+    
+    <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
+        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>
+        
+        <para> </para>
+    </sect1>
+</chapter>

docs/pdGuideDB/ltwdump.xml

@@ -0,0 +1,11 @@
+<chapter id="ltwdump" xreflabel="LTW Dump">
+    <title>LTW Dump</title>
+    
+    <sect1 id="ltwdump-introduction">
+        <title>Introduction</title>
+        
+        <para> Occasionally problems may be encountered with classes that have been load-time woven. Symptoms will
+        include incorrect program function or a Java exception such as 
+        <literal>java.lang.VerifyError</literal>.</para>
+    </sect1>
+</chapter>

docs/pdGuideDB/messages.xml

@@ -0,0 +1,10 @@
+<chapter id="messages" xreflabel="Messages">
+    <title>Messages</title>
+    
+    <sect1 id="messages-introduction">
+        <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>
+    </sect1>
+</chapter>

docs/pdGuideDB/pdguide.xml

@@ -0,0 +1,44 @@
+<?xml version="1.0" encoding="ISO-8859-1"?>
+
+<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1//EN"
+                      "../../lib/docbook/docbook-dtd/docbookx.dtd"
+[
+<!ENTITY messages               SYSTEM "messages.xml">
+<!ENTITY trace                  SYSTEM "trace.xml">
+<!ENTITY ajcore                 SYSTEM "ajcore.xml">
+<!ENTITY ltwdump                SYSTEM "ltwdump.xml">
+]>
+
+<book>
+  <bookinfo>
+    <title>The AspectJ<superscript>tm</superscript> Problem Diagnosis Guide</title>
+
+    <authorgroup>
+      <author>
+        <othername>the AspectJ Team</othername>
+      </author>
+    </authorgroup>
+
+      <legalnotice>
+        <para>Copyright (c) 2006 IBM Corporation and others.
+         2006 Contributors.  
+         All rights reserved.
+        </para>
+      </legalnotice>
+
+    <abstract>
+      <para>
+        This guide describes how to gather and interpret information from the AspectJ compiler
+        to when diagnsoing problems in AspectJ programs, configuring the load-time weaving
+        framework or reporting bugs on Bugzilla.
+      </para>
+    </abstract>
+  </bookinfo>
+  
+  &messages;
+  &ajcore;
+  &trace;
+  &ltwdump;
+
+</book>
+

docs/pdGuideDB/trace.xml

@@ -0,0 +1,15 @@
+<chapter id="trace" xreflabel="Trace">
+    <title>Trace</title>
+    
+    <sect1 id="trace-introduction">
+        <title>Introduction</title>
+        
+        <para> The usual approach to opening a report on Bugzilla is to describe the symptoms of the 
+        problem and attach a simple testcase. This allows the AspectJ team to try and reproduce the problem in
+        an attempt to fix it as well as improve the test suite. Unfortunately it may not be possible
+        to produce such a testcase either because your program is too large or is comercially sensitive. Alternatively 
+        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>
+    </sect1>
+</chapter>