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
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
|
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
<head>
<meta http-equiv="Content-Type" content="text/html;charset=iso-8859-15">
<link rel="stylesheet" type="text/css" href="albdocs.css">
<title>Albert FAQ</title>
</head>
<body bgcolor="white">
<h1>Albert FAQ</h1>
<ol type=i>
<li> <b>What do I need to run Albert on my system?</b><br>
<p> Albert can manage mostly with a lisp-environment, but to process
the generated Docbook files you need a docbook-environment. For a
debian-system you will probably need jade, docbook and
docbook-dsssl. </p>
</li>
<li> <b>How can I tell Albert where I installed the
xml-programs?</b><br>
<p><b>This was more relevant in v0.4.6</b>. If you're debugging
stuff and turned on <code>("albert" "use-temporary-files")</code>,
you might need to specify location of xml-parser. In case you just
ran 'make' or installed albert-programs outside
<tt>/usr/bin/</tt> you might need to help albert a bit by specifying
where the programs are:</p>
<pre class="codesample">
(setf apispec:*xml2sexp-prog* "/home/stig/Projects/albert/expat/alb_xml2sexp")
</pre>
<p>You don't need to worry about the <tt>xml2esis</tt> program, it isn't used
and <tt>xml2sexp</tt> is faster. The xml-files are there for
debugging, safety and other tools, but if you just want to go
straight from lisp-code to docbook you can set the albert-setting
<code>("albert" "use-temporary-files")</code> to <code>NIL</code>
and the xml-programs will not be used and no temporary files will be
created.</p>
</li>
<li> <b>Albert/lisp2csf whines about CL-USER, why?</b><br>
<p> Currently Albert doesn't know about the CL-USER package, but the
default handling will be just fine. Don't worry. </p>
<li> <b>Albert seems unable to parse my lisp-code, why?</b><br>
<p> Albert uses <code>READ</code> to read the lisp-code, so at the
very least your code should be READable. Albert may also stumble on
references to symbols in undefined packages, because the lisp-reader
stumbles on it. When compiling your lisp-program, you might do a
lot of twisted and wacky stuff, and that is great (it's lisp after
all). But Albert has no interpreter and does not process macros so
it will not even try to do the twisted and wacky stuff, and as such
might miss some good parts.</li>
<li> <b>How can I tell Albert to ignore some calls?</b><br>
<p> An example:</p>
<pre class="codesample">
(dolist (i '(+ - * / = < <= > >= /=
dotimes cons list push pushnew string dolist assoc))
(pushnew i lisp2csf:*ignorable-calls*))
</pre>
<p>This will ensure that these functions do not show up in the
"Calls" or "Called by" documentation.</p></li>
<li> <b>How can I tweak the navigation header and footer?</b><br>
<p> You can check the <tt>albert.css</tt> for how to configure the
look of it, to turn on and off parts of the naigation header or
footer, check the <tt>albert.dsl</tt> file and the
<code>%albert-navigation</code> settings in it. The navigation has
changed/been improved from v0.4.5 to v0.4.6.</p>
</li>
<li> <b>How can I make the navigation icons work?</b><br>
<p> The simplest way is to copy the <tt>icons/</tt> directory from
the <tt>data/</tt> directory in the Albert distribution
(<tt>/usr/share/albert/data/</tt> on Debian) to the documentation
output-dir (like you copy <tt>albert.css</tt> file there). If you
need a separate path to the icons, please check <tt>albert.dsl</tt>
where you can set <code>%albert-navigation-iconpath%</code> to the
path where your icons are.</p></li>
<li> <b>How can I tweak the look of the documents?</b><br>
<p> Typically the simplest is to tweak the <tt>albert.css</tt> file
where most of the look'n feel can be tweaked. Some of the more
structural HTML-issues can be tweaked in <tt>albert.dsl</tt>.</p></li>
<li> <b>How can I make headers for exported and non-exported methods
differ?</b><br>
<p> Check <tt>albert.css</tt> for <code>font.exported</code> and
<code>font.not-exported</code>. These are typically commented out by
default.</p></li>
<li> <b>Jade is really noisy about the generated file, is that
normal?</b><br>
<p>Yes, jade will probably complain about several things,
examples:</p>
<pre class="codesample">
jade:RFC2822/BCC.xml:4:20:E: there is no attribute "class"
jade:RFC2822/BCC.xml:4:71:E: there is no attribute "hovertext"
jade:RFC2822/BCC.xml:7:15:E: there is no attribute "class"
jade:book.xml:71:24:X: reference to non-existent ID "packageXCL"
</pre>
<p> These are ok, jade will do as it is told. The extra attributes
are used to communicate info from lisp to DSSSL (formatting), and
they're not mentioned in the DTD. The 'non-existent ID' is usually
not a problem. You might also give the <code>-wnovalid</code>
option to jade which will ensure that the above errors/warnings are
not displayed. </p></li>
<li> <b>How can I change what is displayed in the TOC for my
class/struct/gf?</b><br>
<p>There are two ways to do this currently. If you want to change
the default string for the various objects, check
<tt>settings.lisp</tt> for the <code>("albert" "presentation"
"default-purpose-string" *)</code> settings. The way to change the
specific message for a given class is to use a javadoc-style
<code>@purpose</code> field in the documentation string,
example:</p>
<pre class="codesample">
(defstruct foo
"Foo class this that and this that. ... @purpose Handles Xyzzy transport."
a b c d)
</pre>
</li>
<li> <b>The 'full listing' gets really big and cluttered, how can I
sort it?</b><br>
<p> This is being worked on.</p> </li>
<li> <b>How can I change the <title> of generated HTML-pages?</b><br>
<p> By default the name of the class or generic function will be
used. If you wish to change this you can override the function that
sets this name, here's an example (details might change):</p>
<pre class="codesample">
(defmethod spres-impl:docbook-page-title ((doc spres-impl:docbook-document)
(object sdoc:sdoc-class))
(concatenate 'string (sds-global:get-object-name spres-impl:*enclosing-package*)
":" (sds-global:get-object-name object)))
</pre>
<p>This will override for classes, and make the <title>
<code>PACKAGENAME:CLASSNAME</code>, other variations exist of
course.</p> </li>
<li> <b>Albert doesn't know my <code>FOOBAR</code> macro, and I
want contents in <code>FOOBAR</code> analysed, how can I do that?</b><br>
<p> Here's an example from Langband, where I have a macro called
<code>WHEN-BIND</code>:</p>
<pre class="codesample">
(defmacro when-bind ((var expr) &body body)
"generalisation of (let ((var expr)) (when var ...))."
`(let ((,var ,expr))
(when ,var
,@body)))
</pre>
<p>It's not a sophisticated macro, but I use it a lot and I want the
EXPR and the BODY to be analysed by Albert, and this is an example
of how I do it. This function returns <code>T</code> if it analysed something,
or <code>NIL</code> if it didn't.</p>
<pre class="codesample">
(defmethod lisp2csf:check-body-expression (expr-type expression)
(cond ((equal (symbol-name expr-type) "WHEN-BIND")
(let ((var-calc (second (second expression))))
(lisp2csf:analyse-body-expression var-calc))
(map nil #'lisp2csf:analyse-body-expression (cddr expression))
t)
(t nil)))
</pre>
<li> <b>I hear rumours of Albert giving out 'called by' info, how?</b><br>
<p> Check the settings you can set <a
href="properties.html">here</a>. Setting <code>("albert"
"presentation" "funcallable" "calledby")</code> should do the
trick. </p> </li>
</ol>
<p>Thanks goes to Erik Enge for testing things early and providing
much good feedback, questions and suggestions.</p>
<hr>
<table width="100%">
<tr valign=top>
<td>
<address>stig@users.sourceforge.net</address>
<!-- hhmts start -->Last modified: Sat Jul 5 14:07:34 CEST 2003 <!-- -->
<!--hhmts end -->
</td>
<td>
<div align=right><a href="http://sourceforge.net"><img
src="http://sourceforge.net/sflogo.php?group_id=84355&type=5" width="105" height="31" border="0" alt="SourceForge.net Logo" /></a></div>
</td>
</tr>
</table>
</body> </html>
|
