> I think the essay which Stavros posted is very informative.
> It seems suitable for reference or background material.
> However, I would like to suggest that the on-line
> documentation for ev be organized differently: describe(ev)
> should say just what ev does, without trying to rationalize
> it or consider alternative implementations, etc.
I agree entirely. My message was an explanation and critique of some
behavior in EV that people have trouble with. Parts of it could be used
for reference documentation of EV, though the detailed discussion, with
examples, of evaluation belongs in some sort of "for advanced users and
masochists only" subsection. Probably none of it is suitable for
tutorial documentation (except maybe an elaboration of the bullets under
"let me try to summarize"). Most of it is relevant to a design notebook
(discussion of deisgn issues in current Maxima and alternative designs
for the future).
But mostly, I'd expect that it would be used as *background* for those
writing documentation, not as documentation in itself.
> The current describe(ev) is, I believe, appropriately
> slanted toward "what happens" instead of "why it happens",...
I disagree strongly. The user does not care and should not care about
"what happens". But "why it happens" is not of great interest either,
except as motivation/explanation. The user cares about the black-box
behavior, things that affect usage. Surely you would not suggest that
documentation for 'sign' or 'integrate' be documented in terms of their
internals? Though the baroque semantics of EV make it hard to explain
in a black-box way, I think we can do better than the current text.
> I think clearing up the existing describe(ev) could be
> relatively simple (yes, I'm a born optimist) since all that's
> needed is to accurately report what ev does to various
> combinations of arguments.
Clarity is necessary in addition to accuracy. The current text
accurately predicts that ev((x+1)^2,expand,factor) returns the expanded
form, but ev((x+1),rat,factor) returns the factored form; and that
ev(sin(1),numer) and ev(sin1),bfloat) and ev(sin(1),sin) return 0.84 but
that sin(1),float returns sin(1). But understanding that is hard! Good
documentation (even reference documentation) should include discussion
and warnings about potentially confusing areas. Of course, even better
to fix the behavior, but we're just talking about documentation here....
-s