Subject: Case sensitivity, line labels and the future
From: C Y
Date: Tue, 15 Apr 2003 08:01:52 -0700 (PDT)
--- Martin RUBEY <rubey@labri.fr> wrote:
> On Tue, 15 Apr 2003, C Y wrote:
>
> > --- Martin RUBEY <rubey@labri.fr> wrote:
> >
> > > Axiom is on the way to become THE powerful free CAS, but they are
> not
> > ...
> > I agree it looks powerful, but aside from the whole proof based
> > approach they seem to want to take, are they really that much more
> > capable than us?
>
> I think yes, but I don't know. I think Richard would know. It might
> depend on what you want to do.
Hmm. Well, competition is good.
> > Also, there's no code publicly available yet, as far as I know.
> They take a very profound approach (document before release), but
> there is a 'private' archive where you can get the code from. Ask
Tim
> Daly (daly@idsi.net) if you're interested.
That is a good approach, but the time to document it could be
tremendous. How many people are working on it?
> What do you think about my language/lisp observation? In fact, this
> was the point I tried to make...
It is a good point, and probably true. I don't know enough about the
benefits to properly evaluate it though - I'm still too much of a
newbie user.
> > > (1b) improve the math. I think there are some 200 math bugs out
> > > there.
> >
> > I agree, this is the crucial point, but since only a few of us are
> > skilled enough to address such bugs this is a fun argument for the
> > rest of us ;-).
>
> I don't think the problem is about maths. I think the problem is with
> documenting the maths. I'm absolutely certain you would be able to
> understand how simpsum works, and that you could write it up and
> share it.
>
> Unfortunately, the rat package is one part of maxima which seems to
> be crucial, and is not easy to understand. So I need to propose two
> things: documentation and clean interfaces. hayat (taylor) does not
> seem to interface correctly, and it fails too. (And I failed to
> correct the bug, I can cure only the symptom)
Hmm. If I recall correctly, didn't Richard originally write the rat
package? Richard, is there any in depth documentation of rat anywhere?
> The problem I have is that its probably hopeless for me to understand
> *all* of maxima. (also due to lack of time) I do understand bits and
> pieces. It would be much easier if the code would be documented.
> However until there is no policy how to do it, I won't start. Not
> even with the bits I understand. Also there are rumours that there is
> documentation around somewhere, just not really available. Until all
> that's settled, nothing much will change.
The only rumored documentation I'm aware of is a) the MIT documentation
and b) commercial Macsyma documentation. The commercial docs seem to
be utterly beyond our reach, and I wouldn't waste time waiting for
them. I don't know for sure about the MIT docs - I'm working on it,
but it's very slow going. The knowledge about them seems to have
almost entirely disappeared. Even to the folks who were there at the
beginning it is a decades old project not really connected to their
current work.
My take on it is we should start documenting what we have, and not
count too much on outside docs reappearing. As to how to document the
source code... We had a big discussion on the list a while back about
that. I don't know if we came to any kind of concensus. Ray had some
very good ideas about docstrings and maybe the manual package in the
CMU archive:
(http://www-2.cs.cmu.edu/afs/cs.cmu.edu/project/ai-repository/ai/lang/lisp/code/tools/user_man/0.html)
We can contact the author and see if he would be willing to GPL it for
our use. I asked him about XREF and it was no go, so it's hard to say.
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. We have reached the point where that is now a very
desirable and possibly necessary step.
My proposal, based on Ray's ideas:
a) We use docstrings as source level comments. These will be updated
as code is changed, and be the most current documentation for a given
function.
b) Describe should use these comments rather than the info files.
This will result in a change in the way that describe presents itself
to the user, being a short description of what the command does rather
than a long documentation example. I personally find this preferable.
Probably for functions documentation should consist of something like
the following (note this is just to demonstrate my idea and probably
not accurate):
integrate - a function to do integration
Form: integrate(<function>,<integration variable>,{lower limit},{upper
limit});
Uses: intsec, ldefint, risch
Docauth: CY
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.
c) If people still want examples of the behavior of a function, we
might define a new help command called examples. For example, if the
above wasn't enough for integrate, someone could do:
examples(integrate);
(ExIn1) integrate(x^2+y^2,x,1,5);
2 2
15 y + 125 3 y + 1
(D1) ----------- - --------
3 3
(ExIn2) integrate(x^3+3,x,a,b);
4 4
b + 12 b a + 12 a
(D2) --------- - ---------
4 4
(ExIn3) integrate(1/(1+x+x^5),x);
/ 2
[ x - 4 x + 5
I ------------ dx 2 x + 1
] 3 2 2 5 ATAN(-------)
/ x - x + 1 LOG(x + x + 1) SQRT(3)
(ExIn3) ----------------- - --------------- + ---------------
7 14 7 SQRT(3)
We can also add any examples to the test suite.
> > Agreed, with the possible exception of share packages intended for
> > classroom work.
>
> No, no exceptions. Sorry, but capital_* does not convince me.
Sigh. OK. You or anyone else apparently. I bow to experience.
> BTW, didn't Richard post that one of his students downcased maxima as
> part of some project?
Yes, I believe he did. Richard, did anything ever come of that?
CY
__________________________________________________
Do you Yahoo!?
The New Yahoo! Search - Faster. Easier. Bingo
http://search.yahoo.com