Literate programming

Let us change our traditional attitude to the construction of programs: Instead of imagining that our main task is to instruct a computer what to do, let us concentrate rather on explaining to human beings what we want a computer to do.
Donald E. Knuth, "Literate Programming (1984)" in Literate Programming. CSLI, 1992, pg. 99

Literate Programming is a term coined by Donald E. Knuth to describe a mechanism he devised for weaving both code and its documentation into the same document. For Knuth, the primary content is the documentation, with the program implementation just being one particular example of what is described in the documentation. Many variations on the original concept of literate programming have been undertaken. Those that utilize some tool to separate the program code from the surrounding documentation are closest in spirit to the original idea. Approaches in which the master content is the program, and documentation is extracted from annotations within code comments, have proven more popular than the literate programming method where the documentation is the master, or at least, is on equal footing with the program code.

Dynamic languages like Tcl afford other possiblities, such as ycl::proc::checkargs, in which the documentation for a procedure is written in such a way that it is used at runtime to decide how to process the arguments to a procedure.

Reference

literateprogramming.com

Literate Programming Systems In Tcl

docstrip and tclldoc
The Simple Library
framework to support nearly literate programming doc
Holon - a simple programming system
written in Tcl, similar in some ways to Leo, code is stored in a database
Eric's Literate Programming
real literate programming written in Tcl (with its own markup language)
Literate Programming in asciidoc
written in Tcl, uses asciidoc code blocks as source, can generate DocBook documents

Other Literate Programming Systems

Leo
written in Python, formerly using Tkinter, now using PyQT, provides a GUI for organizing, navigating, and weaving the code and documentation of a project.
IPython Notebook
An interactive computational environment in which code executation, rich text, mathematics, plots, and rich media can be combined.

Documentation Extraction Systems For Tcl

See Source Documentation Tools

Discussion

AM: has some experience using Will Duquette's "expand" for the purpose of intermixing test code with explanatory descriptions. The idea was elegant (IMHO), but requires more elaboration. (Wondering if this will turn into pet project #53 or not ;)


YOSIFOV: New Tcl based, very small (StartPack) LP tool (not for WiKi, but for any programming language: generates flexible document and any number of source code files. Documentation/program (as usual in LP) is one file, like article, where programmer use special markup-commands, all other (references, TOC, index, so on) are generated automatically. Project home is here: http://code.google.com/p/tclp/

See Also

literate programming in a wiki
Source Documentation Tools