Re: [Axiom-developer] browser front end, statement of plans and progress

[Martin Rubey]

Dear Tim,

Although I'm happy that you are working on the documentation issues, I must say
that I'm extremely concerned about your approach to

> 2) replace hyperdoc

and, maybe most importantly, about our (i.e., mine and your) communication with
respect to these things. I very much hope that I misunderstood you.

As you know, Ralf has written an excellent environment for literate programs,
called ALLPROSE. (Environment is not entirely correct, in principle it consists
of some programs that convert your literate program into documentation and
code, plus some LaTeX environments that are not so different from HyperTeX's
ideas, but in contrast to them very well documented. I'd say that they are as
easy to use.)

Meanwhile, I use his conventions also to document my spad code, although I
cannot use all features of ALLPROSE there. (I hope everybody knows by know that
we managed to use ALLPROSE directly for Axiom programs written in Aldor, in
this setting, all of ALLPROSE works very nicely)

Some time ago I asked you whether asq could be used to fetch the documentation
information also dynamically, i.e., after a file has been compiled within the
axiom environment. This would be important to mimick a strong feature of
HyperDoc: After compiling a bunch of spad files with ")co file", all the
documentation is found by HyperDoc!

I faintly remember that you answered, that this would be easy, but I never
heard any further response.

> Hyperdoc used to have its own language for display but this is dead and
> gone. I've been recoding the hyperdoc pages into html so they use a standard
> format. This will allow anyone to code web pages without any training. It
> should also allow us to embed pamphlets as pdf in pages.

I am very much concerned about this paragraph. In fact, if html is going to be
used for documentation rather than LaTeX, I'll immediately quit the project. I
cannot find any sane reason to give up these concepts from ALLPROSE and
HyperDoc. Finally, I don't see any reason to embed pdf in pages when we can
generate html automatically. Browsers are made to display html, not pdf, I'd
guess.

> The low level task is to recode the hyperdoc info into html and javascript
> (in process),

Could you please be more specific here? What do you mean by hyperdoc info? The
api currently written within the ++ environments? The example pages? If this is
the case, you have nearly lost me. Why don't you use tex4ht to translate
HyperTeX to html?

Dynamic api-documentation given the literate program is an absolute must for
me. To this end, given the name of a function or constructor, a hyperdoc
replacement would need to be able to

* fetch the +++ environment corresponding to this constructor from the literate
  program or a database compiled from the literate program, as it is done now
  (libdb.text)

* render the documentation written therein, hyperlinked of course.

Here is an example what is currently put into libdb.text:

cFormalPowerSeriesCategory`1`x`(Ring)->Category`(R)`FORMALP`\begin{adusage}
Foo: \adthistype{} Integer with {...} == add {...}    \end{adusage}    
\begin{addescription}{The category of formal power series.}      \adthistype{} 
is the category of \useterm{formal power series} of      the form      
\begin{gather}        f = \sum_{n=0}^\infty {f_n x^n}.      \end{gather}    
\end{addescription}

This was generated from:

\begin{+++}
  \begin{adusage}
    Foo: \adthistype{} Integer with {...} == add {...}
  \end{adusage}
  \begin{addescription}{The category of formal power series.}
    \adthistype{} is the category of \useterm{formal power series} of
    the form
    \begin{gather}
      f = \sum_{n=0}^\infty {f_n x^n}.
    \end{gather}
  \end{addescription}
\end{+++}

Of course, HyperDoc complains when trying to display that:

Unknown begin type \begin{adusage} 
While parsing T71
Trying to print the next ten tokens
\} Foo \: \ 1027  \{ \} Integer with \{ \. 

An important remark is that, apart from being put into libdb.text, the above
documentation snippet also appears in the "full" documentation, properly
hyperlinked and colored, of course.

--excursion--------------------------------------------------------------------
If you want to see that file, say

svn co svn://svn.risc.uni-linz.ac.at/hemmecke/combinat/trunk

cd combinat/trunk/combinat

notangle -t8 Makefile.nw > Makefile

make dvi

or

make colored dvi

or, if you have tex4ht installed,

make colored html

--excursion--------------------------------------------------------------------

Tim, maybe you could try to build upon these things? Maybe you could use the
above documentation snippet to elaborate on your ideas: How would you like to
have this written? (I hope, not html?) I guess that it would be possible to
convert it to some other format (automatically, of course), before it is put
into the (currently libdb.text) database. In fact, I think that this is the
place where we would need somebody with your knowledge and abilities. Maybe you
can look at ALLPROSE and find out how to turn it into a hyperdoc replacement.

> factor in new function for handling pamphlets and hyperlinking to non-axiom
> data, and using either mathml or some other smooth symbol output.

Note that ALLPROSE can output a huge variety of formats: dvi, pdf, ps, html,
mathml, html+jsmath, ... (Of course this is a half lie, since really ALLPROSE
knows only LaTeX. But Ralf's command of tex4ht is quite good...)

After having said "make html", "cd doc" and "myfavoritebrowser combinat.html",
click on "FormalPowerSeriesCategory" (it's Section number is 11.2) for an
excellent example!

> By design all of the C code disappears and all work is done inside the lisp
> image. 

I dislike C and like Lisp, too. But I have the feeling that throwing away
C code should not be a goal per se.



I very much hope that I could make my concerns understood.

Martin