123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117 |
- = 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
|