Builtins are chips that link to a glossary generated from the registry, and the virtual filesystem is drawn as a tree

#word draws a builtin as a chip on the tag's ground over a rule (Look and
Exec in acme's look green and exec red), a <code class="word"> in HTML,
and links it to its entry in a new Builtins chapter wherever that
chapter is in the same output (the book, the site). The chapter is
drawn from docs/typ/builtins-tty.json and builtins-gui.json, which
`zig build builtins-json -Dplatform=tty|gui` writes from the registry
and the Help rows (src/builtins_json.zig, tools/gen_builtins_json.zig;
summaryOf in ninep/ctl.zig is now pub); style.typ merges them, marking
the window-only words. The doc steps refresh their build's file first,
and each build's unit-test fails when its file is stale. Everyday words
first (`everyday` in style.typ), then groups by leader prefix as Help
has them, then settings, the words with no path, debugging and
internals, and last an A-Z index of every word. `zig build book` joins
the doc steps.

#fstree draws a directory tree with its connectors, a description
column and links to the sections that document each file; reference.typ
draws the served tree with it, each pane, pty and column file on its
own line, and a test in config.zig checks it against ninep/tree.zig's
files both ways. The cheatsheet has a two-level version. On the site
the tree reads as `tree` text in w3m and wraps descriptions under the
names on a phone.

The site's tutor draws its B1, B2, B3 and 1-2 chords as mouse glyphs;
the landing credits Plan 9 and acme, as does the book's title page;
install.typ no longer lists the mirrors (the footer does).

Co-Authored-By: Claude Opus 5.5 <[email protected]>

1 files changed, 50 insertions, 17 deletions

diff --git a/build.zig b/build.zig
index 73d86937..0246d55f 100644
--- a/build.zig
+++ b/build.zig
@@ -122,26 +122,38 @@ pub fn build(b: *std.Build) void {
     const test_build = b.step("test-build", "compile unit-test programs without running them");
     const doc_typ_opts = b.addOptions();
     doc_typ_opts.addOption([]const u8, "dir", b.pathFromRoot("docs/typ"));
+    // The docs (docs/typ, docs/site): each output is one typst run, and each
+    // reads docs/typ/builtins-*.json; `builtins-json` refreshes this build's from the
+    // registry first (the tool is wired below, once the core module is).
+    const typst_bin: ?[]const u8 = b.findProgram(&.{"typst"}, &.{}) catch null;
+    var doc_renders: [3]?*std.Build.Step.Run = @splat(null);
     const cheatsheet_step = b.step("cheatsheet", "render docs/typ/cheatsheet-a4.typ to <prefix>/share/doc/pardes/cheatsheet.pdf (needs typst)");
-    if (b.findProgram(&.{"typst"}, &.{})) |typst| {
-        const render = b.addSystemCommand(&.{ typst, "compile", "--ignore-system-fonts" });
-        render.addFileArg(b.path("docs/typ/cheatsheet-a4.typ"));
-        const pdf = render.addOutputFileArg("cheatsheet.pdf");
-        render.addFileInput(b.path("docs/typ/cheatsheet.typ"));
-        render.addFileInput(b.path("docs/typ/style.typ"));
-        cheatsheet_step.dependOn(&b.addInstallFile(pdf, "share/doc/pardes/cheatsheet.pdf").step);
-    } else |_| cheatsheet_step.dependOn(&b.addFail("zig build cheatsheet needs typst on PATH").step);
+    const book_step = b.step("book", "render docs/typ/book.typ to <prefix>/share/doc/pardes/pardes.pdf (needs typst)");
     // The website: one Typst bundle run writes every page, the stylesheet,
-    // the fonts and the media (docs/site/site.typ). It reads all of docs/typ,
-    // docs/site and the tutor, so it always runs rather than track them.
+    // the fonts and the media (docs/site/site.typ).
     const site_step = b.step("site", "render the docs website to <prefix>/share/doc/pardes/site (needs typst)");
-    if (b.findProgram(&.{"typst"}, &.{})) |typst| {
-        const render = b.addSystemCommand(&.{ typst, "compile", "--format", "bundle", "--features", "bundle,html", "--root", b.pathFromRoot(".") });
-        render.addFileArg(b.path("docs/site/site.typ"));
-        const site = render.addOutputDirectoryArg("site");
-        render.has_side_effects = true;
-        site_step.dependOn(&b.addInstallDirectory(.{ .source_dir = site, .install_dir = .prefix, .install_subdir = "share/doc/pardes/site" }).step);
-    } else |_| site_step.dependOn(&b.addFail("zig build site needs typst on PATH").step);
+    if (typst_bin) |typst| {
+        // They read all of docs/typ, docs/site and the tutor, so they always
+        // run rather than track every file.
+        const sheet = b.addSystemCommand(&.{ typst, "compile", "--ignore-system-fonts" });
+        sheet.addFileArg(b.path("docs/typ/cheatsheet-a4.typ"));
+        sheet.has_side_effects = true;
+        cheatsheet_step.dependOn(&b.addInstallFile(sheet.addOutputFileArg("cheatsheet.pdf"), "share/doc/pardes/cheatsheet.pdf").step);
+        const book = b.addSystemCommand(&.{ typst, "compile", "--ignore-system-fonts", "--root", b.pathFromRoot(".") });
+        book.addFileArg(b.path("docs/typ/book.typ"));
+        book.has_side_effects = true;
+        book_step.dependOn(&b.addInstallFile(book.addOutputFileArg("pardes.pdf"), "share/doc/pardes/pardes.pdf").step);
+        const site = b.addSystemCommand(&.{ typst, "compile", "--format", "bundle", "--features", "bundle,html", "--root", b.pathFromRoot(".") });
+        site.addFileArg(b.path("docs/site/site.typ"));
+        const site_dir = site.addOutputDirectoryArg("site");
+        site.has_side_effects = true;
+        site_step.dependOn(&b.addInstallDirectory(.{ .source_dir = site_dir, .install_dir = .prefix, .install_subdir = "share/doc/pardes/site" }).step);
+        doc_renders = .{ sheet, book, site };
+    } else {
+        cheatsheet_step.dependOn(&b.addFail("zig build cheatsheet needs typst on PATH").step);
+        book_step.dependOn(&b.addFail("zig build book needs typst on PATH").step);
+        site_step.dependOn(&b.addFail("zig build site needs typst on PATH").step);
+    }
     const test_nonce: ?*std.Build.Module = if (b.option(bool, "test-rebuild", "force fresh Zig test compilation while retaining cached C dependencies") orelse false) blk: {
         const files = b.addTempFiles();
         const source = files.add("test_nonce.zig", b.fmt("pub const nonce = {d};\n", .{std.Io.Clock.awake.now(b.graph.io).nanoseconds}));
@@ -976,6 +988,27 @@ pub fn build(b: *std.Build) void {
         });
     }
 
+    // docs/typ/builtins-<platform>.json: every builtin, from the registry and the Help
+    // rows (src/builtins_json.zig), rewritten in the source tree so a plain
+    // `typst compile` reads it too; a unit test fails when it is stale.
+    // A terminal build writes builtins-tty.json and a window build
+    // builtins-gui.json; style.typ merges the two into one glossary.
+    const builtins_json_step = b.step("builtins-json", "rewrite docs/typ/builtins-<tty|gui>.json from the builtin registry (-Dplatform=tty or gui)");
+    if (requested_platform == .tty or requested_platform == .gui) {
+        const gen = b.addExecutable(.{ .name = "pardes-gen-builtins-json", .root_module = b.createModule(.{
+            .target = target,
+            .optimize = optimize,
+            .root_source_file = b.path("tools/gen_builtins_json.zig"),
+            .imports = &.{.{ .name = "pardes", .module = core_module }},
+        }) });
+        const run_gen = b.addRunArtifact(gen);
+        const json = run_gen.addOutputFileArg("builtins.json");
+        const update = b.addUpdateSourceFiles();
+        update.addCopyFileToSource(json, b.fmt("docs/typ/builtins-{s}.json", .{@tagName(platform)}));
+        builtins_json_step.dependOn(&update.step);
+        for (doc_renders) |r| if (r) |run| run.step.dependOn(&update.step);
+    } else builtins_json_step.dependOn(&b.addFail("builtins-json writes one build's list: pass -Dplatform=tty or -Dplatform=gui").step);
+
     const gui_shell_mod: ?*std.Build.Module = gui_mod orelse
         if (platform == .gui) root_mod else null;
     if (gui_shell_mod) |gm| {