axiom-developer
[Top][All Lists]

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

 From: Ralf HEMMECKE Subject: Re: [Axiom-developer] Re: literate programming pamphlet files for MathAction Date: Thu, 30 Sep 2004 15:56:43 +0200 User-agent: Mozilla/5.0 (X11; U; Linux i686; en-US; rv:1.7) Gecko/20040616

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