First of all, I've changed the Subject line to "documentation" from
"case sensitivity etc.". Could we please keep each thread to one
subject?
--------------------
>> its probably hopeless for me to understand *all* of maxima.
But why would you want to? Work on one piece at a time. It is not
perfectly modular, true, but you can figure things out. As you're
figuring it out, write up your notes.
> The only rumored documentation I'm aware of is a) the MIT
> documentation and b) commercial Macsyma documentation.
I believe we have all the MIT user documentation. There was essentially
zero MIT internal documentation (the code is self-documenting ;-) ).
Some modules were written as Ph.D. work, so the dissertations include
some documentation. RJF has pointed me at Moses' thesis for
documentation of the Schachten pattern-matcher, for example. But (a) I
don't think most of the dissertations include very detailed code-level
documentation -- much more on algorithms, which of course is also useful
-- and (b) it is probably out of synch with the actual code. But I
should look them up at the MIT archives one of these days.
> Probably we should decide now at least on a standard source
> code documentation method, so new code writers and people
> fixing up old code know what to do.
Well, the very first thing we need to do is to distinguish between USER
documentation and INTERNAL documentation. It would be a disaster to
confuse the two. Docstrings are probably best suited to be used for
INTERNAL documentation, because there are Lisp-level tools which take
advantage of them. But as I've said before, there is nothing magical
about docstrings. It is trivial to write, e.g.
(put '$defint "Defint is blah blah blah" 'user-documentation)
or for that matter to package that into a defmaxima macro.
Also, there needs to be more than one level of user documentation. The
simplest documents the arguments and general function. Then you want
the one-paragraph version giving the most important features and
options. Finally, the full version with all the gory detail. The
simple form is suitable for a command-line setting -- the other ones
make more sense with a separate documentation viewer.
> That contains enough information to get a user started with
> integrate, documents what integrate depends on for a
> programmer, and identifies who to blame for mistakes.
Why mix up these three things? The vast majority of users have
absolutely no interest in its dependencies or the document author.
> c) If people still want examples of the behavior of a
> function, we might define a new help command called examples.
Actually, there already are commands EXAMPLE and DEMO. But of course
not systematic.
-s