On 09/22/10 08:01 AM, Johan S. R. Nielsen wrote:
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.
To be honest, I'd guess Sage changes more in a backwards incompatible way than
Mathematica! If for no other reason that the release cycle of Mathematica, Maple
and MATLAB are much longer than Sages. (I don't know about Macsyma, but I know
of product aimed at professionals with a release cycle like Sage.)
Yes, maintenance could be an issue, but I believe even outdated references will
be better than none at all.
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?
Perhaps there needs to be two sets of information then.
1) What I suggested. I'm not going to argue about the wording, but for the sake
of this discussion assume "Related Mathematica commands"
2) What Nathann suggested, but wrapped inside some very rigid structure, so the
full text can be extracted. Again, I'm not going to argue about the wording, but
lets for this discussion keep it to "Notes about the relationship between
Mathematica and Sage" and "End of notes about the use of Mathematica"
So for Sage's factor(), we would have something like:
**Related Mathematica commands:** Factor FactorInteger FactorList
FactorSquareFree FactorSquareFreeList FactorTerms FactorTermsList
**Notes about the relationship between Mathematica and Sage**
FactorInteger[] is used in Mathematica to factor only integers, with several
other commands used to factor polynomials. In contrast, Sage, factor() is used
to factor both polynomials and integers.
In both systems, testing if a number is prime is considerably quicker than
factorising that number, so much larger integers can be checked for primality,
that what can be factored in a reasonable amount of time. In Mathematica, the
command PrimeQ[] is used to test whether a number is prime. In Sage, is_prime()
can be used to test if a number is prime.
** End of notes about the use of Mathematica **
Then everything between:
**Notes about the relationship between Mathematica and Sage**
and
** End of notes about the use of Mathematica **
could easily be extracted with a script. (You don't need to have the *'s. I only
put that to indicate what text would be in a rigid format.) The notes could be
split into multiple paragraphs - one could still extract it with a shell script.
As long as that information is in a rigid format, extracting it is very easy. As
soon as people just write what they fancy on the day, then it would be an
impossible task.
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.
I was thinking of adding them in the doctest, being specific to the command. So
in the above case, we might add
Related external references:
http://en.wikipedia.org/wiki/Factorization
http://en.wikipedia.org/wiki/Integer_factorization
http://mathworld.wolfram.com/Factor.html
http://mathworld.wolfram.com/PrimeFactor.html
http://mathworld.wolfram.com/PolynomialFactorization.html
End of related external references:
Again, if the structure was rigid, these could be extracted with a script and if
necessary one create hyperlinks, which people could click.
Cheers,
Johan
Dave
--
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
