Ron,
As I mentioned, code dies when the authors stop touching it. This is
especially so with interns and students. Github is a graveyard of code
for exactly that reason. Even important Phd code gets thrown away once
the thesis is done. Literate programming is an attempt to overcome this.
This is my pain-less way of doing it.Inflict it on your students.
In general, I write code in an Emacs buffer and run a shell in another buffer.
I run a pdf browser in another window. As I work (usually every 10 lines or
so of input) I run a little make command that latex's my file and compiles
my code so I catch mistakes early. This method of programming strongly
encourages writing explanations in latex as you code.
Knuth defined a file format Foo. The file contained both code and explanation.
weave Foo >foo.tex generates a tex file for processing
tangle Foo >foo.code generates a code file for compiling
The idea of weaving in order to generate tex seems pointless.
In my scheme there is no longer a need for Knuth's weave program
because the file is already latex code. The only required code is a
simple tangle program.
I've defined 2 latex macros (see tangle.lisp for details)
\begin{chunk}{name} ... \end{chunk} delimits a named code block
\getchunk{name} requests a code block Foo expansion
As per Knuth, you extract code from your latex file using tangle.
The tangle program walks the Foo.tex file. Every chunk is put into a hash
table under the given name (multiple name uses are concatenated into one
hash block).
The tangle program, when it finds a "getchunk" will output the named
hash block.
So to create a literate program you write standard latex and surround your
code blocks with \begin{chunk}{name} ... \end{chunk}
To extract that code block you write
tangle Foo.tex name >name.code
The default name is "*". You can name any (or all) blocks "*" and then
tangle Foo.tex >the.code
I tend to write a lot of named blocks and then have a single final block
named "*" that consists of
\begin{chunk}{*}
\getchunk{block1}
...
\getchunk{blockn}
\end{chunk}
The tangle program, when asked for "*" will then inline all the named code
blocks on output.
I've attached both lisp and C versions of the tangle command. To use C:
gcc -o mytangle tanglec.c
./mytangle test.tex -- output the default block "*"
./mytangle test.tex foo -- output the block named "foo"
pdflatex test.tex -- latex the file (pdf browser will update)
Oh, by the way, you might already have a binary named 'tangle' on your
system. This is NOT the tangle you're looking for. Use the attached code.
(Aside: it would be a trivial but clever change to use latex to write the
code file immediately during the latex step using \write. Then you don't
need tangle at all. It all works by 'magic'...)
Tim
tangle.lisp
tanglec.c
test.tex