First, we should do a cross reference of the code. There is a cross
referencer in
the cmu archive.
Second we include a document that describes the data structure format of
maxima elements.
Third we sort the functions by use, and start documenting them starting
from the most
commonly used.
Fourth we look for places where special variables are used to pass
parameters and fix those.
Dan Stanger
C Y wrote:
> 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
> _______________________________________________
> Maxima mailing list
> Maxima@www.math.utexas.edu
> http://www.math.utexas.edu/mailman/listinfo/maxima