sjnam — Soojin Nam, literate programmer

sjnam [--literate] [--knuth] [-o document.pdf] idea[.w] ...

There is no --terse. The --literate flag cannot be unset.

Soojin Nam — github.com/sjnam

Fond enough of literate programming to build a system for it. Go had no WEB of its own, and doing without one seemed worse than writing one — so GWEB exists, and nearly everything else on this page was written with it.

A devoted reader of Donald Knuth, and the holder of several checks drawn on the Bank of San Serriffe — the reward Knuth sends to anyone who finds an error in his work.

One of those errors was in SPIDERS, Knuth's implementation of the constrained Gray-sequence algorithms of Knuth and Ruskey — spider squishing, as the paper cheerfully calls it. The recurrences were wrong. The corrected code now stands in spiders.w, where the credit reads:

The code here is due to Soojin Nam, who kindly pointed out in 2026 that my original recurrences were fatally flawed.

Knuth's news page put it more warmly:

However, my Korean friend Soojin Nam has just reported that the original program contained a serious bug — which he discovered with the help of Claude!

The bug report, and a faithful Go implementation of the paper, are in sjnam/spider.

foo.w  --[ gtangle ]-->  foo.go                    for the machine
foo.w  --[ gweave  ]-->  foo.tex  -->  foo.pdf     for people

One source file. Two readings of it.

GWEB is a literate programming system for Go, modeled closely on Knuth and Levy's CWEB.

The premise, which is Knuth's, is that a program is a piece of writing addressed to human beings, and only incidentally something a compiler consumes. So you do not write a program and then document it. You write one .w file — a web — in which TeX prose and Go code are the same document, ordered the way the idea unfolds rather than the way the compiler demands. Then two tools read that file in opposite directions:

The program and the essay explaining it are not two artifacts kept in sync — they are one file. That is the whole of the idea; everything else is machinery in service of it.

gweb

The system itself, and the place for everything this page leaves out: how to install it, the full control-code reference, the manual, change files, editor support, and the gweb(1) man page for the two commands. MIT licensed.

gweb-examples

Thirty-odd literate Go programs, and the best answer to what GWEB is for. Algorithms and data structures (ntt.w, ziptree.w, suffixautomaton.w), concurrency (pipeline.w, squint.w, fast_cancel.w), and contest problems from HackerRank, Codeforces, LeetCode, Library Checker and Project Euler — plus two collections that walk one technique across several problems: cdq-dc/ (CDQ divide and conquer) and cht/ (the convex hull trick). Many are Korean essays; several carry MetaPost figures.

spider

A faithful Go implementation of Knuth and Ruskey's constrained Gray-sequence algorithms, and the bug report Knuth adopted into spiders.w.

Longer programs written in GWEB, each its own repository:

go-sgb

Knuth's Stanford GraphBase, rewritten in GWEB.

dancing-cells

Exact cover with multiplicities and colors, via sparse-set "dancing cells" and binary branching.

elliptic

A traveller's notes on elliptic curves.

bohnanza

The bean-trading card game.

go-advent

Advent of Code, literately.

Whichever you open, start with the PDF the .w weaves into.

Don Knuth wrote WEB for TeX and Pascal. Silvio Levy designed and developed CWEB by adapting the WEB conventions to C; Knuth began using CWEB and made further refinements. GWEB adapts those same conventions to Go — gtangle is the analogue of ctangle(1), gweave of cweave(1). If you have read a woven CWEB document, you already know how to read a woven GWEB one.

email

jsunam at gmail dot com

github

github.com/sjnam

Bug reports against any of the programs above are welcome — preferably as an issue on the repository in question, but mail is fine too.

gtangle(1), gweave(1) — the command reference, installed with GWEB.

ctangle(1), cweave(1), cweb(1) — the C system GWEB is modeled on.

D. E. Knuth, Literate Programming, CSLI Lecture Notes 27 (1992).