axiom-developer
[Top][All Lists]

## 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
#236.

> > 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.

> 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

\begin{+++}
\adparameter{x: %} Element to be tested.
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.
\end{+++}
%CCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCC
zero?: % -> Boolean;
@
%TTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTT
%CCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCC
zero?(x: %): Boolean == x = 0;
@
%TTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTT

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
frame.

http://lists.gnu.org/archive/html/axiom-developer/2005-12/msg00123.html )

> > 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.

Martin