[Top][All Lists]

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

[Axiom-developer] Literate programs

From: Tim Daly
Subject: [Axiom-developer] Literate programs
Date: Thu, 16 Nov 2017 08:06:37 -0500


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


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'...)


Attachment: tangle.lisp
Description: Binary data

Attachment: tanglec.c
Description: Text Data

Attachment: test.tex
Description: TeX document

reply via email to

[Prev in Thread] Current Thread [Next in Thread]