Literate Programming Examples

I’ve really become enamored with the idea of literate programming but figured that the best way to re-introduce it to others is the same way Knuth did… with examples.

What does it look like to work this way?

Screenshots

Here are a few screenshots of my Emacs environment showing some of these examples.

Source code with embedded hyperlinks

emacs-screenshot-1.png

Auto hiding can show just the headers

emacs-screenshot-2.png

Describe diagrams with the source code

emacs-screenshot-3.png

Examples

Now on to the examples. Keep in mind that each example below has an original “ORG” file as well as derivative files:

literate-programming-tangling.png

<style type=“text/css”> .center { margin-left: auto; margin-right: auto; } .center td { text-align: center; vertical-align: top; } .center a { border: none; text-weight: bold; } .arrow-cell { font-size: 200%; } .box-cell { font-size: 110%; border: 2px solid #545454; padding: 8px; } </style>

Coin Kata

Many people have talked about the Coin Change Kata, as a way to practice our coding craft. I thought it would be fun to try it in a literate way, and this is the results. I suggest viewing the tangled web page first.

<table class=“center”> <tr><td colspan=“3” class=“box-cell”> <a href=“coin-kata.org”>coin-kata.org</a> </td></tr> <tr><td class=“arrow-cell”> ↓ </td><td></td> <td class=“arrow-cell”> ↓ </td></tr> <tr><td class=“box-cell”> <a href=“coin-kata.html”>coin-kata.html</a> </td> <td>     </td> <td class=“box-cell”> <a href=“coin-kata.clj”>coin-kata.clj</a> <a href=“coin-kata-tests.clj”>coin-kata-tests.clj</a> </td></tr></table>

Why yes, you can keep your tests next to your code and tangle it out to separate file(s).

Emacs Init File

Being a rabid Emacs user, my .emacs file grows regularly, and sometimes I forget how some of the code I’ve added works… or even why I added it in the first place. LP and Org (with its abilities to have clickable hyperlinks) seem a natural fit.

My Emacs and Shell scripts are uploaded to Github, which now supports automatic weaving of org-mode files, so check out emacs.org which gets tangled as .emacs in my $HOME directory.