--- Richard Fateman <fateman@cs.berkeley.edu> wrote:
> I'm not going to solve any problems here, but
> (a) Some of the real experts have already documented
> the code, and the post-1982 improvements to it as
> well. We just don't have that material, and it
> is discouraging to re-do it. Bug fixes and docs.
I'm assuming you mean the Macsyma manual. I agree, but unfortunately
that work appears to have effectively vanished as far as we are
concerned, unless someone can pry it out of whatever hole it is hiding
in. Copies exist in printed form and some rather hideous postscript,
but even if we retyped it all we have no legal right to use it. Unless
perhaps someone has the original documentation at MIT before the
commercial people got their hands on it? Maybe they could release
that? If not, I guess we'll just have to live with it and do the best
we can.
> (b) Some of the documentation should be
> "dont use this program... it does the same
> thing as xxx but the author didn't know about
> that other thing"
That should be doable - maybe the best thing to do would be something
like gcc does - depreciate code like that, and eventually consign it to
the archive directory. Trick is knowing what code needs that
treatment.
> (c) information that is automatically produced
> is very voluminous. All global variables and
> places they are referenced, bound, set. All dependencies
> of programs... There are sophisticated tools for
> looking at large data sets (from Xerox PARC), but
> these are kind of "data mining" (ugh! hate that term)
> programs. The data here was produced by
> hand and could be explained better.
Probably, but xref might at least prove useful for pointing out places
to start. I've gotten it to scan all but about 14 of the lisp files in
src, and the output is indeed voluminous. (something on the order of
half a million lines.) Obviously no one will absorb all that, but
specific parts of it might prove useful for specific tasks/problems.
For example, it should be possible to have it find all parts of the
code which reference a particular function.
> (d) There is a somewhat parallel effort in the
> Axiom community to document their code. Their
> take on it is to try something like noweb (literate
> programming).
Yes, I've been watching that. Interesting, but I don't think Maxima is
suited to their particular approach, at least if I understand what
they're attempting.
> (e) I have suggested repeatedly that there should
> be a list of all error and warning messages and
> explanations. (Mathematica has this).
I agree.
> (f) For many programs, I suspect it is easier
> to write a simpler correct program than to explain
> the existing program. This is very tricky because
> if you don't really understand a program, you might
> simplify it into something incorrect.
Probably the latter would be the result for all but our most skilled
coders. I know I wouldn't dare. I'm hoping thoroughly documenting the
code might make it easier to see what's actually going on and what
impact changes might have on the system (hence my interest in xref.)
That's a labor of hercules, unfortunately, but if we are systematic
about it maybe some good will come out of it.
Still, I'd love to get my hands on the MIT documentation, if they still
have it and are willing/able to release it. I think I tried to contact
them once about it and got ignored. Anybody have any connections at
MIT? :-)
CY
__________________________________________________
Do you Yahoo!?
Yahoo! Mail Plus - Powerful. Affordable. Sign up now.
http://mailplus.yahoo.com