Literate Programming

Literate programming was first proposed by Donald Knuth in 1984 (Literate Programming, The Computer Journal, 27 (2): 97–111) as a technique of producing computer code from prose. The general idea is that you write code as you would write a story or an article, describing what you want to do and how to solve it. The code gets interweaved with the code as you explain it. Ultimately, you can produce one of two outputs from the same file:

• A human-readable version of the code, nicely typeset with all the explanations and code, through a process called weaving;
• A computer-executable version of the code, which extracts only the code and puts it in the correct order for the computer to run, through a process called tangling.

The idea of literate programming has been around since then, and a number of tools have been created, starting from Knuth’s own CWEB, Ramsey’s noweb, and others. However, the lack of a standard set of tools has made its adoption slow and limited to specialized instances.

During my first encounter with literate programming I used noweb, but beyond some school projects and homeworks, I could never get Literate Programming to “stick”, until I encountered Org mode.

Org mode is a markup format and corresponding toolset developed originally within the Emacs text editor. Org provides a wide range of functionality, including text formatting, calendar, task tracking, and much more. For our purposes, we are interested in the combination of two of its functions:

• Text formatting and exporting. This is one of Org mode’s core functionalities, which provides the weaving aspect of Literate Programming by allowing us to produce nicely rendered versions of our document in a number of output formats, including both the text narration and the code. Out of the box, Org supports exporting to LaTeX, Markdown, HTML and other common formats, but many more are available through third-party libraries. The output document may even include syntax highlighting appropriate for the language in which it is written.
• Code block evaluation and exporting. This is made possible by org-babel, one of Org’s built-in modules, which allows flexible manipulation, execution and exporting of code embedded within an Org document. Babel supports tangling code blocks into one or more separate files which include only the code portions of the document.

Using Org mode with Babel for literate programming is, of course, not a new idea. However, most cases of Literate Configuration that I have seen focus on using Literate Programming for configuring Emacs itself. This is a good use case, but limited in my opinion. In this booklet we will explore how you can use Literate Programming for all your configuration files.