From f700b2af8e874c586e6996b8311c3983203c6637 Mon Sep 17 00:00:00 2001 From: Gabriel Schneider Date: Thu, 1 Oct 2026 13:05:10 -0300 Subject: 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 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 --- docs/typ/README | 33 +++++++++++++++++++++++++++++++-- 1 file changed, 31 insertions(+), 2 deletions(-) (limited to 'docs/typ/README') diff --git a/docs/typ/README b/docs/typ/README index 522d99ff..5db2cf76 100644 --- a/docs/typ/README +++ b/docs/typ/README @@ -35,14 +35,16 @@ Build (from the repo root): The contract for content files ------------------------------ Start a content file with - #import "style.typ": key, keys, btn, chord, word, tag, addr, file, cmd, doc, pairs + #import "style.typ": key, keys, btn, chord, word, tag, addr, file, cmd, doc, pairs, fstree (a content file does not import page setup; the same file goes into the book, the HTML and, for the cheatsheet, the A4 page) and use plain markup (= headings, - lists, `raw`, *strong*) plus these. Never set page, fonts, colours or spacing in a content file; ask for a new function instead. - word(w) a builtin or tag word, drawn as it sits in a tag. + word(w) a builtin or tag word, drawn as a chip on the tag's + ground; a builtin links to its entry in the Builtins + chapter wherever that chapter is in the same output. #word("Save") #word("Tty+bash") key(k) one press, or a sequence of presses separated by spaces, drawn as one pill (Ctrl + w, g › g). @@ -68,12 +70,39 @@ new function instead. config keys detached, mapped in `topics`). A link in the book and the HTML; on the A4 sheet, its name. #doc("building", section: "listeners") + fstree(spec) a directory tree drawn as `tree` draws one, from a raw + block: two spaces of indent per level, the name (a + directory ends in /), two or more spaces, a one-line + description, an optional @label of the section that + documents it (a link where that section is in the + same output). reference.typ's tree is checked against + the files the session serves. + #fstree(``` + index a line per pane @rules + pane/ + new open: a new pane @panes + ```) + theme-gallery() every theme as a picture, on the site's Themes page; + nothing on paper. pairs(split:, ..cells) a two-column table, a thing and its meaning, rows on alternating tints; split: 2 sets it as two tables side by side on paper. Cells alternate left, right. #pairs(key("u"), [undo], keys("i", "a"), [insert]) +Builtins +-------- +builtins-tty.json and builtins-gui.json are every builtin of the terminal +and the window build (name, leader, Help's other shortcuts, arg, scope, +setting, choices, doc), written by `zig build builtins-json -Dplatform=tty` +and `-Dplatform=gui` from the registry and the Help rows +(src/builtins_json.zig). style.typ merges them, marking each word "both", +"tty" or "gui". The doc steps refresh their build's file first, and each +build's unit-test fails when its file is stale. #word takes a name from +either file. builtins.typ draws it as the +glossary; `everyday`, `internals` and `builtin-groups` in style.typ say +in what order. + The drift test -------------- The unit test "docs/typ names only words, keys and default tags that -- cgit v1.3