Lightweight Literate Programming

Allan M. Stavely

Last modified March 19, 2008


Table of Contents

1. Introduction and background
1.1. Literate Programming
1.2. Potential contribution to software engineering
1.3. Single sourcing of documentation
2. Traditional literate programming
2.1. Knuth's WEB and similar systems
2.2. Acceptance of literate programming
3. A lightweight approach
3.1. Simplifying the markup
3.2. Processing
3.3. Apologia
3.4. History of lightweight literate programming
4. Other common approaches and why they aren't the same
4.1. Blocks of comments
4.2. Extracting documentation from source files
Bibliography
A. Literate programming and single-sourcing
B. Jef Raskin's literate programming
C. Literate scripts in functional programming languages

Note

The essay presented in these pages began as a draft of parts of a recent journal paper, co-authored with Lynda Walsh (faculty of the Technical Communications Program, Humanities Department, New Mexico Tech) and John Shipman (Computer Center, New Mexico Tech) [Stavely 2008]. When I use the word "we" here, I include them. However, the words that appear here are mine, for better or worse.

I have continued to develop this essay independent of the journal paper. Thus, this essay is still a work in progress and will change further. Please do not copy, cite, or quote from these web pages; use the journal article for those purposes instead, if possible.

However, please feel free to direct the attention of others to these pages, and of course comments, suggestions, and any other correspondence are most welcome.

Abstract

Literate programming is a technique for combining the source code of a program with its technical documentation. I present a "lightweight" variant of the idea, designed to reduce to an absolute minimum the extra effort required of the programmer. I explain how we do it and how it differs from traditional literate programming, and relate it to software engineering practice and to single sourcing of documentation.