> 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 _______________________________________________ Axiom-developer mailing list Axiom-developer@nongnu.org http://lists.nongnu.org/mailman/listinfo/axiom-developer
