Next: 1.3 New program documentation Up: 1 Some words on Previous: 1.1 WEB and its
Though many of the initial problems of the WEB system have been solved in some of the clones, their sheer number indicates that none of them is perfect.
One of the most controversial topics in the field of literate programming is pretty printing. There are two questions here to consider. Do we want pretty printing at all, and if yes, how should the pretty printed code look like. While for the first question a rational answer can be found, the second is kind of a np-hard problem of computer science.
From a practical point of view it must be stated that doing pretty printing is possible for Pascal, although a look at the WEB sources will tell you that it is not an easy task to do. Doing it for C is even harder2. Taking into account the fact that weave usually processes only a small piece of code, which itself even mustn't be syntactically correct, it should be clear that pretty printing this code in a complex language like for example C++ will be impossible.
To overcome this problems, special tags have been introduced by the various systems to support the pretty printing routines. But this clutters the program code in the WEB file and even increases the problem of the documentation looking completely different than the source. This can be annoying in a develop/run/debug cycle. As a consequence, the use of pretty printing is discouraged. The only feasible solution could be a simple syntax highlighting instead of pretty printing, as it is done by many editors nowadays.
Even without pretty printing and additional tags inserted into the program source, the fact that the source code usually appears rearranged in the WEB file with respect to the generated source file makes it very hard to extend such a program. A few lines of code laying closely together in the source file may be split up to completely different places in the WEB file. Because every WEB system needs at least some control characters, they must be quoted if used inside the program code. Moreover navigating through a web file with respect to a given program structure is a hard task because of the splitting and rearrangement of functions and declarations. But changes definitively must be applied to the web file, since it is the master copy of all source files. Finally, debugging a program created from a web file resembles debugging a program compiled without debugging symbols.
Another serious problem common to WEB systems is their ``one source'' policy. While this may help to hold source code and documentation consistent, it breaks many other development tools like revision control systems and make utilities. Moreover, it is nearly impossible for a programmer not familiar with a special WEB system to maintain or extend code devolved with that WEB.
Even the possibility of giving away only the tangled output of a WEB is not attractive. First of all, it is usually unreadable for humans3 and second this would break the ``one source'' philosophy. It seems that most of the literate programming projects realized until now have been one man projects. There is only one paper from Ramsey and Marceau[RamMarc] which documents the use of literate programming tools in a team project. Additionally, some references can be found about the use of literate programming for educational purpose (see [Childs] and [ShumCook]).
The general impression confirms Van Wyk's observation[VanWyk] ``.. that one must write one's own system before one can write a literate program, and that makes [him] wonder how widespread literate programming is or will ever become.'' The question he leaves to the reader is whether programmers are in general to individual to use somebody else's tools or if only individual programmers develop and use (their own) literate programming systems. I think the question is somewhere in between. Programmers are usually very individual and conservative concerning their programming environment. There must be superior tools available to let them switch to a new environment.
On the other hand, integrated development environments (IDEs) evolved strongly during the last years and they now offer sophisticated navigation, syntax highlighting and online help capabilities for free, thus making many of the features of a WEB system, like indexing, cross referencing and pretty printing become obsolete. Last but not least the will to write documentation in a formatting language like TEX or LATEX using a simple text editor is constantly decreasing in the presence of WYSIWYG word processors.