[Axiom-developer] Documentation and HyperDoc Future

[Martin Rubey]

"Fabio S." <address@hidden> writes:

> >>> I think you should try Axiom's hyperdoc browser. (Unfortunately
> >>> it is only currently available in the linux version of Axiom.)
> >>> Hyperdoc provides a lot of useful information of this kind for
> >>> the new Axiom user.
> >>>
> >>
> >> Fortunately, I use only linux!
> >> Anyway, I must say that I never liked the Hyperdoc (moreover,
> >> it crashes quite often).
> >
> > Again, I agree. I also do not use Hyperdoc very much. My experience
> > is also that it often crashes, although I am not yet able to
> > document a specific sequence which causes a crash. 

That's very strange. I use hyperdoc extensively (really), and I did not see it
crash *once* yet -- provided I did not press the forbidden buttons like
"dependends, "users", "uses" and maybe a few others.

> > If we could report and reproduce such bugs, then it should not be difficult
> > to correct the problems. But even then, I do not much care for the "look"
> > of the user interface. 

Well, I don't *mind* the look of the user interface, but, as you probably know
by now, I've been shouting for a long time: replace HyperDoc, AxiomUI,
MathAction by a single facility.

I must say that I find it a little sad that -- although the above proposal is
certainly doable within a few weeks, maybe months time -- nobody has found time
to help Ralf (whose ALPROSE is certainly the way to go).

> > There have been much discussion and some programming work to replace
> > Hyperdoc with a modern web browser interface, but so far we do not have a
> > good replacement for Hyperdoc.
> 
> I can also add that with modern dvi viewers which allow searching, I prefer
> to look directly into book.dvi. 

But hyperdoc can do A LOT more than that. Did you ever press the button
"Domains"? Far from most of the domains are covered in the Axiom Book!

> In fact, at present, axiom on my machine is
> an alias to "axiom -noht"...

Oh dear. 

> >> My preferred type of documentation is of more "synthetic" type. From this
> >> point of view, I like very much Mathematica help system.

As far as I know Mathematica, it's help browser is not so different from
HyperDoc.

> > From my point of view, it is very useful to have an on line help which
> 1) allows you to look for commands and packages which satisfy a certain 
> pattern;
> 2) gives you the possibility to get on line extensive help (complete syntax,
> maybe some meaningful example, closely related functions, maybe the source
> package) of a command with something natural like
> )? command
> or
> )help command

What you are describing is the basic functionality of HyperDoc browse...

> As I said, from this point of view a good model could be Mathematica, or even
> Mupad: for example, compare the output of
> 
> MuPad         |       Mathematica     |       Axiom
>               |                       |
> -------------------------------------------------------------------
>               |                       |
> ?fibonacci    |       ?Fibonacci      |       )di op fibonacci
> )if           |       ?If             |       )di op if
> 
> and it should be clear what I mean.

But you are comparing different things. ")di op" is not comparable to
"?". Although I do agree that something like this, returning the description
text also provided in HyperDoc should exist.

I sincerely hope that some day my dream of a unified documentation and user
interface format for axiom comes true. If you do have spare time, this would be
just great.

By the way, you mentioned you intend to use Axiom as a teaching tool. Would it
be possible for you to set up a webpage -- or, even better, use mathaction, and
share your .input or .spad files?

Martin