The cheatsheet draws mouse buttons as a mouse, keys as chips, and pairs as tables

#btn and #chord draw a mouse (left button, wheel, right button) with the
pressed part filled; the wheel is a narrow slot on a paper halo, hollow
or filled, so it never reads as a button. A chord is the held button,
then for each click the held one and that one down, with arrows between;
#btn(.., shift: true) adds a ⇧. HTML gets a span with an aria-label.

A key is one soft pill with no border: a combination (Ctrl-w) reads
Ctrl + w and a sequence (g g, SPC f c) g › g, separators muted inside it;
#keys("h", "j", ...) sets alternatives as separate pills. The drift
test reads every key a #keys call names.

#pairs sets key | meaning content as a two-column table on alternating
tints; split: 2 sets the leader map as two such tables side by side.
The mouse chords get their own table: cut, paste, copy (B1-B2 then
B1-B3, one B1 hold, as mouse.zig says), 2-1 with an argument, 2-3
cancelling. The A4 page draws its own title and drops the content's level-1
heading. docs/typ/README is the function contract for content files.

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

1 files changed, 58 insertions, 20 deletions

diff --git a/docs/typ/README b/docs/typ/README
index 175a7abb..b86d7ef2 100644
--- a/docs/typ/README
+++ b/docs/typ/README
@@ -1,16 +1,15 @@
 docs/typ: the Typst documentation corpus
 
-  style.typ        the semantic elements (key btn chord word tag addr file
-                   cmd doc), the palette and the topic ids; the only place
-                   they are defined. Each element looks at target() and
-                   draws itself for paged output or emits HTML elements.
-  cheatsheet.typ   content: facts as markup and element calls, no layout.
-                   Later topics (tags, fs, config, ...) go beside it as
-                   their own content files, importing from style.typ.
-  cheatsheet-a4.typ
-                   an output wrapper: page, type, headings, then #include
-                   of the content. Future wrappers (book.typ, html.typ)
-                   sit beside it; wrappers hold no facts.
+  style.typ          every semantic function, the palette and the topic
+                     ids; the only place they are defined. Each function
+                     looks at target(): it draws itself for paged output
+                     and emits HTML elements under --features html.
+  cheatsheet.typ     content: facts as markup and the calls below, no
+                     layout. Later topics (guide, scripting, reference,
+                     building) go beside it as their own content files.
+  cheatsheet-a4.typ  an output wrapper: page, type, headings, then
+                     #include of the content. Future wrappers (book.typ,
+                     html.typ) sit beside it; wrappers hold no facts.
 
 Build (from the repo root):
 
@@ -18,12 +17,51 @@ Build (from the repo root):
   zig build cheatsheet -Dplatform=tty --prefix DIR   # DIR/share/doc/pardes/cheatsheet.pdf
   typst compile --features html --format html docs/typ/cheatsheet.typ out.html
 
-Write #word("Name") for a builtin, #key("SPC f c") or #key("Ctrl-w") for
-keys, #tag("words", path: ...) for a default tagline, #doc("fs", section:
-"edit") to point at a topic. The unit test "docs/typ names only words,
-keys and default tags that exist" (src/config.zig) reads every .typ here
-and fails when one names a builtin, key binding or default tag that pardes
-no longer has. Only embedded fonts (Libertinus Serif, DejaVu Sans Mono),
-so output is the same on every machine. docs/typ/cheatsheet-a4.pdf is
-committed, as the other docs PDFs are; re-render it when the content
-changes.
+The contract for content files
+------------------------------
+Start a content file with
+  #import "style.typ": key, keys, btn, chord, word, tag, addr, file, cmd, doc, pairs
+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("Save")   #word("Tty+bash")
+  key(k)           one press, or a sequence of presses separated by
+                   spaces, drawn as one pill (Ctrl + w, g › g).
+                   Modifiers: Ctrl-, Alt-, Shift-.
+                   #key("Ctrl-w")   #key("g g")   #key("SPC f c")
+  keys(..ks)       alternatives listed together, each its own key.
+                   #keys("h", "j", "k", "l")   #keys("g d", "g r")
+  btn(b, shift:)   a mouse button, B1 B2 (the wheel) or B3, drawn as a
+                   mouse with that part filled; shift: true adds a ⇧.
+                   #btn("B3")   #btn("B1", shift: true)
+  chord(..bs)      a chord: the first button held, each next clicked.
+                   #chord("B2", "B1")   #chord("B1", "B2", "B3")
+  tag(words, path:)
+                   a whole default tagline; words must be a default tag.
+                   #tag("Save Tty Collapse Del", path: "/home/me/notes.txt")
+  addr(a)          a look address.            #addr("file:12:5")
+  file(p)          a 9P path.                 #file("pane/N/addr")
+  cmd(c)           a shell line, as a block.  #cmd("echo Save > $m/pane/$n/ctl")
+  doc(id, section:)
+                   a pointer to a topic, by id from `topics` in style.typ
+                   (tags fs config themes keys detached).
+                   #doc("fs", section: "look-and-exec")
+  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])
+
+The drift test
+--------------
+The unit test "docs/typ names only words, keys and default tags that
+exist" (src/config.zig) reads every .typ here and fails when a word(),
+key(), keys() or tag() names a builtin, key binding or default tag that
+pardes no longer has. Pass these functions string literals, so the test
+can read them.
+
+Only embedded fonts (Libertinus Serif, DejaVu Sans Mono), so output is the
+same on every machine. docs/typ/cheatsheet-a4.pdf is committed, as the
+other docs PDFs are; re-render it when the content changes.