Rename '*GuideDB' directories to their actual HTML site target names

Signed-off-by: Alexander Kriegisch <Alexander@Kriegisch.name>

1 files changed, 246 insertions, 0 deletions

diff --git a/docs/devguide/ajdee.adoc b/docs/devguide/ajdee.adoc
new file mode 100644
index 000000000..ca6df3d66
--- /dev/null
+++ b/docs/devguide/ajdee.adoc
@@ -0,0 +1,246 @@
+AJDEE
+
+JDEE support for XEmacs and GNU Emacs
+
+== AJDE for Emacs User's Guide
+
+This guide describes AspectJ-mode extensions of JDEE for GNU Emacs and
+XEmacs, which provides enhanced editing and management of AspectJ code
+via a minor mode extension of JDE mode. AJDEE's AspectJ support builds
+on xref:#aspectj-mode[aspectj-mode's] extension of java-mode, also
+provided with the release. Included in this document are guidance for
+AJDEE's xref:#ajdee-featuresandusage[use], including an
+xref:#exploringspacewar[exploration of spacewar], and
+xref:#ajdee-installationetc[installation and compatibility]. See the
+README file in AJDEE's distribution directory for release-specific
+details.
+
+In addition to the java-mode extensions provided by
+xref:#aspectj-mode[aspectj-mode], AJDEE provides (see graphic):
+
+* Viewing and navigation of aspect structures via the the speedbar and
+Classes menu.
+* Basic support for completion.
+* Integrated Javadoc support.
+
+image:ajdee.gif[image]
+
+[[ajdee-featuresandusage]]
+== AJDEE Features and Usage
+
+The AJDEE extensions of JDE require no special effort to use. The
+speedbar and Classes menus provide additional sublists showing
+crosscutting structure. Selecting items in those lists navigates to the
+referenced item.
+
+=== Aspect Structure and Navigation
+
+==== Enhancements to Speedbar in JDE Mode
+
+As a minor mode of JDE mode, AJDEE enhances the speedbar to show the
+location of aspect, advice, and inter-type declarations. The
+affects/affected-by relationships are shown in the speedbar rather than
+embedding tags in the text (available as an option), and selecting the
+items in the speedbar will perform the expected navigation. The speedbar
+symbols have been extended for AspectJ as follows (see right side of
+xref:#ajdeemacsscreenshot[figure)]:
+
+.Enhancements to Speedbar in JDE Mode
+[cols=",",options="header",]
+|===
+|Indication |Meaning
+|`(+) ` _`name`_ |A class, interface, or aspect; double mouse-1 will
+display its declarations
+|`+  ` _`methodSignature`_ |Method has an advice that applies to it;
+double mouse-1 will display the relevant advice.
+|`+  ` _`adviceSignature`_ |Advice declared by the containing aspect;
+double mouse-1 will display affected methods.
+|`+  ` _`introductionSig`_ |Inter-type declaration declared by the
+containing class; double mouse-1 will display affected methods or
+classes.
+|`| | ` _`methodOrFieldSig`_ |Method or field has been declared by an
+aspect; double mouse-1 on text will navigate to the declaration; a +
+within the bars means that it has an advice that applies to it.
+|===
+
+A minus (`-`) is displayed on the item when the crosscutting items are
+displayed. AspectJ structure information is derived from the last
+compile of your AspectJ program.
+
+=== Compilation and JavaDoc
+
+The option `AspectJ Compile File Specification` can be customized from
+the Customize options under the AspectJ menu, changing the default
+compile specification given to `ajc`. See
+xref:#ajdee-installationetc[installation instructions] for examples and
+other customizations.
+
+AspectJ JavaDoc support is enabled by setting `Jde Javadoc Command Path`
+to invoke `ajdoc`. These are the default settings provided in the
+installation instructions.
+
+[[exploringspacewar]]
+== Exploring the Spacewar Source Code
+
+To begin exploring Spacewar within emacs using JDE and AspectJ mode:
+
+* Compile spacewar.
+* Change into the `spacewar` directory.
+* Type `emacs Ship.java`.
+* Pull down the JDE menu and select the Speedbar entry to show the
+AspectJ files in the directory. Note that `Ship.java` is shown in red to
+denote that it is currently shown in the main buffer.
+* Double-click with the left mouse button on the `+` in front of the
+`Ship.java` entry. It should display an entry for the class `Ship`.
+* Double-clicking on Ship will navigate to its declaration in the
+buffer. Note that declarations of advice are annotated to note the types
+of objects that they advise, declarations of methods that are advised
+are annotated with the aspects that advise them, and so forth.
+* Double-clicking on the `+` in front of either will show the declared
+fields, methods, inter-type declarations, and advice. A `+` in front of
+any field or method means that it is introduced or advised;
+double-clicking will list entries for the introducers/advisers;
+double-clicking on them will navigate to their declarations. A `+` in
+front of any inter-type declarations or advice will will display its
+targets.
+
+[[ajdee-installationetc]]
+== Installation and Compatibility
+
+AJDEE requires the installation of http://sunsite.auc.dk/jde[JDE
+2.2.9beta4] or higher and small edits to your `.emacs` file to configure
+AJDEE and enable autoloading AJDEE when a `.java` file is loaded.
+
+=== Installation for enhancement of JDE mode
+
+The first and last steps, with enhancements, can be found in the example
+Emacs initialization file `sample.emacs` and the sample JDE project file
+`sample.prj` in the distribution. The latter also demonstrates a way to
+enable AspectJ mode on a per-project basis.
+
+[arabic]
+. Make sure AJDEE, aspectj-mode, JDE, and supporting packages are on
+your `load-path` and are ``required''. This is an example for the 1.0
+release:
++
+[source, text]
+....
+   ;; I keep my emacs packages in C:/Emacs
+   (setq load-path
+   (append
+'(
+ "C:/Emacs/aspectj-emacsMode-1.0"   ; for AJDEE
+ "C:/Emacs/aspectj-emacsAJDEE-1.0"
+ "C:/Emacs/jde-2.2.9beta6/lisp"
+ "C:/Emacs/elib-1.0"            ; for JDEE
+ "C:/Emacs/speedbar-0.14beta2"  ; for JDEE
+ "C:/Emacs/semantic-1.4beta12"  ; for JDEE/speedbar
+ "C:/Emacs/eieio-0.17beta3"     ; for JDEE
+ )
+load-path))
+
+   (require 'jde)
+   (require 'ajdee) ; can also appear in prj.el
+....
+. _[Optional]_ add `-emacssym` switch to the `ajc` and `ajc.bat` files
+in your AspectJ tools installations (in the `/bin` directory). If you
+invoke the compiler outside Emacs, this will ensure that your compiles
+always generate information for annotations and the jump menu in the
+form of `.ajesym` files.
+. Customize AJDEE's compile options by putting a version of the
+following in your `.emacs` file or in a JDE project file `prj.el` in
+your project's hierarchy (see the `JDE Project File Name` option for the
+latter). Here is a simple example:
++
+[source, text]
+....
+;; A default version for simple projects, maybe good for
+;;; .emacs file.
+(custom-set-variables
+'(jde-compiler '("ajc" "ajc"))
+'(jde-javadoc-command-path "ajdoc")
+
+;; ajc requires all files to be named for a compile
+'(aspectj-compile-file-specification "*.java"))
+....
++
+Here is an example for spacewar, in `examples/spacewar`.
++
+[source, text]
+....
+;;; These options are for the spacewar, in examples/spacewar.
+(custom-set-variables
+'(jde-compiler '("ajc" "ajc"))
+'(jde-javadoc-command-path "ajdoc")
+
+;; ajc provides an ``argfile'' mechanism for specifying all files.
+'(aspectj-compile-file-specification "-argfile demo.lst")
+
+;; *if* compiling packages, name root dir for package hierarchy
+;; to tell ajc where .class files should go.
+'(jde-compile-option-directory "..")
+'(jde-run-working-directory ".."))
+'(jde-run-application-class "spacewar.Game")
+....
+. _[XEmacs only]_ If you're installing JDE yourself, be sure to closely
+follow the JDE installation directions for XEmacs, otherwise you may get
+out of date JDE `.jar` files.
+
+=== Customizing Options
+
+Selecting Customize options from the AspectJ menu displays a number of
+options that customize AspectJ mode. These control whether annotations
+are shown by default, and whether the bovinator set up by JDE runs.
+`AspectJ Compile File Specification`, specifies a compilation argument
+as an alternative to the current buffer's file or the run class's file.
+Example customizations are shown above and in the sample files discussed
+above.
+
+== Usage and Upgrade Problems
+
+Please see the documentation for
+
+aspectj-mode
+
+for problems not specific to AJDEE's features.
+
+* _Symptom_: Get standard speedbar menus in JDE; no annotations display.
+Message:
++
+[source, text]
+....
+AspectJ Mode Warning: Can't find declarations file for...
+....
++
+AspectJ file has not been compiled with ajc and the `-emacssym` flag, or
+was compiled with an obsolete version of ajc. After compilation, there
+should be a <file>.ajesym for every <file>.java in the build. If .ajsym
+files are present but error persists, recompile. Note that aspectj-mode
+for JDE has a fallback view for uncompiled files.
+* _Symptom_: Navigations via the speedbar and the jump menu are off,
+annotations are misplaced in the code.
++
+AspectJ mode operates by querying data derived from the most recent
+compile that includes the `-emacssym` flag. Recompile the entire program
+with ajc including the switch. Consider permanently installing the
+switch by editing the ajc and ajc.bat files in the /bin file in your
+distribution.
+* _Symptom_: Java files that are part of a Java project not written in
+AspectJ come up in aspectj-mode.
++
+Emacs uses the file suffix (.java) to determine which mode to invoke.
+You can either globally toggle the AspectJ features from the AspectJ
+menu, or you can prevent AJDEE from coming up by moving the (require
+'ajdee) expression from your .emacs file to a prj.el file in each
+AspectJ project's directory (see sample.prj in the distribution).
+* _Symptom_: Reported bug fixes and new features to AJDEE are not seen,
+or ajdee.el cannot be found or loaded, with message:
++
+[source, text]
+....
+Error in init file: File error: "Cannot open load file", "ajdee"
+....
++
+Your load-path variable (set in your .emacs) is referring to an old
+release. Change your load-path to point at the directory for the current
+release. See the sample.emacs files in the distribution, for example.