--- Stavros Macrakis <stavros.macrakis@verizon.net> wrote:
> First of all, I've changed the Subject line to "documentation" from
> "case sensitivity etc.". Could we please keep each thread to one
> subject?
Sorry :-).
> --------------------
>
> >> 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 ;-) ).
Eeep.
> 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
Hmm. OK. I take the Macsyma Conference records wouldn't help much
either?
> -- 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.
Who at MIT handles copyright issues? The LCS doesn't seem to know.
> > 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.
Agreed.
> 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.
Well, as long as there is some standard we are using. What do you
think would be best for the long term?
> 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.
Agreed.
> > 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.
Hmm. OK, point. I was think about it wrong - I was considering what
someone editing the source would find most useful. The way to do it
then would be to have the description and syntax definition returned to
describe, but have the other parts present at that location in the
source code. That is where they will be most useful. What's the clean
way to do that?
> > 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.
Ah. What do you think of making example systematic? Would that make
sense?
CY
__________________________________________________
Do you Yahoo!?
The New Yahoo! Search - Faster. Easier. Bingo
http://search.yahoo.com