diff options
Diffstat (limited to 'docs/readme-docs-module.adoc')
| -rw-r--r-- | docs/readme-docs-module.adoc | 98 |
1 files changed, 0 insertions, 98 deletions
diff --git a/docs/readme-docs-module.adoc b/docs/readme-docs-module.adoc index 523912921..d7d236749 100644 --- a/docs/readme-docs-module.adoc +++ b/docs/readme-docs-module.adoc @@ -17,101 +17,3 @@ works: guides `quickref/quick.pdf` and `quickref/quickA4.pdf`. * `build.xml`: Ant build script for the doc distribution * `developer`: Docs for AspectJ developers - -*Build*: `build.xml` assembles a local distribution which is gathered -into the product distribution by the master build script, -`../build/build.xml`. Dependencies outside this directory: - -* `.xml` files refer to their docbook dtds using relative path, for the - moment `../../lib/docbook/...` -* When building docbook, uses `../lib/saxon` libraries. -* When building installer, using `../lib/build/build.jar` and the - `../build/installer-resources`. -* `quickref/quick.pdf` is generated manually from `quickref/quick.doc`. -* `../org.aspectj.lib` 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 - -#*TODO:* Remove this section after AsciiDoc conversion is complete# - -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`.) -- `No spaces to justify text in line` many times - -== 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 - -** 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 - -== To Do - -- fyi, generate.reference.titlepage appears not to be respected. - tried to add if statement to html/refentry.xsl, but file still gen'd |