In fact, making your program 'literate' (aka, a book ) is easy.
The first steps (1)-(6) are only done once to get your program in book form.
Note that this works with any programming language. I normally use Lisp
but I'll illustrate it with C code.
The last step (7) will create a PDF and also execute your code.
You run step (7) which just requires typing 'make' any time you
want to see the book and run the code.
So now you're in a "hot loop", writing explanations and changing your
literate code, typing 'make' to remake the book and rerun the code while
continuing to create a literate program in a PDF.
To explain in detail, assume you have "hello.c" and want it literate.
(1) convert your program to a latex file. Copy hello.c to hello.tex.
Starting with the your hello.c:
====================================
#include <stdio.h>
int main() {
printf("hello\n");
return 0;
}
=====================================
At the command line type:
=====================================
cp hello.c hello.tex
=====================================
(2) wrap your code into latex using macros (attached below)
There is a latex macro pair (attached in a latex style file below called
chunk.sty) which defines \begin{chunk} and \end{chunk} that wrap anything
in a verbatim-style block. The \begin{chunk} takes an argument which is any
word or sentence, as in \begin{chunk}{int main}. So you walk your source file(s)
inserting these macros around every function / struct / define, etc. So, for hello.c
you create a copy, call it hello.tex which contains your C code with latex blocks.
This is tedious but trivial.
Your hello.tex file looks like (the chunk name can be anything)
======================================================
\begin{chunk}{includes}
#include stdio.h
\end{chunk}
\begin{chunk}{main}
int main() {
printf("hello\n"};
return 0;
}
\end{chunk}
========================================================
(3) automate the extraction from your hello.tex to hello.c
Now you'd like to make it so your program can be extracted easily.
Make a new chunk using any name that collects your chunks: The
third macro, called getchunk, will insert the named chunk inline.
at the end of hello.tex add a new chunk:
===================================================
\begin{chunk}{all}
\getchunk{includes}
\getchunk{main}
\end{chunk}
====================================================
(4) check that you can recreate the original hello.c from hello.tex
The second too is a program called 'tanglec' which, given the name of a
chunk will extract it to stdout. So we ask for the whole program and put it into
extracted.c with and check that it is byte compatible with hello.c:
(Note: tanglec is attached below. gcc -o tanglec tanglec.c)
at the command line type:
===========================================
./tanglec hello.tex all >extracted.c
diff -Naur extracted.c hello.c
===========================================
(5) make hello.tex into a PDF. Just add some trivial latex header/footer.
For example add a header: (Note: chunk.sty is attached below)
So now your hello.tex looks like:
============================================
\documentclass[dvipdfm]{book}
\usepackage{chunk}
\begin{document}
\title{A Literate Hello}
\author{Timothy Daly}
\maketitle
\chapter{We need includes}
\section{This is the usual one for printf}
\begin{chunk}{includes}
#include <stdio.h>
\end{chunk}
\chapter{This is where the magic happens}
\begin{chunk}{main}
int main() {
printf("hello\n");
return 0;
}
\end{chunk}
\begin{chunk}{all}
\getchunk{includes}
\getchunk{main}
\end{chunk}
\end{document}
=================================================
(6) create a trivial makefile (note that indented lines require TABS, not spaces)
in a file called 'makefile'
===================================================
doit:
latex hello.tex
dvipdfm hello.dvi
evince hello.pdf &
tanglec hello.tex all >hello.c
gcc -o hello hello.c
./hello
==================================================
(7)
At the command line
===============================================
make
================================================
WIN! Now you write all your explanation and your code in the latex file.
Then type 'make' which recreates the book and runs the code. The
explanation and the code are always in sync. Now your code is a book.
Now you can add pictures, URLs, a table of contents, an index,
cross references, a bibliography, and even a spiffy new cover!
Oh, and someone can actually read your explanation of your code.
Make Knuth happy! Win a Pulitzer prize!
tanglec.c