cyclops@TAMUNIX.BITNET (Glenn Vanderburg) (02/28/89)
All this talk about code documentation has reminded me of a rather interesting idea I ran across a while back in some documentation for Donald Knuth's WEB system. (For those of you who aren't familiar with it, WEB is a system for integrating Pascal code with TeX documentation. It also offers some extra support for modular coding which is precluded by ordinary Pascal syntax. See Jon Bentley's "Programming Pearls" column, CACM, May and June 1986, for a good introduction. WEB is certainly not without problems, but it is a fascinating concept, and it's hard not to be impressed when you can pick up a listing of a program as large and complex as TeX, start reading it from the beginning like a novel, and understand it easily). The thing about WEB that has had the biggest impact on me is something that Knuth just hints at, and never explicitly states (so far as I know). The title of the WEB manual is "The WEB system of structured documentation," and while that's the only mention of the phrase "structured documentation," I think that it's the pivotal phrase of the entire document. It really makes a difference to see the central task of programming as documentation. Now, the main audience is readers, not the machine. And, with a little discipline, you can structure the documentation so that the machine can understand and act on the same document. And you don't even have to use WEB to do it! Thoughts? Not a panacea, certainly, but it's a very intriguing idea. Glenn Vanderburg cyclops@tamunix.bitnet
simpson@minotaur.uucp (Scott Simpson) (03/02/89)
In article <8902271704.AA12256@ajpo.sei.cmu.edu> cyclops@TAMUNIX.BITNET (Glenn Vanderburg) writes: >The thing about WEB that has had the biggest impact on me is something >that Knuth just hints at, and never explicitly states (so far as I >know). The title of the WEB manual is "The WEB system of structured >documentation," and while that's the only mention of the phrase >"structured documentation," I think that it's the pivotal phrase of >the entire document. It really makes a difference to see the central >task of programming as documentation. Now, the main audience is >readers, not the machine. And, with a little discipline, you can >structure the documentation so that the machine can understand and act >on the same document. And you don't even have to use WEB to do it! > >Thoughts? Not a panacea, certainly, but it's a very intriguing idea. I like WEB and I think mixing program and documentation is a good idea. I wish there was an Ada version so I could experiment with it. I don't ever use Pascal any more. I imagine an Ada version would have slightly different WEB control sequences though since the semantics of the two languages differ. I have some problems with it though. First, WEB utilities (i.e., tangle, weave) act as preprocessors. I usually don't like preprocessors because you lose semantic information that debuggers and other tools need. This is one reason I thank God Ada does not use a preprocessor and Stroustrup added constants to C++. With WEB, you can get errors at 3 levels: from WEB control sequences, from TeX control sequences and from Pascal code. Trying to find where the errors are coming from can be somewhat confusing. I have another granularity problem with the way Knuth divided up the code in TeX. The code is divided up into so many small chunks that it is hard to keep track of what goes where. He has devised an indexing scheme (i.e., the <...> notation) for keeping track of all these divisions but I still think the level of "exploding" code needs further investigation. I like just putting comments at the beginning of procedures/functions. Other people differ. I think the name WEB for the TeX code is an accurate description though! [[ Perhaps this discussion should move. I leave it to someone else to do this.]] Scott Simpson TRW Space and Defense Sector oberon!trwarcadia!simpson (UUCP) trwarcadia!simpson@oberon.usc.edu (Internet)
davidg@oravax.UUCP (David Guaspari) (03/02/89)
Someone interested in a version of WEB for Ada might be
interested in a paper by Norman Ramsey,
Building a language-independent WEB
which will be appearing in the CACM (I'm not sure when). This
paper is also available as Tech Report 17-5 from
Odyssey Research Associates
301a Harris B. Dates Drive
Ithaca, NY 14850-1313horst@pcsbst.UUCP (horst) (03/16/89)
The University of Oldenburg has done an implementation of WEB for Ada in Ada. It is distributed freely if you wish. (Karl, do you want a copy?) Horst
slutz@hpdtl.HP.COM (Eric A. Slutz) (03/21/89)
Can you make the Ada-Web avalible to the net?
horst@pcsbst.UUCP (horst) (04/13/89)
In article 1122 of comp.lang.ada Eric A. Slutz asks for AWEB.
If no unexpected difficulties arise, AWEB should be on the Ada
Software Repository soon. As you need a running TeX to output the
generated .tex files, maybe you have enough work until then :-).
Regards,
Horst