Re: [Axiom-developer] Using ALLPROSE for SPAD programming

[Ralf Hemmecke]

> First of all, I want to point out that I don't want to advocate against
> ALLPROSE for documentation, which is in fact an interesting development
> framework.
> Nevertheless, my contribution do the documentation discussion is
> non-ALLPROSE. Did you consider using an "javadoc" style for
> documentation.

Of course. You certainly know about the +++ comments. These things have 
been invented before Java came into existence. The only problem with 
Aldor is that there is not yet a proper tool to make use of this data.

ALLPROSE hast \begin{+++} ... \end{+++} for that.

> E.g. doxygen is a mature and flexible tool aimed primary
> at C++ but extended to some more languages.

Yep, doxygen is too much tailored for C/C++. If you make it work for 
Aldor, it might be worth another try.

But as Tim suggests, that is not the point of literate programming. LP 
is here to express your ideas and illustrate these ideas by real (in 
contrast to pseudo) code. So you basically write a research article (or 
so). In that sense I fully support Tim and Knuth.

But as you can see with my \begin{+++} ... \end{+++} environments, I 
also strongly believe that for using other peoples work it is often 
quite sufficient if you know about the API of what that library/program 
does on which you want to build. You do not usually want to read 
thousands of pages and books before you are able to write one single 
line of code.

I, for example, would be quite happy if someone writes a library for 
factorization of multivariate polynomials in an LP style and 
additionally gives me a short API description of what his function does 
and how I have to call it. I am simply not interested in learning all 
the difficult stuff about an efficient implementation and about tricks 
in this implementation to make it even more efficient. I want to use 
factorization. If I ever become interested in the details, I can come 
back to that later.

So my approach in ALLPROSE is to write in an LP style and *additionally* 
provide an API description for those who don't want to delve too deeply 
into the details.

If you can make some tool available that supports such a combined 
approach, I would be quite happy to see them.

But I would never sacrifice the LP approach to doxygen. Doxygen (to my 
taste--correct me if I'm wrong) is only about the API, ie half of the 
story -- if not less.

Ralf