sdo@linus.UUCP (Sean D. O'Neil) (11/19/88)
I have gotten a bunch of requests asking how to get WEB for Unix based on my original article. All the mail I sent has gotten bounced right back, so I'm posting this rather longish article in hopes that it will satisfy those who sent me mail. I will assume that everyone is familiar with Knuth's amazing typesetting program, TeX. Given that assumption, let me quote from Knuth's memo, "The WEB System of Structured Documentation." The philosophy behind WEB is that an experienced system programmer, who wants to provide the best possible docu- mentation of his or her software products, needs two things simultaneously: a language like TeX for formatting, and a language like C for programming. Neither type of language can provide the best documentation by itself; but when both are appropriately combined, we obtain a system that is much more useful than either language separately. The structure of a software program may be thought of as a "web" that is made up of many interconnected pieces. To document such a program, we want to explain each indi- vidual part of the web and how it relates to its neighbors. The typographic tools provided by TeX give us an opportu- nity to explain the local structure of each part by ma- king that structure visible, and the programming tools provided by C make it possible for us to specify the algo- rithms formally and unambiguously. By combining the two, we can develop a style of programming that maximizes our ability to perceive the structure of a complex piece of software, and at the same time the documented programs can be mechanically translated into a working software system that matches the documentation. ... To put it more crudely, one writes a WEB program that consists of mixed TeX and C code. There exist two preprocessors---weave and tangle. Weave takes a WEB file and turns into a TeX file which, when typeset, is your program documentation consisting of blocks (or modules) of C code, with lots of explanatory text on what each module does and how the modules piece together to form the entire program. Remember, the explanatory text is TeX code you put in the WEB document, so you can use the full power of TeX to describe how the program works (i.e. mathematical formulas, tables, diagrams, font changes, etc.). The other preprocessor, tangle, takes the WEB file and turns it into a C program ready for compiling. We have Berkeley Unix here, and having been running weave and tangle on it. The software I have used is all public domain---we got the C version of WEB by sending mail to levy@princeton.edu. That will give you weave and tangle, plus some documentation written by Levy, and some sample WEB programs. As an aside, Knuth has written that probably the most important thing to come out of the creation of TeX is WEB (Knuth created WEB to help him write the Pascal code for TeX). Sean O'Neil P.S. I'm still waiting to hear if anyone knows about a C-WEB for the Mac.