I think this is quite a good idea as a complement to the usual topical documentation and for luring other math-software users in. The biggest problem is maintenance, I guess: I don't exactly know how much Mathematica, Maple etc. change in each version, but for the more obscure functions, there will be an upkeep for each new version. I know that at least Maple is infamous for making larger changes without warning.
> Nathann wrote: > Then, because I am thinking of Graph Theory, it would be hard > sometimes to give, as you say, just one equivalent. Sometimes, many > are available, sometimes our Sage methods replace several Mathematica > methods at once because of our optional arguments. Sometimes, there is > no equivalent Mathematica method, but one doing "almost" the same job > : I remember having seen that Mathematica was only able to approximate > problems for which we had exact solvers, in which case we have to > explain in the "Equivalent" line the difference between the two. All > in all, I would quite love to be able to write a small paragraph > corresponding to an "Equivalent" line, to deal with all of it. > > What would you think of such a paragraph ? > > EQUIVALENTS: > > Mathematica : Small paragraph if necessary (and most probably on > multiple lines as we try to keep them short in the code), talking > about the differences between the current method and Method 1/2. (This > paragraph does not contain any list, as we want to be able to parse > the following commands easily ?) > > * Method 1 > * Method 2 > > Scilab : Same kind of things... > > * Method 1 > * Method 2 I like Nathann's structure for the doctest section. There is no doubt that for most functionality, another math system will not have an equivalent or even a close analogue. Rather, there will be a set of functions which combined in various ways can emulate most of the behaviour. So I would suggest a heading being non-specific such as "In other software". As I understood it, the list of methods after each alternative system's text paragraph should only be for searching and autogenerating dictionary-like documentation in the sense Dave suggested, right? Though it kind of disappeared from the discussion, I also like adding the Wikipedia and Mathworld references. Don't we already have a "references" section? This could be extended to including not directly cited material. Or we could add a "See also" section, like Wikipedia's. Cheers, Johan On Sep 22, 7:51 am, mda_ <[email protected]> wrote: > > > How about "close analogue". > > > No, I don't like that. If nothing else, it will be more confusing to those > > whose > > first language is not English, and even though mine is, I don't like that > > term. > > Tom Boothby can "inventor" a word. I do like "analogues" though. > > m-w.com: "1:something that is analogous or similar to something else" > > Since the functions may have different modes, context, side-effects, > options, evaluation order, precision, memory complexity/access order/ > alignment, cpu/runtime complexity, test coverage etc. ad nausium I > think the point is to call them "[Somewhat equivalent, but not the > same.]" > > > >> Nobody can expect the commands to be identical - except for trivial > > >> ones like > > >> Sin[], Cos[]. In the case of factor() there are two very obvious > > >> Mathematica > > >> commands that provide broadly similar functionality. > > > > Since Mma doesn't post it's BNF (Grammar), it's an exercise in reverse > > > engineering. > > > > -Don > > > But we don't need that for documentation. I'd be quite keen to have Sage > > read > > Mathematica input, or at least some sort of converter. Then one needs to be > > a > > I don't think anyone is going to step forward to write a parser > generator and maintain it, so I agree that trivial similars in the > docstrings is a good idea. > > Cheers, > Don -- To post to this group, send an email to [email protected] To unsubscribe from this group, send an email to [email protected] For more options, visit this group at http://groups.google.com/group/sage-devel URL: http://www.sagemath.org
