Something went wrong. Try again.
A literate programming tool.
Something went wrong. Try again.
readme.typ
== README
`````markdown
#| file: README.md
# Loom
Loom is an experiment in how to write source code which explains itself.
It is inspired by [entangled.py](https://github.com/entangled/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:
````text
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](https://typst.app/docs/)
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](https://leoqi.ca/loom).
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](https://leoqi.ca/loom/) 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:
```bash
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.
`````