----- Original Message ----
> From: Robert Dodier <robert.dodier at gmail..com>
> To: Dieter Kaiser <drdieterkaiser at web.de>
> Cc: "maxima at math.utexas.edu" <maxima at math.utexas.edu>
> Sent: Mon, 27 September, 2010 3:45:40 PM
> Subject: Re: [Maxima] More documentation of Maxima internals
>
> On Sun, Sep 26, 2010 at 9:29 AM, Dieter Kaiser <drdieterkaiser at web.de> wrote:
>
> > I am interested to add the documentations to the project. We might add
> > it to the Lisp files (the documentation might be to verbose) or we start
> > to add a technical documentation in a TEXI format.
>
> For detailed documentation of internal Lisp functions,
> I think it's best to paste the documentation into the source code.
>
Robert, if this is done, and docs are embedded in source code,
would you be interested in some automation for adding them there?
The reason i ask is that if all functions, symbols whatever have docs in the
same format then at least... it can later be parsed out and used separately. It
would be a great shame for me in learning to use and program Maxima properly if
the documentation were not extractable. The reason is that... for myself and for
some other users i have to use a screen reader. i have often wanted to check
the sources for usages of variables etc and for this EMACS and grep suffice.
But if there is going to be internals documentation... i would be interested in
working to improve the Maxima user manual using these docs as well. To make the
going easier, i think there aught to be a discussion about a format for internal
docs that is at least able to be scripted. But then it becomes necessary to
enforce it.... or simply have it not work.
If a format can be agreed and it is something others want i will happily hack on
a set of macros for EMACS or similar to ease insertion of docs in this format.
> The examples you showed look great to me.
> I don't suppose it's necessary to document every function in
> that much detail, though.
Can it harm the road of the next 10 years worth of Maxima users, who at this
point probably have to be hackers as well still, if there is at least this much
detail? After all, what if one of You old hands takes sick and suddenly there is
no Fateman, no Willis, no Keiser. Then where will we be without it. Yet anoher
rewrite?
Robyn Hannigan, Dunedin New Zealand