Re: [Axiom-developer] Documentation and HyperDoc Future

[Martin Rubey]

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

> 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 

\begin{+++}
  \begin{adusage}
    if \adthisname{} x then ...
  \end{adusage}
  \begin{adparameters}
    \adparameter{x: %} Element to be tested.
  \end{adparameters}
  \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.
  \end{addescription}
  \begin{adremarks}
    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{adremarks}
  \begin{adseealso}
    \adname{0}
  \end{adseealso}
\end{+++}
%CCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCC
<<exports: MyAdditiveType>>=
zero?: % -> Boolean;
@
%TTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTT
%CCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCC
<<defaults: MyAdditiveType>>=
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.

  
(In fact, I thought about this in public already once:
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