"Organic Markdown" Intro

NOTE: The mobile version of this article doesn’t format code sections properly. Try the desktop version instead.

This document demonstrates how to use literate programming with a simple literate system that lightly extends standard Markdown syntax. It is strongly inspired by Emacs Org-mode. I call it Organic Markdown. Using a simple Markdown file as the source, you can generate and save its corresponding source code, run commands, and much more. This strategy offers several advantages.

1. Keeps Documentation and Source Code in Sync: Source code is never edited separately from the documentation. They stay tightly coupled.

2. Improves Code Presentation: It allows you to present your code in a way that better suits human understanding. The source can be rearranged later to accommodate a compiler or interpreter.

3. Enhances Documentation: You can take advantage of all the other features of Markdown that naturally enhance your documentation.

4. Reduces Code Duplication: It allows you to reuse code and reduce duplication in ways that can be difficult directly in the source code.

This document will hopefully help you start writing your own literate programming projects.

Installation

Organic Markdown is a Python script that you can install from GitHub (https://github.com/adam-ard/organic-markdown). You'll find more installation instructions on the README.md page included with that project. It's important to note that this is just a prototype I wrote to explore different literate programming ideas. It is not production-ready, but it is fun to play with, so I thought I would share it here for any other literate programming enthusiasts.

Tangling and Weaving

When Donald Knuth introduced literate programming in 1984, he described two fundamental transformations that can be applied to a literate source document: tangling and weaving. Tangling generates source code documents in the format and file system locations appropriate for a compiler or interpreter. Weaving produces well-formatted documentation with embedded code snippets.

A literate source document, therefore, contains all the source code and documentation necessary for these two transformations. For this purpose, Donald Knuth used a hybrid of TeX and source code. As you would expect, his exported documents are beautifully typeset.

I opted for a less intensive solution (one day I'll learn LaTeX) that uses Markdown for my literate source document. Since there are many tools for writing and displaying Markdown, the weave step comes for free. The Organic Markdown script provides the tangle step.

Main file

To demonstrate how this all works, first create a file called README.md. This is where all the code and documentation will go. To add documentation and code for the main application file, insert the following code into your newly created README.md. In this case, we'll use C as our programming language. But you can choose any language you would like. Notice how we add some extra information on the line that opens the fenced code block. This will tell Organic Markdown where our source file should go when it's generated.

# Main file

Here is where you can put your documentation. Using all the normal markdown goodies, like **bold**, *italics*, etc...

```C {tangle=main.c}
#include <stdio.h>

void main()
{
    printf("Hello World\n");
}
```

Next, run the following command in a terminal:

omd status

you should see the main.c file listed in the output file section:

Available commands:
  (use "omd run <cmd>" to execute the command)

Output files:
  (use "omd tangle" to generate output files)
        main.c       <------------ here

You should still only see a README.md file in your directory, however. To actually generate the main.c source file, you’ll need to run the tangle command. After running this command, you should see a new main.c file appear in your directory.

> omd tangle
> ls
main.c  README.md

Build the application

To build this file, you'll need to run gcc. Add this command to the README.md file below the first section you copied above:

# Build application

This is how you build the application...

```bash {name=build menu=true}
gcc main.c
```

The cool thing about Organic Markdown is that you can execute commands directly from the README.md file by adding some attributes to the first line of the fenced code block, as shown above. Here we give the command a name and specify that it should show up in the omd status command output. You should now see the build command in the command listing of your status output:

> omd status
Available commands:
  (use "omd run <cmd>" to execute the command)
        build     <----------- here

Output files:
  (use "omd tangle" to generate output files)
        main.c

Let's see if it works. Run omd run build. You should see a new a.out file show up in your directory. You just compiled the main.c file!

> omd run build
> ls
a.out  main.c  README.md

Run the application

Next, add the command that runs your built application to your README.md file.

# Run application

This is how you run the newly built application...

```bash {name=app menu=true}
./a.out
```

Give it a shot; you should see:

> omd run app
Hello World

And now you should see all your commands in the status listing as well:

> omd status
Available commands:
  (use "omd run <cmd>" to execute the command)
        build
        app

Output files:
  (use "omd tangle" to generate output files)
        main.c

Lots More Coolness

This is just the beginning of what you can do with Organic Markdown. With what you have learned here, you can turn a Markdown file into an executable document and save code snippets as files on your file system. The ability to divide code into sections, like in traditional literate programming systems, is also available and will be covered in future articles and videos—along with a few other cool features not available in other literate systems. Once you start programming this way, you'll never want to go back ;) Stay tuned for more content.