A one-page A4 cheatsheet, the first file of a Typst docs corpus in docs/typ

docs/typ/cheatsheet.typ holds the facts as semantic calls (#key, #btn,
#chord, #word, #tag, #addr, #file, #cmd, #doc); docs/typ/style.typ
defines those once, drawing them for paged output and emitting HTML
elements under --features html; docs/typ/cheatsheet-a4.typ is the page.
`zig build cheatsheet` renders it when typst is on PATH. A config.zig
test reads every .typ in docs/typ and fails when one names a builtin,
key binding or default tag pardes no longer has.

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

1 files changed, 150 insertions, 0 deletions

diff --git a/docs/typ/cheatsheet.typ b/docs/typ/cheatsheet.typ
new file mode 100644
index 00000000..d9c3f573
--- /dev/null
+++ b/docs/typ/cheatsheet.typ
@@ -0,0 +1,150 @@
+// The pardes cheatsheet: the facts only, an index into the docs, not a copy.
+// cheatsheet-a4.typ lays it out; style.typ says how each element looks.
+// config.zig's "docs/typ" test checks every #word, #key and #tag here
+// against the registry, the keymap and the default tags.
+#import "style.typ": key, btn, chord, word, tag, addr, file, cmd, doc
+
+= pardes #h(1fr) _acme's tags and three buttons, helix's keys, terminals as panes, the editor as a 9P filesystem_
+
+== The mouse
+/ #btn("B1"): select, and focus the pane. On a tag: type there.
+/ #btn("B2"): *execute* the word or selection: a builtin, else a shell line.
+/ #btn("B3"): *look*: open the file, address, directory or URL, else find the word's next place. Resting the pointer tints what B3 would take.
+/ sweep: drag B2 or B3 to run or look at exactly what you swept.
+/ #chord("B1", "B2"): cut; #chord("B1", "B3") paste; both: copy.
+/ #chord("B2", "B1"): execute the word with the B1 selection as argument (#word("Grep") on a selected name).
+/ #chord("B2", "B3"): cancel the sweep (either way round).
+/ grip: drag the box left of a tag: up/down resizes, onto another column moves the pane. A column's right edge drags its width.
+A program that takes the mouse (htop, vim `mouse=a`) gets #btn("B1") and the wheel; #btn("B2")#btn("B3") stay pardes's. Hold Shift to swap: Shift-#btn("B1") selects, Shift-#btn("B2") goes to the program.
+
+== Tags
+Three levels of command text, every word live: the workspace tag, a tag per column, a tag per pane (file, terminal, PDF).
+#tag("Newcol Joincol Find Grep Help Changelog Tutor Dump Themes Config Debug Exit")
+#tag("New Tty Find Grep Joincol Delcol")
+#tag("Save Tty Collapse Del", path: "/home/me/notes.txt")
+#tag("Tty+bash Save Mode Filter Collapse Del", path: "/home/me/src")
+#tag("Tty PdfSections PdfTint Collapse Del", path: "manual.pdf [1/12]")
+- Type anything into a tag and click it: tags are text, with undo.
+- A pane's words run in its directory; workspace and column tags in the session's.
+- #word("Del") closes; #word("Del") `k`/`j` gives its rows above/below. Unsaved text (marked on the grip) is refused once: #word("Del") again discards.
+- #word("Collapse") folds a pane to its tag; again unfolds.
+- Click the path to rename (Enter confirms); #word("Save") writes.
+- #word("Undo") #word("Redo") #word("Edit") #word("Mode") work typed anywhere.
+- New panes: #word("Placement") `acme` (default) or `pardes`. #doc("tags")
+
+== Look addresses
+Typed anywhere, then #btn("B3") or #key("Enter"):
+#table(columns: 2,
+  addr("file:12"), [line 12],
+  addr("file:12:5"), [line 12, byte column 5],
+  addr("file:/re/"), [next match after the selection (`file:0/re/`: first)],
+  addr(":40"), [this pane, line 40 (any address after `:`)],
+  addr("~/x"), [home; also in `Save`, `Restore`, `pardes ~/x`],
+  addr("@p3:12"), [pane 3 by serial, a terminal's lines too],
+  addr("src/"), [a directory: `ls` in an idle terminal there, else a new one],
+)
+Addresses are sam's: `#n`, `/re/`, `?re?`, `$`, `a,b`. #doc("fs", section: "look-and-exec")
+
+== Keys: normal mode
+Helix-style: motions *select*, then an edit acts on the selection. Mode box: blank normal, `^` insert, `$` tty.
+#table(columns: 2,
+  [#key("h j k l") #key("w b e")], [move; words select],
+  [#key("g g") #key("g e")], [first line, last line],
+  [#key("g h") #key("g l") #key("^")], [line start, end, first non-blank],
+  [#key("x") #key("v") #key("%")], [line, character select, all],
+  [#key(";")], [collapse to the cursor],
+  [#key("d") #key("c") #key("y")], [delete, change, yank],
+  [#key("p") #key("P") #key("R")], [paste after, before, replace],
+  [#key("u") #key("U")], [undo, redo],
+  [#key("i a I A o O")], [insert; #key("Esc") back to normal],
+  [#key("s") #key("S")], [regex: a cursor per match, split],
+  [#key("C") #key(",")], [cursor on next line; keep primary],
+  [#key("/") #key("n") #key("N")], [search, next, previous],
+  [#key("m i") #key("m m")], [textobject, matching bracket],
+  [#key("|")], [pipe each selection through the shell],
+  [#key("g d") #key("g r")], [definition, references (language server)],
+  [#key("Ctrl-d") #key("Ctrl-u")], [half page down, up],
+  [#key("Enter") #key("Tab")], [look, execute the selection (like #btn("B3") #btn("B2"))],
+  [#key(":")], [to the pane's tag and back],
+)
+#doc("keys")
+
+== Keys: panes
+#table(columns: 2,
+  [#key("Ctrl-w") #key("h j k l")], [focus a neighbour (anywhere)],
+  [#key("Esc")], [normal mode: hop to the previous pane],
+  [#key("Shift-Esc")], [leave, whatever Esc means here],
+  [#key("Ctrl-o") #key("Ctrl-i")], [jump history back, forward],
+  [#key("Alt-n")], [new terminal below],
+  [#key("Alt-c")], [move the pane to a new column],
+)
+
+== The leader: #key("SPC") in normal mode
+#table(columns: 4,
+  key("SPC ?"), [every path], key("SPC d"), word("Del"),
+  key("SPC f s"), word("Save"), key("SPC f n"), word("New"),
+  key("SPC f f"), word("Find"), key("SPC f g"), word("Grep"),
+  key("SPC f r"), word("Recent"), key("SPC f c"), word("Config"),
+  key("SPC n t"), word("Tty"), key("SPC n 9"), word("Tty9p"),
+  key("SPC w h"), [focus left], key("SPC j j"), word("Last"),
+  key("SPC j l"), word("Jumplist"), key("SPC y"), [clip yank],
+  key("SPC p"), [clip paste], key("SPC t t"), word("Themes"),
+  key("SPC t n"), word("NextColor"), key("SPC t w"), word("Wrap"),
+  key("SPC c n"), word("Newcol"), key("SPC c p"), word("Placement"),
+  key("SPC s d"), word("Dump"), key("SPC s r"), word("Restore"),
+  key("SPC s a"), word("Attach"), key("SPC s D"), word("Detach"),
+  key("SPC h t"), word("Tutor"), key("SPC h m"), word("Messages"),
+)
+
+== Terminals and commands
+- A terminal is a pane. #key("Ctrl-b") toggles raw input (`$`) and editor mode, where the same keys move over its text, prompts hidden.
+- Raw: keys go to the program; #key("Esc") at a shell prompt hops away, #key("Shift-Esc") always.
+- #word("Mode") cycles raw, normal, insert. #word("Filter") maps its colours to the theme. #word("Tty+bash") opens another on that shell.
+- #btn("B2") on any non-builtin line (`make`, `git log`) runs it with #word("Shell") `-c` in the pane's directory, in a *command pane*: #tag("Kill Save Collapse Del", path: "/home/me/src (make) exit 0")
+- #word("Kill") stops what pardes started (`Kill make`: those lines); #word("Exit") quits.
+- `Repl python` in a terminal tag: clicks in a `.py` pane go to it.
+
+== Reviewing diffs
+Run `git diff` (or open a `.patch`): it shows as a coloured diff. #btn("B3") on a `diff --git`, `---` or `+++` line opens the file; on `@@` the hunk's new line; on a hunk line's `+`/`-`/space, that line in the new file. #doc("tags", section: "reviewing-diffs")
+
+== Finding things
+- #word("Find") `name`: files below this pane's directory; #word("Grep") `re`: contents under every pane's directory. Bare, they ask; results land in `+Search`, a place per line for #btn("B3").
+- #word("Recent"): files opened lately, closed ones too, each reopened where you left it.
+- #word("Help"): every key and builtin. #word("Tutor"): the tutorial.
+
+== Sessions
+- `pardes --detach=work` runs a core with no screen; `pardes --attach=work` (or #word("Attach") `work`) shows it; #word("Detach") leaves it running, shells and all. #doc("detached")
+
+== Config
+- #word("Config") (#key("SPC f c")) opens `~/.config/pardes/init`; a line per builtin, run at start; `#` comments.
+```
+Theme atelier
+Shell zsh
+Placement pardes
+```
+- #word("DumpConfig"): every live setting as a word to click; it pastes back into `init` as is.
+- Keys are compile-time, in `src/config.zig`.
+- #word("Dump") / #word("Restore"): save and reload the workspace (`pardes -l dump.zon`). #doc("config")
+
+== Themes
+#word("Themes") lists them, a word each; #word("Theme") `name` sets one; #word("NextColor") walks the ring. `orchard` is the default, `atelier` this page's. #word("DumpThemes") writes them as `.zon`; #word("ThemeFile") `x.zon` loads one, live on save. #doc("themes")
+
+== 9P control filesystem
+Every session serves its panes as files. Pane shells get `$PARDES_9P` (socket), `$PARDES_PANE` (serial).
+#cmd("9ns --mntgen   # m=$NINE_MOUNT/pardes/<pid|name>")
+#cmd("9p -a \"unix!$PARDES_9P\" read index")
+#table(columns: 2,
+  file("index"), [a line per pane: serial, kind, name],
+  file("look exec"), [write a line: a #btn("B3") or #btn("B2")],
+  file("log"), [events; write `follow` to wait],
+  file("pane/new"), [open to make a pane],
+  file("pane/N/addr"), [an address; `data` reads/replaces it],
+  file("pane/N/ctl"), [builtins: `Save`, `Edit ...`],
+  file("pane/N/body tag"), [its text (`>>` appends)],
+)
+#cmd("echo notes.txt:12 > $m/look")
+#cmd("echo /foo/ > $m/pane/$n/addr; printf bar > $m/pane/$n/data")
+#cmd("echo 'Edit ,x/foo/c/bar/' > $m/pane/$n/ctl")
+#cmd("exec 3<>$m/log; echo follow >&3; cat <&3")
+`pardes FILE` in a pane opens it here; `EDITOR='pardes --wait'` returns when its pane closes. `cat $m/README`. #doc("fs")
+