Motivation for FunnelWeb

During 1986, I was exposed to Donald Knuth'sDonaldKnuth WEB literate programming system in the form of Jon Bentley'sJonBentley ıProgramming Pearlsprogramming pearls column in ıCommunicationsCommunications of the ACM of the ACMBentley86. This prompted me to obtain a copy of the report on the Web systemKnuth83 and to try out the program which had been installed on the local Vaxen.

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). This was exciting.

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

• Web can only process PascalPascal programs.

• Web can produce only one output file. In many instances it is desirable to generate more than one output file. For example, when programming in Ada, it is desirable to write a package specification and a package body together in the same file.numberoutput files

• 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.indentation

• 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 RazorOccam'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 can process programs in any language or any combination of languages at the cost of typesetting the text in tt font.

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. In the end, time pressures forced me to take the back door and hack up a TEX document file generator. This compromise has found its way into FunnelWeb V3.0 which is still reliant on TEX, although V3.0 at least encourages input files to be typesetter independent. It is hoped that future versions of FunnelWeb will include more sophisticated typesetting facilities.