[Top][All Lists]
[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Re: [Axiom-developer] Asq rewritten
From: |
Martin Rubey |
Subject: |
Re: [Axiom-developer] Asq rewritten |
Date: |
01 Feb 2007 09:23:22 +0100 |
User-agent: |
Gnus/5.09 (Gnus v5.9.0) Emacs/21.4 |
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