Multi- to Monorepo Conversion and Literate Programming

Literate Programming means writing a program in the order and flow that is most natural to a human reader, not to a computer.

Example: if the initialization of your program is the least important part, you put it at the bottom of the file, regardless of whether the execution environment needs it at the top.

Between the blocks of code you have room for human text and explanation. Essentially, this inverts the relationship between code and comments: normally, code is first class, and comments are sprinkled in between code, wherever they fit. In literate programming, the commentary is first class, and the code is sprinkled in.

Tomono

Literate Programming is so easy that it’s only taken me five years to produce my first program: a cleanroom reimplementation of tomono:

human readable version: Human readable docs
computer readable version: tomono script

Which are extracted from the:

source: literate program source

Tomono is a script that merges multiple repositories into a single monorepo. It leaves history unmodified, namespaces remote tags, and allows gradual migration while other repos stay under development. It does some low level Git wrangling, if you’re into that stuff.

Due to a licensing issue it needed a full rewrite, and that was absolutely not a waste of anyone’s time, no way, such a great idea. Really glad I did that. It allowed me to learn about Literate Programming, which will absolutely serve me well in the future when…

⋮

Literate Programming. It’s a great idea but the implementation needs some work.

I first wrote about tomono in 2016, when I developed v1. Tune in on Dec 12, 2028, for the rewrite in ksh.

Shortcomings of Literate Programming

Shell script one of the few languages I can think of that actually benefit from LP. It has no modules, and the tools it does have for abstraction (functions, files) incur significant semantic costs. How do you get a string return value from a function while keeping proper error checking? It’s a mess. LP makes languages like bash and sh more readable already, even with current stunted tooling.

For everything else, this needs to improve:

An easy way to navigate between generated source code and original doc
A “quick glance” view: when looking at a code block in LP, where does it belong in the generated file? And vice-versa. Think: the Atom minimap.
Sync between generated program and LP doc
An elegant “export” mode. The default Org HTML export is messy to say the least (hello this very website), but completely breaks down for larger documents. It would need at least a fixed position Table of Contents, collapsible headers, better code block meta data formatting (name, used by links, etc), and a better color scheme.

Some of these functions partially exist in org-babel, but are either currently broken, or fall short (e.g. :comments link and :comments noweb are broken).

That being said: it works for tomono!