The philosophy behind Literate Programming is that the programmer who wants to provide really usefull documentation needs to use two different languages simultaneously: one for program code and another for documentation.
Combination of intervowen code and documentation chunks in one artefact is much more usefull than separated program code and documentation.
There are two categories of literate programming tools named after original tools by Donald Knuth: weave and tangle.
The first one, weave, is intended to produce printable document optimized for human perception. The second one is used to produce compile-ready source code.
Tools
- noweb
- One of the best literate programming tools.
Simple. Extensible. Language-independent. It can be used with languages that use indentation to mark blocks of code (Python, Haskell) - FunnelWeb
- "Literate Programming Macro Preprocessor". Minor changes in tool source code required for using with encodings other than latin-1.
- xmLP
- xmLP is a literate programming tool written in XSL-T
Wiki
- LiteratePrograms
- LiteratePrograms is a unique wiki where every article is simultaneously a document and a piece of code that you can download, compile, and run by simply using the "download code" tab at the top of every article.
Other perspectives
There is another view on literate programming: instead of producing single file with single documentation thread and interlinked code chunks it is possible to keep the program code intact and produce interlinked documentation chunks.
It is Elucidative Programming. Instead of printable reports it is based on the concept of code/documentation browser.
Another interesting project - Documentation threads - concentrates on "sewing" printable documentation from multiple sources. For example you can compose single document from excerpts from software architecture specification and requirements specifications and add into it UML diagrams and code fragments. Also you can produce different documents for different purposes from the same set of source files.
It is Elucidative Programming. Instead of printable reports it is based on the concept of code/documentation browser.
Another interesting project - Documentation threads - concentrates on "sewing" printable documentation from multiple sources. For example you can compose single document from excerpts from software architecture specification and requirements specifications and add into it UML diagrams and code fragments. Also you can produce different documents for different purposes from the same set of source files.
Other perspectives explained
- The Elucidative Programming Home Page
- This page describes basic concepts of the elucidative programming.
- Documentation threads
- Documentation threads are a means for presenting fragmented documentation through a concept called documentation threads.
Heretics
There are a few technologies that seem similar to literate programming but don't share its concepts.
The first is perl documentation system. You can use some markup to integrate documentation into the perl source code. But these document chunks are completely independent of the program code. It is imposible to use such a file to produce a human-optimized document in a way it is common in literate programming world.
The second is JavaDoc - tool and notion of including documentation chunks in java source code.
In that case document chunks are linked to source code very tightly, but the result -- lots of interlinked HTML pages -- is unprintable. One the first sight it seems like elucidative programming browsing technique, but it contains no source code.
The XDoclet extends JavaDoc concept. It use custom documentation tags to implement Attribute-oriented programming in Java.
The first is perl documentation system. You can use some markup to integrate documentation into the perl source code. But these document chunks are completely independent of the program code. It is imposible to use such a file to produce a human-optimized document in a way it is common in literate programming world.
The second is JavaDoc - tool and notion of including documentation chunks in java source code.
In that case document chunks are linked to source code very tightly, but the result -- lots of interlinked HTML pages -- is unprintable. One the first sight it seems like elucidative programming browsing technique, but it contains no source code.
The XDoclet extends JavaDoc concept. It use custom documentation tags to implement Attribute-oriented programming in Java.
Resources
- Literate Programming Library
- A large collection of links to related resources.
- The CWEB System of Structured Documentation
- By Donald Knuth and Levy, describing a prominent system of Literate Programming.
- Literate Programming
- A Book by Donald Knuth, who started the ideas about Literate Programming with WEB.
- Literate Programming
- Resources for Literate Programming. Consulting services. Download freeware for Windows 95, 98, and NT. Learn about the CWEB programming language.
- Literate Programming using Pascal
- WEB2 programming tool for Pascal combining program-code and documentation into a single source-file.
- The Literate Programming FAQ
- A good place to start looking for information.
- SGML/XML and Literate Programming
- Information on applying SGML and XML to Literate Programming.
- Literate Programming in Forth
- An article by Peter J. Knaggs, originally presented at euroFORTH'95.
- Literate Programming
- The WikiWiki entry point for related information and discussions.
- Bibliography on Literate Programming
- A part of the Computer Science Bibliography Collection.
- Literate Programming -- Propaganda and Tools
- Overview of the concepts and some ideas for applying this methodology.
- Literate Programming in XML
- Aricle by Norman Walsh.
- Literate Programming with XML
- Provide tools to support Donald Knuth's Literate Programming using XML instead of TeX. Is not based on any specific DTD or programming language, but instead uses processing instructions for processing the literate programs.
