Re: [Axiom-developer] Asq rewritten

[Martin Rubey]

Dear Waldek,

Waldek Hebisch <address@hidden> writes:

> There were many plans to rewrite various parts of Axiom.  I decided
> to actually rewrite one part: the asq program :).

Did you see the mail where I set a price? Well, I repeat the relevant bit here
anyway, slightly modified to make the intention clearer:

(Modifications in [...])


**OLD MAIL*********************************************************************
I think it's time to set a price again. I'll pay 100$ anyone who writes a new,
or modifies an existing program, that displays [in a standard webbrowser] the
documentation of a +++ environment (and only this bit of documentation) as
generated by ALLPROSE, on demand, i.e., using a web interface similar to that
Tim provided.

To get started, do the following

----------------------------------------------------------------------

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

cd combinat/trunk/combinat

notangle -t8 Makefile.nw > Makefile

make VARIANTSTOBUILD=axiom

cd lib

for f in $(ar t libcombinatax.al); do ar x libcombinatax.al $f; done
for f in $(ar t libcombinatax.al); do echo ")lib $f" >> combinat.input; done

cd ../src

axiom

-- now everything of combinat is available. To generate a libdb.text say

)se co args "-O -Fasy -Fao -Flsp -laxiom -Mno-AXL_W_WillObsolete -DAxiom -Y 
$AXIOM/algebra -i ../include"

)co csseries
----------------------------------------------------------------------
(very likely, there is an easier way to generate the libdb file.)

To explain the process a bit: (Ralf, please correct me if I'm wrong)

  make VARIANTSTOBUILD=axiom

extracts using noweb documentation and code from the source files, for example
series.as.nw. All of the code and the api description (i.e., everything between
\begin{+++} ... \end{+++} ) is put into a file csseries.as.

")co csseries" is one way to extract the +++ strings and write them into
libdb.text.

The best thing would be, of course, if one could simply call tex4ht on the
individual +++ strings. One would have to write a suitable LaTeX preamble, of
course, that \usepackages the appropriate style files. However, I do not know
how hyperlinking will work then. (In fact, I don't even understand hyperlinking
within ALLPROSE, and Ralf begs me to read the documentation since a few
months...)

Maybe it also makes sense to run a preprocessor over the literate
program. I.e., to modify ALLPROSE so that preprocecessed LaTeX (for example
html) is put into a database. But I would like the other solution better.

It would already be a great thing if doc could be displayed without
hyperlinks. That shouldn't be too hard, I believe.

**END OLD MAIL*****************************************************************

Here is a bit of the generated libdb.text:


dDataStream`1`x`(CoercibleTo(OutputForm))->etc`(T)`DATASTR`\begin{adusage}      
T == Integer      s: \adthistype{} T := \adname{stream: T -> %} 0;      s := 
\adname{stream: Generator T -> %}(generator [1, 3]);      g: \adtype{Generator} 
T == generate for i in 2.. repeat yield i;      s := \adname{stream: Generator 
T -> %} g;    \end{adusage}    \begin{addescription}{Implements an infinite 
array.}      The domain \adthistype{} can be abstractly seen as an infinite     
 array. However, to make thi----s data structure finite, it is more      
appropriate to view it as a pair $(a, g)$ of an      \adcode$\adtype{Array}(T)$ 
and a \adcode$\adtype{Generator}(T)$.        Like \adtype{Array}, \adthistype{} 
is 0-based.    \end{addescription}



Non-standard environments and commands:

adusage and addescription are environments, adname, adthisname, adtype,
adthistype commands defined in combinat/trunc/allprose/aldordoc.sty.nw.

Below is a very short description, to see the full thing say

-------------------------------------------------------------------------------

cd combinat/trunk/combinat

make include-allprose-documentation colored html

konqueror doc/combinat.html

-------------------------------------------------------------------------------
and go to Section 33.


The short description:

adusage: explains how to use the constructor/operation by example

addescription: the argument of the environment is a one-line description, the
         body a more detailed one

\adname: markup for a constant or operation. Should be hyperlinked to the
         appropriate constant, operation.

\adtype: markup for a type constructor. Should be hyperlinked to the
         appropriate type constructor.

\adthisname: expands to the constant or operation we are currently looking
         at. (should not occur if we are just defining a type...)

\adthisname: expands to the constructor we are currently looking at, or, if we
         we are just defining a constant or an operation, the constructor it
         belongs to. In the example above, it expands to DataStream.


You can find the DataStream example properly typeset in Section 22.1.

To see an operation, look at stream: Generator T -> % (roughly five pages below
the definition of DataStream, which, in libdb.text reads as follows:

ostream`1`x`(Generator(T))->_$`dDataStream(T)``\begin{adusage}      T == 
Integer;      g: \adtype{Generator} T := generator [2,4,6,7];      s: 
\adthistype{} T := \adthisname{} g;    \end{adusage}    \begin{adparameters}    
  \adparameter{g: Generator Integer} A (finite or infinite)      generator that 
computes the next values of the stream.    \end{adparameters}    
\begin{addescription}{Construct a stream.}      The function constructs the 
stream      \begin{gather}        (g_1, g_2, g_3, \ldots----)      \end{gather} 
     or (informally) the infinite array      \begin{adsnippet}        [x for x 
in g]      \end{adsnippet}      where $g_i$ is the $i$-th element generated by 
the generator $g$.        In case the stream $g$ is finite and generates $n$ 
elements then      the result is      \begin{gather}        (g_1,...,g_{n-1}, 
g_n, g_n, g_n, \ldots).      \end{gather}    \end{addescription}    
\begin{adremarks}      It is allowed to call \adthisname{} with a generator 
that does not      --ge--nerate any element, but the resulting stream may not 
be ask to      reveal any of its entries, since there are none. It is basically 
     the same to say \adcode$\adthisname(generate)$ and      
\adcode$\adname{new}()$.    \end{adremarks}



It is a mystery to me how Ralf did the linking magic. Maybe he or the
combinat.aux file can help...


Martin