Subj : Re: Doc/noDoc? (was: CV, work-history, 91C, CompSci?, Applet? ...) To : comp.software-eng,comp.programming From : Arthur J. O'Dwyer Date : Fri Sep 16 2005 12:42 pm On Thu, 15 Sep 2005, blmblm@myrealbox.com wrote: > > Robert Maas, see http://tinyurl.com/uh3t wrote: >>> From: Chris Hills >>> There is a system called Literate Programming where the >>> documentation and the source are the same thing. ... >>> It never caught on. Started out using Pascal and TeX [...] >> Now if comments in the source file contained directives which were >> compiled to produce separate documentation, as is the case with >> JavaDoc, that would be something entirely different. > > A Google search for Knuth and "literate programming" turns up some > information and examples. http://ankh-morpork.maths.qmul.ac.uk/~saha/mus/advent/advent.pdf is a fun read, although it would give some modern programmers conniptions. (Warning: contains spoilers. ;) [...] > So it's not exactly like Java's Javadoc system, but it's sort of > along the same lines. (Sort of -- with the Java system, the "master > source" is compilable source code, which apparently is not the case > with Knuth's system.) Well, it is the case that a WEB program contains only compilable code --- it's just that the compilation procedure has two phases, and some of the code is also typesetter-ready documentation. :) > Sounds interesting. I wonder if it could still catch on if someone > developed a GUI front end for it. Judging by the example I skimmed, > few people now would be able to write the "master source" (lots of > TeX) without some help, but maybe .... ? Idle speculation, mostly. There are IDEs for literate programming (e.g., Leo), but I don't know whether they actually show the compiled TeX, or how much they help the user versus, say, Notepad. LP is really cool, and produces nice documentation for monolithic medium-sized programs like TeX (and WEB itself), but I don't think it translates well to giant modular programs, or to modern languages like Java. (Not that I'm a fan of Java --- but it does seem to be pretty entrenched in some fields.) -Arthur .