Hi all. This is largely a curosity question, but since it seems to be
stuck in my brain at the moment I thought I might as well pose it to
the list. (Misery loves company ;-) I was thinking about the rather
monumental task we will someday face of documenting the Maxima source
code, and wondering how to go about it. I can think of some things
that might be nice to have/do (or so it seems to me, at least) and I
thought I'd see if anyone knows about tools to accomplish them.
First, I guess I'd better define the basis I'm thinking from, to make
it easier for everyone to shoot me down :-). I'm thinking the overall
broad way to approach this problem is to systematically document every
function in the lisp and maxima source files (yeah I know it will take
forever and be boring as heck, but I fear there's no way around it)
recording name, syntax for calling it, whether it is intended as a user
callable function or a purely internal one (not sure this is really a
meaningful distinction in Maxima - feel free to correct me on this one)
, purpose, expected input/output types, scope? and other
functions/files/whatever it depends on. And any other interesting
tidbits such as who wrote it, source for algorithm, how robust it is
considered to be, etc. can also be included.
OK, given that goal, there are a few tasks which I see as hopefully
part of the same job, and with the correct tools maybe they can be one
task. We want "on site" documentation in the source code, but we also
want a system reference manual (not user manual, note, but system
manual) and online help sytem. We have both of these now, but my guess
is that they are much in need of both fleshing out and correction. I
would like to be able to automatically generate these files in texi or
whatever the proper format is from the source code comments, so we can
document in one place and have an autoupdate script do the rest. (I'm
sure someone else suggested this long ago and i've forgotten - my
apology for not crediting whoever said it first here.)
Does anyone know of any method out there to parse comments in some form
from lisp code to form texi files? If not, would it be worthwhile to
create a solution which can do the above? My only thought at the
moment is we might define an xml format for entries to be inserted as
comments into the lisp code and then easily parsed into some predefined
texi/info/whatever format. There can be tags for chapter/section so
the program knows where in a book to put them.
Also, the other significant problem is the interdependancy of the files
and functions in the system - it would be very helpful to document
these. I was wondering if it would be possible to generate a map of
all the functions in the Maxima system and which functions they depend
on. This does not entirely solve the problem, but in theory at least
it should help - if we edit some part of the code we can look and see
what other parts of the system depend on that code, and what the impact
might be. Does anybody know of such a source code mapper? A graphical
map would be neat, but the really useful part would be to be able to
add to the documentation a record of the interdepenancies of the code.
Does anyone know of such a tool?
CY
__________________________________________________
Do you Yahoo!?
Yahoo! Mail Plus - Powerful. Affordable. Sign up now.
http://mailplus.yahoo.com