From cf4d7b321093e16d13ba90b21515a1f29648f64b Mon Sep 17 00:00:00 2001 From: wisberg Date: Thu, 10 Mar 2005 08:10:17 +0000 Subject: Docbook comments from build.xml, fop/pdf comments --- docs/readme-docs-module.html | 84 +++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 83 insertions(+), 1 deletion(-) (limited to 'docs/readme-docs-module.html') 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 @@ AspectJ docs -

AspectJ docs

Contents and build

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 {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

+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)
+- 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
+

-- cgit v1.2.3