A literate programming tool.
Files
README.md

Loom #

Loom is an experiment in how to write source code which explains itself. It is inspired by entangled.py and the concept of literate programming.

Motivation #

To understand programs, we look to two things: source and documentation. However, by keeping them separate, we subconsciously divide the task of writing programs into two parts: writing programs which the machine may execute, and writing prose which explains the program to humans.

Literate programming does away with this division. We write a single literate source as an explanation to humans, mostly to ourselves, on the program: what it is for, what ideas it combines, and how it is currently put together. The source code which is to be executed is embedded into this explanation and follows the demands of the explanation.

This removes significant complexity in the development process:

  1. I understand immediately the motivation for a design decision.
  2. All design decisions are mapped to the area of the system that was changed.
  3. The program is easier to understand because the focus was on the explanation.

The way this is carried out is hugely powerful. It allows thinking by jumping between different layers of abstraction and considering the problem from every layer.

With literate programming, I can introduce the broad system and handle the specifics later:

The proton-massager system consists of a daemon that services a client running in the browser.

```
#| file: main.c
#define MS_STRENGTH 1402
#define MS_MAX_DEGREE 32

<<os-specific-defines>>

int main(int* argc, char* argv)
{
  int flags = 
    <<os-specific-checks>>
  ;
  broadcast_ready();

  while (flags == error) {
    fire_protons();
  }
}
```

The client must wait until the broadcast has completed before initializing the
DOM.

```
#| file: handler.js

async def wait_for_broadcast() {
  wait_for_event();
  <<initialize-dom>>
}
```

A typical IDE supports jumping to all symbols within a language. Macros and inline functions can also encapsulate details unnecessary for getting the gist of a program. However, by being a higher level system explanation which can jump between source files, literate programming adds advantages that narrative explanations using comments can't provide.

The happy path #

The happy path to me seems to be:

  1. A tool which assembles the individual code files from the literate source in a procedure called tangling, resolving dependencies using the unique id or file path of each code block. This is Loom and is also entangled.py.
  2. Writing the literate source in a format like Typst so that Typst can handle the generation of the explanation, aka the manual.

Typst can output HTML, which allows the resulting documentation to be interactive. I was excited seeing the possibilities while creating Loom's own online explanation. I think there are a lot of possibilities:

  1. Increased understanding through non-linear exploration using links. Links allow us to jump between explanations aimed at different audiences and consider multiple abstractions, whereas headings allow us to focus deeply on a single part.
  2. Iterative sharing of understanding across the team. The idea here is that if a whole team modifies the same set of literate sources, they can more easily make connections while owning their own headings. It further means that explanations are version-controlled and can improve over time in a tracked manner, and that customer facing explanations (user guides) and API contracts can be generated together with minimal duplication of explanation: just enough to focus on the needs of the users of each.

The literate programming method may work well with agents, too, because they solve so many problems encountered by teams. Stale documentation and specifications often come from the fact that they are separate from the code. Instead of versioning specifications and Markdown plans for code, it's easier to version the explanation, and let it change over time with the code.

Literate programming lends itself to the iterative improvement of your proccess.

More about Loom #

This manual is divided into four needs:

  1. How: I use Loom and literate programming methods in my workflow.
  2. Reference: generating a CLI reference as a manpage.
  3. Explanation: design decisions I made when building the website and tool.

Building the explanation #

I use Nix to build Loom. Nix in conjunction with Nix flakes is a happy path to keeping track of dependencies used in your project and being able to rebuild your experiments in three months from the same version controlled tree. Learn more here: [TBD best resource].

The command I use is:

nix build

# => result/bin/loom
# => result/docs/loom.html

Why the name loom? #

Since readable literate sources are generated from "weaving" the source, I thought loom was a fun name for such a tool.