Hey gang. Guess I might as well give you the full picture of what's
been bouncing around in my head, and ask for opinions/discussion.
Part A. I've been looking at using the Albert documentation system
(http://albert.sf.net) as a possible tool to generate low level
reference/programmer documentation for Maxima. It automatically scans
the source code and creates documentation from its scan, and has ways
to allow programmers to insert comments at the source code level which
are incorporated into the documentation. It is currently able to
digest the Maxima code at least in part thanks to a very helpful albert
developer on the IRC #lisp channel, although it's output is not
complete. (The system needs some expansion to handle how Maxima does
things.) It sounds like they might be willing to work with us to
improve their tool, and this might prove to be a very nice framework
within which to document the Maxima source code. To see what it does
with Maxima as of now, check http://maxima.sf.net/maximaalbert For a
better example of what it does with a codebase attuned to it, see
http://albert.sourceforge.net/Docs-Albert/
Part B) Clearly there is a lot of tweaking needed on the albert end to
handle the Maxima source, but one rather fundamental issue is that
albert organizes itself by packages, and most of the logic in Maxima is
grouped into the MAXIMA package. The net result is one very very large
html page. What to do to address this problem isn't entirely clear to
me, or rather the obvious way to address it might be a bad way.
The obvious way is to abandon the idea of having all of the Maxima
logic in one package, and create specific packages like
maxima-integrate, maxima-plot, maxima-ode, maxima-tex, whatever makes
sense (I haven't put a lot of thought into that yet.) XREF and albert
itself might both be of use in deciding what should go where, and what
to export from each package. One possible benefit to this is it would
quickly become much clearer what the scope of particular parts of the
code are, and what parts are impacted by any given change.
Drawbacks - I have been warned that the common lisp package system is
not without its warts - I don't know much about that but hopefully the
gurus on this list do. Also, it's a major undertaking to reorganize
the code in such a fashion, and should only be done if it is deemed to
be a good idea and have long term benefits worth the initial effort. I
am not qualified to address any of these concerns, so I bring it to the
list for discussion - what do you think?
CY
__________________________________
Do you Yahoo!?
Yahoo! Photos: High-quality 4x6 digital prints for 25¢
http://photos.yahoo.com/ph/print_splash