Waldek and Ralf,
I think you are both agreeing that there is a big gap between structured
metadata in ++ and pure mathematics theory from textbooks although,
towards the end of Waldeks email, you seem to be suggesting there was
not much of a gap?
I think we are all agreed that this structured information needs to be
improved, if there were more users/developers then this could be done,
but I think users are put off by lack of information, so how to cut
through that loop?
I would suggest making any information that does exist available to the
documentation system, for instance by using a script or cut and paste to
move old LP comments to a separate file which can be linked to from the
documentation system. So what I am suggesting is make the information
available in unstructured form now, then structure it when time is
available, on the grounds that any information is better than none.
I think that the most damaging situation is where a potential new user
is looking for an implementation of some mathematics they want to do in
some specialist field. They look through all the domains, there are so
many that it is not clear which they should use, but eventually they
find one that might be what they need. They spend several days trying to
get it to work without success, perhaps they just give up and try some
other CAS or perhaps they ask here and are told that code probably does
not work "but I left it in because it does not do any harm". A simple
one line in some unstructured documentation might avoid alienating users
in this way.
I think there is a lot more, that is not pure maths theory but is
specific to the program about:
* Things that only work is certain cases or have not been fully tested.
* How well is it expected to scale to higher dimensions.
* Unusual notation
* If there is not a canonical form then why was this method chosen.
* Plus all the points Ralf made about usage stuff and so on.
Example 1
---------
The following function documentation was written by Waldek so I will
take that to be your ideal form:
kroneckerSum : (%, %) -> %
++ kroneckerSum(a, b) calculates the Kronecker sum
++ of the matrices a and b.
This has the advantage of using few words (although those words don't
tell me a lot that is not in the function signature).
Do all potential users user the term 'Kronecker sum'? When this was
discussed on this list not everyone here did. perhaps some people just
know it as a Cartesian product for matrix algebra? Perhaps people may
confuse it with 'Kronecker product'.
What happens when this is fed with non-square matrix values? Are there
any error conditions that I should look out for?
What algorithm is used? It might help to say it is something like this:
A (+) B = A (x) Im + In (x) B
Example 2
---------
What does the following do? In what circumstances would I extend my code
from it? Is this what most people would expect a category called Monad
to do?
)abbrev category MONAD Monad
++ Authors: J. Grabmeier, R. Wisbauer
++ Date Created: 01 March 1991
++ Date Last Updated: 11 June 1991
++ Basic Operations: *, ^
++ Related Constructors: SemiGroup, Monoid, MonadWithUnit
++ Also See:
++ AMS Classifications:
++ Keywords: Monad, binary operation
++ Reference:
++ N. Jacobson: Structure and Representations of Jordan Algebras
++ AMS, Providence, 1968
++ Description:
++ Monad is the class of all multiplicative monads, i.e. sets
++ with a binary operation.
Monad() : Category == SetCategory with
--
You received this message because you are subscribed to the Google Groups "FriCAS -
computer algebra system" group.
To unsubscribe from this group and stop receiving emails from it, send an email
to fricas-devel+unsubscr...@googlegroups.com.
To post to this group, send email to fricas-devel@googlegroups.com.
Visit this group at http://groups.google.com/group/fricas-devel.
For more options, visit https://groups.google.com/d/optout.
