Re: [Axiom-mail] Help in axiom

[Bill Page]

Alasdair,

Let me address your last comment first:

Quoting Alasdair McAndrew:

> Please don't take my comments as overly critical; I am speaking
> from a beginner's perspective.  But sometimes it's hard for
> experts to see things through a beginner's, or learner's eyes. 

On the contrary, I think your views as a beginner are VERY
valuable to us. The more verbose and critical you are willing to
be (within reason of course :), the better. 

> I'm sorry to keep harping on about this same issue, but I do find
> it a real sticking point.  When I attempt to learn a new software
> system (such as a new CAS) I spend a lot of time in the help
> pages, looking at examples, seeing how things are done; reading
> online tutorials and introductions.  I find help in Axiom very
> hard to access.  To use HyperDoc, and to enjoy the benefits of
> decent typesetting in TeXmacs, it seems I need two instances of
> axiom running.  And there is no functions/commands help available
> from the command line (such as there is with Maxima, Maple,
> Mathematica, MuPAD etc). 

That is not quite true. There are commands like the following:

(1) -> )summary
 )credits      : list the people who have contributed to Axiom

 )help <command> gives more information
 )quit         : exit AXIOM

 )abbreviation : query, set and remove abbreviations for
                 constructors
 )cd           : set working directory
 )clear        : remove declarations, definitions or values
 )close        : throw away an interpreter client and workspace
 )compile      : invoke constructor compiler
 )display      : display Library operations and objects in your
                 workspace
 )edit         : edit a file
 )frame        : manage interpreter workspaces
 )history      : manage aspects of interactive session
 )library      : introduce new constructors
 )lisp         : evaluate a LISP expression
 )read         : execute AXIOM commands from a file
 )savesystem   : save LISP image to a file
 )set          : view and set system variables
 )show         : show constructor information
 )spool        : log input and output to a file
 )synonym      : define an abbreviation for system commands
 )system       : issue shell commands
 )trace        : trace execution of functions
 )undo         : restore workspace to earlier state
 )what         : search for various things by name

------

I find the )what, )show and )display commands especially useful. 
But unfortunately in the current versions of Axiom )help is not
so helpful. :-(

I think Hyperdoc is sort of neat, but I have to admit I learnt
everything I know about Axiom without using it at all. Other
people have different opinions about it. 

> And even in HyperDoc, there are very few examples.  For instance,
> I was trying to find the defining polynomial of a finite field. 
> I discovered that there is a command definingPolynomial, but I
> couldn't find any examples on its use, nor a comprehensive help
> page about it.  There are some simple examples in HyperDoc
> (calculus, graphics, linear algebra etc), which is incredibly
> helpful, but there doesn't seem to be this level of help
> available for ALL commands, as I believe there should be. 

Yes, there should be. But Axiom is now a volunteer-based open
source project, so if there is going to be this sort of
documentation it will have to be written by these volunteers. 
Part of the implied obligation of using open source software is
the user's willingness to eventually "give something back" but
contributing in some manner to the project. Writing new and
improving old documentation is one way that new users can easily
contribute while they are learning Axiom at the same time. 

The Axiom Wiki

http://wiki.axiom-developer.org

is an especially easy way to contribute to this process. 

> > From my limited understanding, it would seem that Axiom is
> > superb for the development  and implementation of mathematical
> > algorthms (such as Martin Rubey's Guess package), but that it
> > would go even further, and have greater reach in the mathematical
> > community, with more comprehensive, and more easily accessible
> > help. 

+1. I agree 100%. 

Thank you for your comments. 

Regards,
Bill Page.