The Theory behind Cocoon

(The author, to tentative applause, ascends his soapbox...)

Documentation is a tricky business. Too much or too little documentation is unusable. Just the right amount--but poorly organized--is almost as bad. On the other hand, good organization doesn't guarantee a good visual design in the presentation. And even if all of these needs are met, if the documentation doesn't have some form of index and cross-referencing capabilities it will still be difficult to use.

Cocoon uses the World-Wide-Web (WWW or simply, Web) as a vehicle for delivering documentation. The capabilities of HTML provide the basic services required to meet the needs outlined above. Coocon organizes the information provided in C or C++ header files into a liberally cross-linked hypertext document that hopefully affords all of the most important navigational aids. It also provides a visually cohesive, consistent, and (hopefully) appealling visual presentation.

It is assumed that the C++ header files contain complete information on the usage of the class. This assumption seems to be safe, being supported by the best engineering practices and theory regarding the necessity of separating implementation from interface: the header file specifies the interface, and the corresponding .cpp or .cxx file specifies the details of the implementation. In practice, this split is not so clean as it seems, but provides a conceptual approach that Cocoon can exploit. In the sense that headers are strictly confined to ASCII text, they cannot contain complete information, but with the added use of HTML, the header files can contain the graphical and referential capabilities needed.

Of course, the idea of extracting documentation from source code is not new. It has as its origins some of the pioneering work in literate programming by Knuth, in his development of TeX and WEB (not related to the Web). C++ class browsers provide some of the organized cross-references facilities that are needed between classes. The cxx2html utility produces web pages that are similar to those produced by Cocoon.

Cocoon attempts to combine the best aspects of these three, while culling out their weaknesses. The weakness in most literate programming practices is that the embedding of formatting directives in the code tends to make the code itself extremely difficult to read. And most literate programming systems seem to ignore all of the structural information that is provided by the language itself. Class browsers are useful, but provide no hooks into the documentation for the artifacts being browsed. And the cxx2html utility requires very rigid formatting constraints on the code.

One of Cocoon's main goals is to allow the original source code to be free of distracting or visually cluttering text that exists only to support Cocoon. When it requires the existence of sentinel strings, Cocoon generally allows user customization of the string, or tries to make it as unobtrusive as possible. Source code should be source code. That's what we, as programmers, generally want to work with. It is also the lowest common denominator: we may or may not have the freedom to use a literate programming system, or other commercial tools for browsing.

It is hoped that Cocoon can be a practical tool for the delivery of informative, browsable, and easy-to-read documentation.

(The author, to stunned silence, exits...)

Cocoon 3.0. Created with pride, distributed with fear... by jkotula@unimax.com