Overview

To have documentation for Tcl packages and applications in a single universal format is one of the recurring topics on comp.lang.tcl [13]. Especially given the high variety formats currently employed, like the *roff family [8], HTML [7], and even plain text.

The latest concrete attempt at creating such a format I am aware of was done for the Tcl-Blast! CD. At that time D. R. Hipp created TMML, the Tcl Manpage Markup Language [2], now maintained by Joe English.

The problem I had with TMML is that it is of XML-ancestry [14] and thus heavyweight in the sense that while

1. processing of such markup in pure Tcl is possible (See [15], [16]) it is not very efficient, good performance requires compiled extensions to the Tcl language.

2. editing the markup manually, just with an editor is possible it also causes the viewer to nearly drown in the markup versus the actual text. Reducing this problem requires special editors tailor-made for XML-based markup languages. It should be noted that compared to other DTD's TMML is relatively lightweight in this regard.

Thus the motivation for a more lightweight format was born. Lightweight as in easier to process in pure Tcl, and easier to edit without special tools. And a more tclish appearance would not hurt either.

The result of that motivation are the three doc* formats we describe here.

The remainder of the paper is structured as follows. In chapter 2 we explain the formats, their ancestry and where to find (the Tcl sources for processing) them. In the next chapter, 3 we present the API between the generic core processor and the plugins for the generation of the actual output.

Chapter 4 then discusses advanced topics, namely the automatic creation of keyword indices, tables of contents, parameterization, plugin hooks, etc.

Then we discuss the limitations of the system in chapter 5, provide conclusions in chapter 6, and at last chapter 7 talks about possible future work in this area.