The Joy of Literate Programming

With Video Examples

Intro

Literate programming is a lot of fun. It's a great way to document your source code, and its macro capabilities are powerful enough to greatly enhance the coding experience itself. However, to be honest, it’s hard to convey the joy of literate programming without demonstrating it. So, in this post, I’m going to walk you through a simple example that touches on all the features of a modern literate system.

For this demo, we’ll be using Organic Markdown. To install it on your machine, follow the instructions in the README.md file of its GitHub project. After that, all you’ll need is a Markdown editor and a terminal to get started. Many people use standard programming environments (e.g., Emacs, Vim, VSCode) that have Markdown editing modes, but you don’t have to. Markdown editors like Typora and Obsidian work just as well. Personally, I find there's something special about doing your programming in an environment specialized for writing prose. For this reason, I’ll be using Typora for all the examples in this document.

To further simplify things, I’ve recorded my examples as videos and embedded them in this document. I did this because writing a document about how to write a document, placing Markdown with code sections inside Substack code sections, with all the necessary escaping, is too much inception for my brain to handle. It's a lot easier to understand in a video anyway.

Writing Source Code Files

We’ll start by creating a file called demo.md to hold the documentation and code for a simple "Hello, World!" application. In our documentation file, we’ll create a main.c file section and demonstrate how to automatically write that file to the file system. (You may want to maximize the video window to see the details more clearly.)

Running Commands

Now that we can output a source file from our Markdown file, let’s create a couple of commands that we can run directly from the Markdown file as well. In this case, we’ll create commands to build and run the application.

Literate Reference Syntax

Now it’s going to get really fun. In this video, we start using literate programming reference syntax. This allows us to rearrange code in our literate file to make it easier to read and document, while still ensuring it shows up in the right places on disk when we run omd tangle. Beyond simply referencing code sections, these references can also take arguments and provide defaults. Hopefully, you’re starting to see the power of a literate programming system.

Yaml Header Block

Markdown files can also include YAML blocks at the top for metadata and other information. Organic Markdown allows you to define simple code sections within the YAML area to enhance the readability of your file.

Using Command Output in Other Code Blocks

As our final trick, we’ll show you how to take the output of a command and use it as if it were a code section in the literate file. This gives you nearly infinite freedom to automate the writing of your source code.

Conclusion

With just these few features, Organic Markdown offers considerable power for documenting and writing source code. From the comfort of a nice Markdown editor, you can feel like you're writing a book while simultaneously crafting fully functional code. It almost feels like magic. I hope you’ve enjoyed exploring Organic Markdown. If you have any suggestions or questions, please feel free to reach out.