docstrip and tclldoc

These are two tools that combine into a system for literate Tcl programming.

The basic aim of literate programming is to combine source and its documentation into one thing, but it takes a more radical approach to it than the "automatic documentation tools" of which there are thirteen to the dozen -- it is not documentation that should be part of the source code, it is the source code that should be part of the documentation. The documentation should be master, and not the code, because code organisation is anyway rather arbitrary. When you write a Literate Program, you write as you would explain it to another human (or yourself a couple of months later), and the code is put in where it is natural to explain it. The end result? Well, it actually look rather like a Wiki page. ;-)

docstrip is the name of a utility implemented in TeX, as of late also a tcllib module [2 ] [1 ], but perhaps most of all a file format for literate sources. The format is language-independent and has some support for conditional code inclusion, but most of all it provides for including large amounts of comments in such a way that they don't get in the way of the code. The docstrip utility generates "stripped" source files with only code (for use by dumb programs) from the literate "master" sources. The docstrip tcllib module makes it possible to source code directly from a docstrip-format source file, without having to write anything to disk.

A majority of all LaTeX packages, and in particular the LaTeX core itself, is written entirely in docstrip format.

tclldoc is a LaTeX package and document class that provides support for writing docstrip-format literate sources for Tcl programs (and there is also some support for C).