Literate programming, introduced by Donald Knuth, is a technique of writing programs in the natural order and style that you would use if you were to verbally describe the way a program works. Literate programming is designed to break the order of source code required by traditional compilers. It can be fun to build programs in this way by simply starting a document with a description and a list of headers for each feature.

Litc

Here's my take on a literate programming tool.

You can grab it at ZaneA/litc.

Writing a literate program with Litc

To start off a new literate program, create a new file with an extension based on the source type (this is used by CodeRay to detect the language for syntax highlighting) but add a markdown extension to the end. For example, myscript.scm.md for a script in Scheme.

Now open this file in your favourite Markdown editor write up a nice description of your program followed by some headings for each main section of the program, or whatever feels natural as that is the point of literate programming after all!

In order for litc to understand how to run your script, the first code block in the file must be the command-line used to run the source. The filename will be appended automatically. After this you may mix as many code blocks as you like into the "literature". Once you're finished you should have something that looks like this:

# My fancy hello world in Chicken Scheme

This is a fancy schmancy hello world script written in Chicken Scheme.
It can be run with the following command-line:

    csi -script

## The Hello World

The first and only thing that this script does, is print the string "Hello, World!" to the user.

    (display "Hello, World!\n")

Now, to run this script, we simply invoke litc and pass the script filename. It will take care of the rest!

$ litc ./myscript.scm.md
Hello, World!

It will also leave an .html file in the same directory with the rendered Markdown, complete with syntax highlighting if the file extension was correctly guessed.