2.2 Motivation For FunnelWeb

During 1986, I discovered Donald Knuth's WEB literate programming system in the form of Jon Bentley's Programming Pearls  column in Communications of the ACM  [Bentley86]. This prompted me to obtain a copy of the report on the Web system[Knuth83] and to try out the WEB program.

WEB was the best system that I had seen for producing printed and online, inline documentation. To me the most extraordinary aspect of the system was its success despite the fact that it had been built into the horribly antiquated file/batch processing systems that we all know and love (and use). I had imagined sophisticated documentation systems before this time, but had always assumed that they would be parts of complex programming environments. Knuth showed that, to some extent, it can be done using 1960s software technology (excluding the 1980s typesetting technology).

The WEB system was enticing and promising, but to me suffered from many drawbacks, many of which Knuth had categorized as advantages. The following highly subjective list of disadvantages formed a springboard for the construction of FunnelWeb.

• WEB can only process Pascal programs.
• WEB can produce only one output file. In many instances it is desirable to generate more than one output file.
• WEB enforces Knuth's individual style of indentation. WEB supplies commands to over-ride the automatic indentation, but it is an uphill battle and the code becomes clogged up with format directives.
• WEB does not cater for non-standard Pascal programs. In particular, all identifiers are truncated to about eight characters.
• WEB formats the program output file into a form that is unreadable to humans.
• WEB does not provide an include facility. This was considered a feature essential for supporting macro libraries.
• WEB provides macros with at most one parameter. Knuth describes a hack that can extract a multiple parameter macro facility from a single parameter one, but it is hardly satisfactory.
• WEB does not provide conditionals.

Most of these objections boiled down to two points: that WEB is far too specialized, and that Knuth's "Occam's Razor" had cut too far. What I wanted was a documentation system that employed all the same principles as WEB but was far more general. The result was FunnelWeb V1 which could process programs in any language or any combination of languages at the cost of setting the text in tt font instead of typesetting it in a language-specific way, as WEB does.

Originally, it was intended that FunnelWeb would be typesetter independent as well as language independent. It was intended that a format file consisting of a set of productions describing how the document file was to be formatted would be handed to FunnelWeb along with the input file. However, time pressures forced me to take the back door and hack up a TeX document file generator. In version 3.2 an HTML generator was added.