mirror of
https://github.com/eclipse-aspectj/aspectj.git
synced 2024-07-30 20:20:12 +02:00
149 lines
5.6 KiB
HTML
149 lines
5.6 KiB
HTML
<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>
|