Documentation and source code are written into one source file. The compilable source code and the formatted documentation can be extracted from this file with specific utilities.
The information is presented in a reading order suitable for human consumption. The code is automatically rearranged for computer execution.
Origin
The first published literate programming environment was WEB, introduced by Donald Knuth in 1981 for his TeX typesetting system; it uses Pascal as its underlying programming language and TeX for typesetting of the documentation.
The complete commented TeX source code was published in Knuth's TeX: The program, volume B of his 5-volume Computers and Typesetting. Knuth had internally used a literate programming system called DOC as early as 1979; he was inspired by the ideas of Pierre Arnoul de Marneffe. The free CWEB, written by Knuth and Levy, is WEB adapted for C, C++ and Java, runs on most operating systems and can produce TeX and PDF documentation. Other implementations of the concept are noweb and FunnelWeb.
Variants
Less powerful systems to integrate documentation and code are also sometimes labeled literate programming; examples are pod for perl, doc++ for C, C++ and Java, and javadoc for Java.
These however do not quite follow the literate programming philosophy since they typically just produce documentation about the program, such as specifications of functions and parameters, and not documentation of the program source code itself.
Example of a simple literate program
This whole article demonstrates one method of implementing the idea of literate programming. You can copy it and run it using the example literate interpreter on the interpreter page.
Note that all program code in this article is on lines which start with a dash. Everything else is assumed to be comments and will be ignored by the interpreter.
Firstly, in the interests of putting the user at ease, the program will simulate personal interest in the user by asking for their name, accepting the input and generating a greeting based on the input text.
- cls - print text Please type your name: - store input - print Hello there, - print value - print . Nice to meet you. - newline - newline
Continuing the "query-response" mode of operation, prompt the user for the radius of a circle, which is then used to calculate the area of a circle using the standard formula for the area of a circle: A = πr2. Due to syntax limitations, this is done by multiplying the input value by itself, then by π. This calculated value is returned to the user. Note: the value of π used is an approximation that is sufficiently accurate for our purposes.
- print text Let's work out the area of a circle. - newline - print text Please enter the radius of the circle in yards: - store input - multiplyby value - multiplyby 3.14159 - print Thank you - newline - print text The area of the circle is - print value - print text square yards. - newline - newline
Finally we'll ask the user for the required information and work out the area of a rectangle using the standard width by height formula.
- print text Now let's work out the area of a rectangle. - newline - print text Please enter the width of the rectangle in yards: - store input - print text Please enter the length of the rectangle in yards: - multiplyby input - print Thank you - newline - print text The area of the rectangle is - print value - print text square yards. - newline - newline - print text Goodbye,
And that's the program finished.
References