Subj : Re: Doc/noDoc? (was: CV, work-history, 91C, CompSci?, Applet? ...) To : comp.software-eng,comp.programming From : blmblm Date : Sat Sep 17 2005 06:24 pm In article , Arthur J. O'Dwyer wrote: > >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. :) Right. I wrote "compilable source code" but meant something a bit more restricted. "My bad", I think. >> 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.) Oh well -- but thanks for providing a little more info. -- | B. L. Massingill | ObDisclaimer: I don't speak for my employers; they return the favor. .