aboutsummaryrefslogtreecommitdiffstats
path: root/docs
diff options
context:
space:
mode:
authorwisberg <wisberg>2005-03-10 08:10:17 +0000
committerwisberg <wisberg>2005-03-10 08:10:17 +0000
commitcf4d7b321093e16d13ba90b21515a1f29648f64b (patch)
tree5f6361a7be4f92b6ee18a9e884c186d9d721e731 /docs
parenta5e1a73048c9d8edf8834ec2ec34dc29ac61a31c (diff)
downloadaspectj-cf4d7b321093e16d13ba90b21515a1f29648f64b.tar.gz
aspectj-cf4d7b321093e16d13ba90b21515a1f29648f64b.zip
Docbook comments from build.xml, fop/pdf comments
Diffstat (limited to 'docs')
-rw-r--r--docs/readme-docs-module.html84
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>