Differences between Maxima and Macsyma and GPL vs. commercial version

--- Raymond Toy <toy@rtp.ericsson.se> wrote:

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

Hmm.  I guess it depends on what we want to use Docstrings for, but I
don't see that as being a problem per say.  Docstrings, if I understand
correctly, are source code level comments which programmers would add
to document what a function does, right?  Many of these functions would
be internal and not intended for general/non-power-user consumption,
but still need to be documented.  Formatted examples are much better
for regular user level documentation, but only a percentage of the
functions in Maxima will need it.  Advanced users will not need
formatted examples if they are doing power usage work, but good text
descriptions are a godsend.

Maybe what we could do is treat docstrings as the basic minimum level
of documentation everything should have.  Then, on top of that, we add
another layer for user level functions which supports formatted
examples.  

> 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.)

Hmm.  I would say that rather than put HTML into docstrings (which
would make reading them in the source code a pain) we use strictly text
for source code level documentation and generate HTML on the fly from
the docstrings using a CSS or xml template.  Plus, I think people would
be more likely to maintain them if they didn't have to think in HTML to
write 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. 

What's the license on that?  It might serve as a starting point for
building what we need.
 
> All in all, docstrings are a trivial detail compared to the 
> substantial 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 agree.  Docstrings can be the foundation on which more user friendly
documentation is built on the future.  If the source code is well
documented creating other documentation is a whole heck of a lot
simpler.

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

I agree.  When the documentation is right there for the programmer when
they are working on the code, it is much simpler and more
straightforward to update.  Reference and User manuals we can ensure
are updated for major releases, but a continually maintained source
code level documentation in CVS seems to me like a Good Thing.
 
> Oh, well,

No Ray, to this newbie at least your ideas sound very good.  Of course
I don't know in the end how impractical/practical it might be, but we
need something and this has a lot of advantages.

Stavros is correct in that good documentation is very difficult to do,
but I think having a good system in place is an important first step. 
Currently we have almost nothing.  I think eventually we should make it
a policy that any change committed to cvs have proper documentary
docstrings in place, but the code is years away from that level.

Anyway, worthy of discussion.

CY

__________________________________________________
Do you Yahoo!?
Yahoo! Tax Center - File online, calculators, forms, and more
http://tax.yahoo.com