Differences between Maxima and Macsyma and GPL vs. commercial version

>>>>> "Richard" == Richard Fateman <fateman@cs.berkeley.edu> writes:

    Richard> Docstrings might help to remind you of something you
    Richard> already knew, but strikes me as a bad idea for being
    Richard> a primary documentation tool.  You need stuff described

I wasn't proposing it as the primary tool for documentation.  At least
someone thought enough of it to make a Lisp tool to extract docstring
to produce a LaTeX reference manual out of it.

And I do use docstrings in emacs as a primary tool for documentation.
The real documentation is usually out-of-date, so short of reading the
code, the docstrings are usually quite helpful.  If nothing else,
they're pointers to what can be done and what else to look for. 

I also use it a lot in cmucl to figure out how something works,
including compiler internals.

    Richard> in context or else it is all terribly repetitive.

    Richard> (defun third(a)" See chapter X for complete documentation
    Richard> on user-level list selection and construction programs.
    Richard> Third selects the 3rd element from a list.
    Richard> input: any macsyma general expression
    Richard> output: third element if there is one
    Richard>   Possible errors:
    Richard> Time:
    Richard> algorithm description:

    Richard>   "
    Richard>     body of function...)

But the user manual has this same kind of problem.  There's a lot of
context that you need to know before you actually use it.  

If I had written the docstring for third, I would have just said

        "returns the third element of a list, if there is one"

That probably would have been clear enough to anyone looking for some
function to extract the third element of a list.  If you didn't know
what a list was, you wouldn't have been looking for third. :-)

Anyway, docstrings won't solve the problem of not having a good
reference manual or user's guide.

Ray