Re: [Axiom-developer] Re: literate programming pamphlet files for MathAction

[Ralf HEMMECKE]

> > I am very much open to everything, even LaTeX, but there should be 
> > some standard of how to document with ++ and this is missing 
> > currently!

> I'm interested in this thread (though buried under a huge project in 
> work at the moment). The ++ and -- comments were part of the original
>  documentation mechanism. In the long term these will go away.

Why should they go away? Is there a way in Axiom to produce a 
hyperlinked category hierarchy? Such a hierarchy should be generated 
from the actual CODE and not some latex documentation around. If then 
there is some helpful documentation like the ++ comments that describe 
the input/output parameters and approximately what the 
domain/category/function is doing, this would greatly help programmers.

I don't say that this should be the only documentation, but it should 
not go away, because programmers need the exact interface of functions 
in a compact way. Sometimes one knows what a function is doing, but not 
exactly in which order the parameters go and what there exact 
specification is. Putting this information away from the function code 
is dangerous.

Of course with noweb, one can do everything nicely, but the 
documentation is lost for the Aldor compiler then.

> The code generated for the compiler won't contain documentation 
> (since the compiler doesn't care).

This is NOT true for the Aldor compiler. Aldor compiles .as -> .ao -> .o
in a way so that the ++ comments are still extractable from the machine 
independent .ao files. Leaving the ++ information in, would leave the 
option of generating some type of documentation even from .al libraries 
(a collection of .ao file) where the source code is not available.

> There will be new environments in the pamphlet file which will be
> standardized and automatically extracted. Standard environments
> include \begin{testcase} for integrating .input file tests,
> \begin{concept} for tagging the introduction of a new concept that
> needs to be pushed into a semantic network (see the crystal
> discussion in the history), etc. These stylized environments will,
> like \begin{list}, probably have special sub-tags (like \testinput
> and \testresult so testcases can automatically verify the results).

Speaking of testcases, you should have a look at AUnit.

http://www.myjavaserver.com/~tmgisi/aldor-jsp/showPackage.jsp?id=1

Maybe this could be also useful for Axiom. Christian 
<address@hidden> took much effort to translate the JUnit 
idea from Java to Aldor. I think he did great work.

Christian, could you update your website with the newest version. On the 
above site it is still AUnit0.0.1.

> ++ and -- suffer from the usual problem of documentation. programmers
> will not maintain documentation tags. mostly because almost nobody 
> but the programmer ever reads code. we tried to be clever about it 
> and make the comments "live" with hyperdoc (a pre-javadoc idea). 
> unfortunately it still suffers from the fact that embedded comments 
> are not the primary reason for a .spad file. I'm hoping that the 
> pamphlet file (which makes the documentation task primary and coding
> secondary) will encourage computational mathematicians to actually 
> write papers that include working code and programmers to write real
> papers that explain their algorithms.

I agree to a certain extend, but not completely. The pamphlet idea is 
wonderful, but the paper-style text is quite unhandy as a reference 
manual. An additional documentation like, for example,

http://www-sop.inria.fr/cafe/Manuel.Bronstein/libaldor/html/node18.html

would be desirable. Or can this be done already with AXIOM?

Ralf