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

[Gernot Hueber]

On Tue, 2006-08-22 at 02:19 -0400, root wrote:
> > 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.

I agree with you, there are no alternatives to latex.

> 
> 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.

I see I have to work on my enlightenment :-)

Thank you for your extensive explanation.

Gernot