Literate programming in lisp dialects

Table of Contents

1 Introduction

For a long time, I pursue a convenient way to write my documents while developing my codes. And the most common way I found is writing specified format comments in my source file directly. It is not a nature way and is much weaker than most documentation software.

So are there a better way to write documents for my codes? Do I have to write all documents in my source file with just plain text?

Then I find Timothy Daly's talk about literate programming in the large and Donald Knuth's article introducing literate programming, they told me not focus on writing codes, but focus on writing documents, I agreed with their opinion because Literate programming will change the way of software development, to force us write codes to human instead of writing codes to just meet the demand of a computer.

but I think they rushed too much against popular development, because if we write document file instead of source code file, then it is harder for us to benefit from most popular but more and more powerful development tools, and we have to tangle source file from document file time to time in a iterative development, any way, no one like to keep two copies of codes, one in the document, and the other in a tangled source file.

But things may vary in lisp dialects, because lisp is the most flexible language from my view, and if a lisp dialect and its development tools can read a document file just like a source file, then we don't have to keep multiple copies of source codes, and just enjoy the benefit from Literate programming.

2 How

Then I tried to find out the possibility in lisp dialects, the good news is, we can do it easily.

2.1 Common Lisp

The result of the attempt is my Github project: literate-lisp.

As the flexibility of common lisp, all I have to do is adding some new reader syntax so common lisp can read org files directly.

Now I have developed some internal projects based on literate-lisp, even literate-lisp itself.

2.2 Emacs Lisp

The result of the attempt is my Github project: literate-elisp.

All I have to do is writing a new read function to read source codes in my document file, with a simple syntax.

Now I have maintained my emacs configuration file with literate-elisp, and even literate-elisp itself.

2.3 Clojure

The result of the attempt is my Github project: literate-clojure.

This is just an exercise of Clojure development, all I have to do is adding some new reader syntax so Clojure can read org files directly, just like it is done in Common Lisp.

Author: Jingtao Xu ([email protected])


Emacs 26.3 (Org mode 9.1.9)