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

[root]

> Nevertheless, my contribution do the documentation discussion is
> non-ALLPROSE. Did you consider using an "javadoc" style for
> documentation. E.g. doxygen is a mature and flexible tool aimed primary
> at C++ but extended to some more languages. The output formats include
> html, latex, and rtf. Furthermore, doxygen can be "easily" extended by
> using a preprocessor. I used a simple (and short) perl script to
> generate a doxygen documentation for a bunch of VHDL source files (VHDL
> is a language for hardware description of digital circuits) by mapping
> part of the VHDL syntax to C++. In terms of documentation, the Axiom
> Types correspond to C++ objects. Furthermore, both languages have public
> exports and private functions, ...

yes, i wrote a document on the internal details of the Jikes compiler
using doxygen and i have used javadoc extensively on many projects.
both are excellent tools for documentation. but we're not trying to 
write documentation.

the choice of noweb-style programming is more a matter of philosophy
than technical details. the hardest and most subtle part of the choice
is a change of mindset. it really can be distinguished by the difference
between the words "document" and "literature". "documents" are what 
programmers write to help other programmers. "literature" is what you
write when you want to communicate with another person above the level
of implementation.

after a few false starts i eventually settled on knuth's style.
most scientists know latex and use it to write technical papers.
noweb only adds a trivial amount of syntax to latex and is an
easy learning curve. so for computational science, latex is a natural
choice.

and latex is widely used to write books (aka literature) so for 
writing mathematics "literature" it is also a natural.

the hardest part is that it really is a cliff-like transition to 
do literate programming. it is NOT the same as hacking the source
and adding some words around it. more like writing the ideas and
then reducing them to practice. it took me a couple years to 
finally realize the subtle but vital difference. it is the same
insight a programmer gets when he first learns lisp, mistakenly
thinking that lisp is "just another language". at some point there
is a "religious conversion" when, having seen the light, you can
only mourn the wasted years of non-enlightenment :-)

literate programming is not the same as documentation.

t