Differences between Maxima and Macsyma and GPL vs. commercial version

>>>>> "Stavros" == Stavros Macrakis <stavros.macrakis@verizon.net> writes:

    >> Since maxima uses Lisp, and Lisp has doc strings for functions, I've
    >> always thought describe should look there instead of some mostly
    >> out-of-date info file somewhere.

    Stavros> Very few Maxima functions or variables currently have docstrings.  So
    Stavros> someone has to add them.

Yes, like I said.

    Stavros> Docstrings as normally used do not support any sort of formatting (HTML,
    Stavros> MathML, whatever), hyperlinks, or global structure (this function is
    Stavros> part of the such-and-such subsystem) so are a very impoverished format.

Since the current manual doesn't really have this either, I don't see
this as a major problem yet.  And we can always put HTML into the
docstrings if we so choose.  Describe should then be quite a bit
smarter to display the docstring neatly.  (No, I'm not talking about
displaying HTML properly, but perhaps stripping out the HTML markers.)

    Stavros> Adding docstrings to the code base as opposed to a separate
    Stavros> documentation system would mean that documentation would live in at
    Stavros> least TWO places, which would inevitably be out of synch.  Though
    Stavros> docstring-style documentation is different from reference-manual-style
    Stavros> documentation, they should probably live in the same place to make it
    Stavros> easy to maintain them.

Well, there is the manual-ref package in the CMU AI archives for
extracting docstrings and producing a LaTeX reference manual out of
it.  Works ok, but perhaps this isn't really an adequate solution
either. 

    Stavros> All in all, docstrings are a trivial detail compared to the substantial
    Stavros> problem of (a) writing good documentation; and (b) presenting it well.

Given our limited resources and the probably even more limited number
of people who are willing and able to do (a) and (b), docstrings can
fill the very large gap between nice documentation and no
documentation at all.  

I think a programmer is more likely to keep docstrings up-to-date than
to keep some reference manual up-to-date.

Oh, well,

Ray