diff options
| author | wisberg <wisberg> | 2005-03-10 08:10:17 +0000 |
|---|---|---|
| committer | wisberg <wisberg> | 2005-03-10 08:10:17 +0000 |
| commit | cf4d7b321093e16d13ba90b21515a1f29648f64b (patch) | |
| tree | 5f6361a7be4f92b6ee18a9e884c186d9d721e731 | |
| parent | a5e1a73048c9d8edf8834ec2ec34dc29ac61a31c (diff) | |
| download | aspectj-cf4d7b321093e16d13ba90b21515a1f29648f64b.tar.gz aspectj-cf4d7b321093e16d13ba90b21515a1f29648f64b.zip | |
Docbook comments from build.xml, fop/pdf comments
| -rw-r--r-- | docs/readme-docs-module.html | 84 |
1 files changed, 83 insertions, 1 deletions
diff --git a/docs/readme-docs-module.html b/docs/readme-docs-module.html index 69b10e2a2..53451ec71 100644 --- a/docs/readme-docs-module.html +++ b/docs/readme-docs-module.html @@ -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> |