[Top][All Lists]

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

Re: [Axiom-developer] Documentation and HyperDoc Future

From: Martin Rubey
Subject: Re: [Axiom-developer] Documentation and HyperDoc Future
Date: 23 Jan 2006 15:59:33 +0100
User-agent: Gnus/5.09 (Gnus v5.9.0) Emacs/21.4

"Bill Page" <address@hidden> writes:

> On January 22, 2006 11:51 AM Martin Rubey wrote:
> > 
> > provided I did not press the forbidden buttons like "dependents, "users",
> > "uses" and maybe a few others.
> Are you making a joke? What do you mean by "forbidden buttons"?

The said buttons access functionality which is currently not working. Issue

> > I've been shouting for a long time: replace HyperDoc, AxiomUI, MathAction
> > by a single facility.
> Usually shouting is not very effective in open source projects. :)

Very true. Still I think I should concentrate on the maths, while I can't
resist telling everybody how I'd like the IDE (integrated documentation
environment) to work.

> > 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).
> Your point of view seems quite unreasonable to me. 

Oh. :-(

> How much time have you devoted to this concept (not counting the shouting ;)?
> I also would like to see more people working on Axiom development but I think
> we have to lead by setting an example, not just by making suggestions. I
> personally doubt that it is "doable within a few weeks", but if you think so
> then perhaps you could help by creating a prototype to show how it might
> work.

> How can ALPROSE be used to do this? What about navigation?  What about access
> to the Axiom database? What about conversion of the existing Hyperdoc
> material?

I am not saying anything but that the *format* of the documentation should be
the format proposed by Ralf (albeit for a slightly different purpose).

I mentioned the design problem remaining already: Currently the databases
contain the documentation (extracted from the spad files at compile time) in
HyperDoc format. However, we need a way to have it ready in various different
formats. I guess that LaTeX -> HTML or MATHML or the like is too slow to be
convincing. Maybe for a prototype it would suffice. We would need 

* a script that converts something like the following 

    if \adthisname{} x then ...
    \adparameter{x: %} Element to be tested.
  \begin{addescription}{Tests whether its argument is \adname{0}.}
    The boolean value of \adcode$\adthisname{} x$ is identical to the
    test \adcode$x \adname[MyPrimitiveType]{=} \adname{0}$ in the type, but
    might be implemented more efficiently.
    Note that one would usually not use this function on floating
    point types. A zero test might fail because of small errors
    introduced during a computation.
<<exports: MyAdditiveType>>=
zero?: % -> Boolean;
<<defaults: MyAdditiveType>>=
zero?(x: %): Boolean == x = 0;

  into html/mathml/jsmath via tex4ht. 

* a javascript applet that allows querying the database, extracts snippets like
  the above, converts them with the said script into HTML, and displays it in a

(In fact, I thought about this in public already once: )

> > 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!
> Perhaps that is a criticism more appropriate to the Axiom Book, then to the
> choice of user interface?

Well, partly. The Axiom Book contains a carefully chosen subset of the domains
shipped with Axiom. I don't think that the printed documentation should strive
to contain everything, it would be too much. The online documentation should,
and it should be printable, but probably not be sold in a bookstore.

Still, how would you get the result from pressing "Domains" when viewing the
category "Field" in HyperDoc by a search in the dvi file? Searching for "Field"
will not suffice, I guess.


reply via email to

[Prev in Thread] Current Thread [Next in Thread]