This document describes a program with the intent to explain it and document every design decisions. Actually, it describes that program so well that the entire program can be reconstructed from this documentation. Indeed, the whole code is presented, although in an order that suits the flow of explanations rather than the flow of computation. Extracting a program code from its explanations rather than adding some documentation within its code is a technique called "literate programming" and have several advantages over traditional code writing:

  • it produces a much better documentation of a program;

  • this documentation does not become obsolete that easily;

  • last but not least, it forces the author of the program to think about and justify many decisions that he would have otherwise taken unconsciously.

To be able to extract a working program from a natural language publication requires some rigorous notations, though, that this short guide will describe.

Notice that although we will take OCaml as the implementation language in this guide the same set of technique can be applied to any language.

First of all, blocks like this are code, with a name as title:

a code block
let some_string = "hello world!"

If another block of code appears later in the text with the same title then it implies that this fragment of code will be present after the previous one in the program. Notice that when two blocks of code appear in different locations they tend to be loosely related such that their relative position in the program is of little importance.

Sometime, though, we must defer the introduction of some code until a latter time in the presentation, and thus will display code with a placeholder for a latter definition. Those placeholders will always follow the schema (* ...some text... *). Here is an example:

a code block with a placeholder
type person = {
  name : string ;
  date_of_birth : float ;
  (* ...other person attributes... *)
};

This has the advantage of being valid code thus being nicely rendered as a comment by asciidoc. Being valid code has a own side though: a missing expansion may leads to a valid program!

Later in this document, a code block entitled with the string present between the ellipsis marks is supposed to replace the placeholder. For instance:

other person attributes
nickname : string ;
email : string ;

It is even possible that some more code with the same title will follow, in which case it is meant to be written in the placeholder as well:

other person attributes
country_of_residence : string (* ISO country code *) ;

Finally, when the title of a code block is preceded by a name and a colon, this mean that the content of this code block is supposed to take place in a module named after that suffix. For instance:

Example: an implicit module
let value = 42

is equivalent of:

the same, with explicit module
module Example = struct
  let value = 42
end

This is so because in OCaml files play the role of implicit modules, and since we don’t use files here to organize the code
[actually, code blocks will end up being written in files of that name prior compilation]
 we must have a way to open a module implicitly.

As expected, all code blocks prefixed with the same module name will be appended in this module in the order they are met in this text.

And that’s all one have to know to be able to reconstruct an OCaml program from this documentation!

In addition to this, we also want to be able to define other files. For that purpose we will be using this rather explicit title:

Content of a_file_name.ext
foo bar

so that we can expose short auxiliary files.