What's the inverse of literate programming.

One of my favorite ideas in programming that hasn’t ever quite worked is literate programing. Literate programming explores how the act of writing and reading software might work if we blended code and documentation–the how and the why–much more closely, usually in the same file.

As I reflect back on writing my book, I wish I had tools to do the opposite: powerful, easily extensible tools to write books. I guess we could call it “programmable literacy”, if we had to manufacture a name under durress.

Imagine if you wrote a book where each section was tagged with prerequisite content! It would be trivial to ensure content was ordered properly, making it easy to avoid forward references to concepts that hadn’t been introduced yet, even if you refactored the content multiple times.

I also recently discovered a fairly odd sub-genre of fantasy/science fiction called LitRPG, which I really can’t recommend (the writing quality is noticably low in a genre that already is beset by quality issues), but is structurally quite interesting. In particular, they often render the same structured content over and over (e.g. a status table describing the protagonists), and I started to wonder, what are the tools to avoid continuity errors for authors maintaining so much mutable state over hundreds of pages?

Blending this all together with the desire to get some initial exposure to Rust, and I hacked together literal over the past week or so. It’s, to be clear, not good Rust code, since I barely understand how Rust works, but it is a working proof of concept of how a simple version of “programmable literacy” might work.

In short, you write Markdown syntax with some extra directives, one of which is rendering templates (using Tera’s subset of the Django template language).

Your document file might look like:

\init title My Cool Book
\init author Will
\init chapter 1
\init chapter_title First Chapter    
\render templates/chapter.md

This is an insightful chapter, filled with insight.

\incr chapter 1
\incr chapter_title Second Chapter
\render templates/chapter.md    

Honestly, not as good as chapter one.

Then your templates/chapter.md would look like:

## Chapter {{ chapter }}: {{ chapter_title }}
*{{ title }} by {{ author }}.*

You then run literal to expand the content, and perhaps pass it through pandoc to render it. For example, you could convert this into an epub formatted ebook via:

./literal book.md | pandoc -f gfm -o mybook.epub

I also added some very simple support for assertions, a more powerful version of which could be used to plot expected state across a book and ensure their prerequisites are met. You could imagine a full version of this that’s essentially “test driven development” for writing your book.

\init chapter 1
\assert chapter 1

Do some stuff

\incr chapter 1
\assert chapter 2

Those would all succeed, but it would exit with an error status code if you attempted to an incorrect assertion such as:

\init chapter 1
\assert chapter 2

Really, this is not that useful as is, but it was a good Rust learning project and I think you could do something very powerful (and very niche) building out a more powerful toolkit that included rendering computed values, more useful data structures, and perhaps arbitrary code execution.

Altogether, was a fun exploration, and I look forward to understanding Rust’s borrowing concept sometime soon (I keep wanting to think of it as a reference, which seems subtlely wrong). This is also the largest personal project I’ve written in VSCode, which is slowly becoming my default IDE for projects where Emacs feels overwhelmed.