A lightweight, extensible literate programming tool.


This tool consists of two programs, tangle and weave, both of which accept an input file from stdin and write output to stdout. There are no command-line arguments or other sources of input data. The literate programming interface is language-agnostic with respect to both the source code language and the document formatting language used.


These programs are intended to be intermediary text processing functions, used as components within build automation routines or shell scripts. The build processes for this tool itself, build.sh and gen-docs.sh, serve as example use cases.


For compiling the executables:

For building the (freestanding) documentation:

File Structure

A literate programming file consists of plain text sections, code sections, and output configuration commands. Inclusion of the top-level code section, named *, is mandatory within input to tangle, and certain configuration commands are mandatory within input to weave, described in a later section.

Section Commands

Code sections are created as follows:

@: <section name>
<section content>

Source code may also be later appended to previously defined sections:

@+ <section name>
<additional content>

Code sections may contain references to other sections, written as follows:

@= <section name>

References may be prepended by any amount of whitespace, whereas other commands must be placed at the immediate start of the line.

Configuration Commands

These commands define the format of the code sections and references as they would appear in the output of weave, written as follows:

@start <str>
@add <str>
@end <str>
@ref <str>

The format strings may contain the following control sequences:

Literate Source Code

The source code of this tool is rendered as a set of literate program documents, listed below.


Future Work