[Axiom-developer] Examples on functions

[Tim Daly]

Franz,

> 2. On the download page for release 1.0.8 there is a tarball containing
> examples. Where should they go to make them visible to )help ?

If you put a flat text file in $AXIOM/doc/spadhelp, for example,
create a file called $AXIOM/doc/spadhelp/foo.help then you can say

 )help foo

and it will type out the contents of that file. I have created
about 300 help files (which will also work in Fricas).

If you create new help files I would be happy to add them.


> 3. What is a canonical place to put examples?
> In Axiom (TM) there are some examples shown after the )display command,
> which can be quite instructive.
> I would like to prepare some examples for tensor as well.

In Axiom you can add examples to any function. The examples are just
a special syntax in the comments for a function. So if you have a
function called

   foo: % -> %
     ++ foo(x) returns x

then you can write an example by adding "++X" comments (that is,
the ++ comment followed immediately by an "X" character so you write:

  foo: % -> %
    ++ foo(x) returns x
    ++
    ++X foo(3)

Fricas could add this functionality easily but I'm not part of that
effort so someone will have to pick up the change from Axiom and
add it to Fricas.


On another topic, Axiom algebra is integrating the regression test
files with the algebra sources. If you generate new code I beg you
to write as many tests as you can, especially including a test for
each function. It is very painful for me to try to track Fricas
algebra because all I ever see is the final code with no test
cases, documentation, examples, or pointers to literature. This
makes it very difficult for me (or anyone, actually) to figure
out how to use new algebra.

Tim
Elder of the Internet