<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
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>
projects / aspectj.git / commitdiff