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.
This was more relevant in v0.4.6. If you're debugging
stuff and turned on ("albert" "use-temporary-files"),
you might need to specify location of xml-parser. In case you just
ran 'make' or installed albert-programs outside
/usr/bin/ you might need to help albert a bit by specifying
where the programs are:
(setf apispec:*xml2sexp-prog* "/home/stig/Projects/albert/expat/alb_xml2sexp")
You don't need to worry about the xml2esis program, it isn't used
and xml2sexp 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
("albert" "use-temporary-files") to NIL
and the xml-programs will not be used and no temporary files will be
created.
Currently Albert doesn't know about the CL-USER package, but the default handling will be just fine. Don't worry.
Albert uses READ 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.
An example:
(dolist (i '(+ - * / = < <= > >= /= dotimes cons list push pushnew string dolist assoc)) (pushnew i lisp2csf:*ignorable-calls*))
This will ensure that these functions do not show up in the "Calls" or "Called by" documentation.
You can check the albert.css for how to configure the
look of it, to turn on and off parts of the naigation header or
footer, check the albert.dsl file and the
%albert-navigation settings in it. The navigation has
changed/been improved from v0.4.5 to v0.4.6.
The simplest way is to copy the icons/ directory from
the data/ directory in the Albert distribution
(/usr/share/albert/data/ on Debian) to the documentation
output-dir (like you copy albert.css file there). If you
need a separate path to the icons, please check albert.dsl
where you can set %albert-navigation-iconpath% to the
path where your icons are.
Typically the simplest is to tweak the albert.css file where most of the look'n feel can be tweaked. Some of the more structural HTML-issues can be tweaked in albert.dsl.
Check albert.css for font.exported and
font.not-exported. These are typically commented out by
default.
Yes, jade will probably complain about several things, examples:
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"
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 -wnovalid
option to jade which will ensure that the above errors/warnings are
not displayed.
There are two ways to do this currently. If you want to change
the default string for the various objects, check
settings.lisp for the ("albert" "presentation"
"default-purpose-string" *) settings. The way to change the
specific message for a given class is to use a javadoc-style
@purpose field in the documentation string,
example:
(defstruct foo "Foo class this that and this that. ... @purpose Handles Xyzzy transport." a b c d)
This is being worked on.
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):
(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)))
This will override for classes, and make the <title>
PACKAGENAME:CLASSNAME, other variations exist of
course.
FOOBAR macro, and I
want contents in FOOBAR analysed, how can I do that? Here's an example from Langband, where I have a macro called
WHEN-BIND:
(defmacro when-bind ((var expr) &body body)
"generalisation of (let ((var expr)) (when var ...))."
`(let ((,var ,expr))
(when ,var
,@body)))
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 T if it analysed something,
or NIL if it didn't.
(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)))
Check the settings you can set here. Setting ("albert"
"presentation" "funcallable" "calledby") should do the
trick.
Thanks goes to Erik Enge for testing things early and providing much good feedback, questions and suggestions.
| stig@users.sourceforge.net Last modified: Sat Jul 5 14:07:34 CEST 2003 |
|