Better Literate Programming

First, several big updates recently to the original version of lit, my agnostic tool for literate programming.

  1. It can now preserve correct line numbers for debugging, which is the killer feature I’ve been trying to figure out; this is the only reason I haven’t written all my source code in this format for the past couple years.
  2. You can pipe the processed content over stdin/stdout instead of just writing files to disk, which should enable any shenanigans you want to wire up that I have not anticipated.
  3. Best of all, thanks to some logging tricks it also lets you actually execute Markdown documents. Usage would be something like this:
    
    # use Python to execute the fenced code blocks inside script.py.md
    $ python $(./lit.sh --input "script.py.md" --before "#")
    

In addition, I’ve reimplemented the same core logic as a Rollup plugin. This is optimized for JavaScript, supports sourcemaps for debugging, and can be delivered via npm with semantic versioning for dependency management.

Literate Programming

Lately I’ve been doing a lot of coding in CoffeeScript, which is a very elegant language, but my favorite feature is actually just a workflow. Instead of first coding and then later annotating the code, with “literate mode” you first write out descriptions of your logical structures, and then inside that framework you start to embed the executable code. It’s a very interesting way of working, so a few days ago I put together a small shell script which allows me to apply a “literate” workflow to any other kind of code.