1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
|
<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>
|
