org.aspectj/docs/readme-docs-module.adoc

= AspectJ docs

== Contents and build

This module contains the sources for the documentation delivered with
the AspectJ distribution and for various internal, teaching, and online
works:

* `devguide`: AsciiDoc sources for the AspectJ Development Environment Guide
* `progguide`: AsciiDoc sources for the AspectJ Programming Language Guide
* `faq`: AsciiDoc sources for the AspectJ Frequently Asked Questions
* `sandbox`: a collection of sample AspectJ programs, tools built on the
  AspectJ API's, script snippets, and instructional trails, all intended
  to serve as sources for documentation. See xref:sandbox/readme-sandbox.adoc[].
* `teaching`: Teaching materials, esp. for the AspectJ tutorials.
* `quickref/quick.doc`: The Microsoft Word source file for the .pdf Quick Reference
  guides `quickref/quick.pdf` and `quickref/quickA4.pdf`.
* `build.xml`: Ant build script for the doc distribution
* `developer`: Docs for AspectJ developers

*Build*: `build.xml` assembles a local distribution which is gathered
into the product distribution by the master build script,
`../build/build.xml`. Dependencies outside this directory:

* `.xml` files refer to their docbook dtds using relative path, for the
  moment `../../lib/docbook/...`
* When building docbook, uses `../lib/saxon` libraries.
* When building installer, using `../lib/build/build.jar` and the
  `../build/installer-resources`.
* `quickref/quick.pdf` is generated manually from `quickref/quick.doc`.
* `../org.aspectj.lib` provides library sources for
  `{AspectJ}/doc/aspectjlib`.

When editing the build script and XML files, try to make only
substantive changes rather than reformatting, which produces illusory
changes. If you do reformat, do so programmatically (e.g., using
XMLBuddy plugin reformat command, with long lines wrapped and 80
character lines).

== Docbook notes

#*TODO:* Remove this section after AsciiDoc conversion is complete#

Documentation is written in docbook XML form, which is transformed to
HTML (single-page and multi-page forms) and, potentially, PDF.
Unfortunately, this means you need to use the tags which are not only
legal, but which work when transformed into all output formats, even if
it means working around bugs in the transform scripts. Following are
some notes on traps to avoid.

=== Authoring support

XMLBuddy has a free eclipse plugin that displays errors using problem
items and gutter annotations, but it gets confused by entity references.
So for devguide.xml, create a new file foo.xml and do a manual merge,
correct the files, and then scatter again (leo?).

=== PDF transformation

The transformation from docbook XML to formatting-objects (.fo)
to pdf is fairly weak. If you run the build.xml `test-pdf` task,
you'll see a number of debug messages, which unfortunately give no
clue as to the location of the problem.  Problems noted in the output
(where DE == docbook element)

* tables broken.
** DE `table` unsupported
** DE `informaltable` autolayout is not supported
* lineation/justification broken
* need things like page header/footer titles, page number, copyright
* Valid docbook elements not supported:
** superscript in title
* ...

Sample debug messages:

- `area contents overflows area in line`
- `table-layout=auto is not supported, using fixed!`
- `The element 'fo:table-and-caption' is not yet implemented.`
   (So use docbook element (DE) `informaltable`, not DE `table`.)
- `No spaces to justify text in line` many times

== Older notes

=== Misc info for writing and building docbook

* link tag linkend attribute takes an id
** xsl converts as needed during output
** do NOT use `ulink`; this will be converted to `""`
   (but see param `citerefentry-link`: might enable this)

* to use sensible names for the files produced,
** use an xsl wrapper to add/modify features
** set flag to use the id of the top-level element in the output
   file as the filename. +
   `xsl:param name="use.id.as.filename" select="1"`
** fyi, other related parameters: `html-ext`, `root-filename`
** In this example, the top-level element in the output file
   is the `refentry`, so set ids which become the basename of the file: +
+
 refentry id="aspectj-mode"  # in aspectj-mode.xml, produces aspecj-mode.html
 refentry id="ajdee"         # in ajdee.xml, produces ajdee.html

** related parameters: `html-ext`, `root-filename`
** these tags did not work for me: `dbhtml filename="foo.htm"`, `dbhtml prefix="foo-"`

== Resources

- the dtd reference for docbook
  http://www.oreilly.com/catalog/docbook/chapter/book/docbook.html
- the stylesheet reference for docbook xsl
  http://docbook.sourceforge.net/projects/dsssl/doc/html.html

== To Do

- fyi, generate.reference.titlepage appears not to be respected.
  tried to add if statement to html/refentry.xsl, but file still gen'd