Bug 159854 "Problem Diagnosis Guide" (skeleton)

5 files changed, 95 insertions, 0 deletions

diff --git a/docs/pdGuideDB/ajcore.xml b/docs/pdGuideDB/ajcore.xml
new file mode 100644
index 000000000..c78ce85e3
--- /dev/null
+++ b/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>
diff --git a/docs/pdGuideDB/ltwdump.xml b/docs/pdGuideDB/ltwdump.xml
new file mode 100644
index 000000000..99240965a
--- /dev/null
+++ b/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>
diff --git a/docs/pdGuideDB/messages.xml b/docs/pdGuideDB/messages.xml
new file mode 100644
index 000000000..96512d362
--- /dev/null
+++ b/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>
diff --git a/docs/pdGuideDB/pdguide.xml b/docs/pdGuideDB/pdguide.xml
new file mode 100644
index 000000000..2090cb6cb
--- /dev/null
+++ b/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>
+
diff --git a/docs/pdGuideDB/trace.xml b/docs/pdGuideDB/trace.xml
new file mode 100644
index 000000000..49f642444
--- /dev/null
+++ b/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>