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