There are two essential goals when creating a literate program:

• A working program: This is the code, extracted from the source document(s) and prepared for the compiler or interpreter.
• Easy-to-read documentation: This is the explanation, plus the code, plus any helpful markup prepared for the presentation. This document could be in HTML, ready to be viewed, or it could be in RST, and we'd use docutils rst2html.py to convert it to HTML. Alternatively, it could be in LaTeX and we run it through a LaTeX processor to create a PDF document.

The working program goal means that our literate programming document will cover the entire suite of the source code files. While this seems daunting, we have to remember that well-organized code snippets don't require a lot of complex hand-waving; in Python, code itself can be clear and meaningful.

The easy-to-read documentation goal means that we want to produce a document that uses something other than a single font. While most code is written in a monospaced font, it isn't the easiest on our eyes. The essential Unicode character set doesn't include helpful font variants such as bold or italic either. These additional display details (the font change, size change, style change) have evolved over the centuries to make a document more readable.

In many cases, our Python IDE will color-code the Python source. This is helpful, too. The history of written communication includes a lot of features that can enhance readability, none of which are available in simple Python source using a single font.

Additionally, a document should be organized around the problem and the solution. In many languages, the code itself cannot follow a clear organization because it's constrained by purely technical considerations of syntax and the order of the compilation.

Our two goals boil down to two technical use cases:

• Converting an original source text into the code.
• Converting an original source text into the final documentation.

We can, to an extent, refactor these two use cases in some profound ways. For example, we can extract the documentation from the code. This is what the pydoc module does, but it doesn't handle the markup very well.

Both versions, code and final document, can be made isomorphic. This is the approach taken by the PyLit project. The final documentation can be embedded entirely in Python code via docstrings as well as # comments. The code can be embedded entirely in RST documents using :: literal blocks.

The next section shows how to work with a literate programming tool.