|
123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148 |
- <html>
- <head><title>AspectJ docs</title></head>
- <body>
- <h2>AspectJ docs</h2>
- <h3>Contents and build</h3>
- <p>
- This module contains the sources for the documentation
- delivered with the AspectJ distribution and
- for various internal, teaching, and online works:
- </p>
- <ul>
- <li><a href="devGuideDB">devGuideDB</a>: DocBook sources
- for the AspectJ Development Environment Guide</li>
-
- <li><a href="progGuideDB">progGuideDB</a>: DocBook sources
- for the AspectJ Programming Language Guide</li>
-
- <li><a href="faq">faq</a>: DocBook sources
- for the AspectJ Frequently Asked Questions</li>
-
- <li><a href="sandbox">sandbox</a>: a collection of sample
- AspectJ programs, tools built on the AspectJ API's,
- script snippets, and instructional trails, all intended
- to serve as sources for documentation.
- See <a href="sandbox/readme-sandbox.html">
- sandbox/readme-sandbox.html</a></li>
-
- <li><a href="teaching">teaching</a>: Teaching materials, esp.
- for the AspectJ tutorials.</li>
-
- <li><a href="quick.doc">quick.doc</a>: The Microsoft Word
- source file for the .pdf Quick Reference guides
- <a href="dist/doc/quick.pdf">dist/doc/quick.pdf</a> and
- <a href="dist/doc/quickA4.pdf">dist/doc/quickA4.pdf</a>.</li>
-
- <li><a href="build.xml">build.xml</a>: Ant build script for
- the doc distribution</li>
-
- <li><a href="developer">developer</a>: Docs for AspectJ developers.
- See the <a href="developer/overview.html">overview.html</a></li>
- </ul>
-
- <p>
- <u>Build</u>: <a href="build.xml">build.xml</a> assembles a local
- distribution which is gathered into the product distribution by
- the master build script,
- <a href="../build/build.xml">../build/build.xml</a>.
- Dependencies outside this directory:
- </p>
- <ul>
- <li>.xml files refer to their docbook dtds using relative
- path, for the moment ../../lib/docbook/...
- </li>
- <li>When building docbook, uses ../lib/saxon libraries.
- </li>
- <li>When building installer, using ../lib/build/build.jar
- and the ../build/installer-resources.
- </li>
- <li><a href="dist/doc/quick.pdf">dist/doc/quick.pdf</a>
- is generated manually from <a href="quick.doc">quick.doc</a>.
- </li>
- <li><a href="../org.aspectj.lib">../org.aspectj.lib</a>
- 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>
|