|
|
@@ -1,7 +1,8 @@ |
|
|
|
<html> |
|
|
|
<head><title>AspectJ docs</title></head> |
|
|
|
<body> |
|
|
|
<h1>AspectJ docs</h1> |
|
|
|
<h2>AspectJ docs</h2> |
|
|
|
<h3>Contents and build</h3> |
|
|
|
<p> |
|
|
|
This module contains the sources for the documentation |
|
|
|
delivered with the AspectJ distribution and |
|
|
@@ -62,5 +63,86 @@ Dependencies outside this directory: |
|
|
|
provides library sources for <code>{AspectJ}/doc/aspectjlib</code>. |
|
|
|
</li> |
|
|
|
</ul> |
|
|
|
<p> |
|
|
|
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). |
|
|
|
</p> |
|
|
|
<h3>Docbook notes</h3> |
|
|
|
<p> |
|
|
|
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. |
|
|
|
</p> |
|
|
|
<pre> |
|
|
|
---------------------------------------------- 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) |
|
|
|
- many "No spaces to justify text in line" |
|
|
|
|
|
|
|
---------------------------------------------- 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 |
|
|
|
|
|
|
|
-- fyi |
|
|
|
- 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 |
|
|
|
- todo |
|
|
|
- fyi, generate.reference.titlepage appears not to be respected. |
|
|
|
tried to add if statement to html/refentry.xsl, but file still gen'd |
|
|
|
</pre> |
|
|
|
</body> |
|
|
|
</html> |