The reference gains Coming from acme, one table of what differs for acme users and scripts; the intros say modelled on acme's; Look says it has no plumber; the guide compares Esc with acme's and answers the acme question fairly; the OTRUNC sentence reads

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

1 files changed, 26 insertions, 4 deletions

diff --git a/docs/typ/reference.typ b/docs/typ/reference.typ
index 9b107fe5..29f535ee 100644
--- a/docs/typ/reference.typ
+++ b/docs/typ/reference.typ
@@ -5,8 +5,8 @@
 #import "style.typ": key, keys, btn, chord, word, tag, addr, file, cmd, doc, pairs, fstree
 
 Every native session is a virtual filesystem, served as 9P2000 (not .u,
-not .L), in acme's manner: panes, columns, tags and the session are
-files. Paths here are the served ones (#file("/pane/2/body")); through a
+not .L) and modelled on acme's (#doc("reference", section: "from-acme")):
+panes, columns, tags and the session are files. Paths here are the served ones (#file("/pane/2/body")); through a
 mount they sit under the session's directory (`$m`; #doc("scripting", section: "find-the-session")
 says how to find it). The served #file("/README") is a
 one-screen summary of this page. Two builtins: #word("Look") (right-click): open what the
@@ -983,8 +983,8 @@ Under `9ns --mntgen` (which sets `NINE_MNTGEN=1`) a session is at
 `$NINE_MOUNT/<service>/<name>`, pardes's `$NINE_MOUNT/pardes/<name>`, and
 every pane pardes spawns gets it as `$PARDES_MOUNT`. Under `9ns --unix SOCK
 -- cmd` the session is `$NINE_MOUNT` itself, and `$PARDES_MOUNT` is unset.
-plan9port's `9p write` opens with OTRUNC, so it replaces a whole
-#file("body"); append with `>>` through a mount. Through a FUSE mount
+plan9port's `9p write` opens with OTRUNC, so on #file("body") it replaces
+the whole text. To append, use `>>` through a mount. Through a FUSE mount
 bash's `read -t` cannot time out: wrap a follow loop in `timeout`. The
 scripting chapter's rule (a mount, else `9p`) covers most uses. Two more:
 
@@ -1015,6 +1015,28 @@ with Client(sys.argv[1]) as c:    # a socket path, or (ip, port)
 
 `client.screen()` returns the parsed #file("/screen").
 
+= Coming from acme <from-acme>
+
+#pairs(
+  [`$NAMESPACE/acme`], [not posted there: a session is `$XDG_RUNTIME_DIR/9p/pardes/<name>`; reach it with `9p -a "unix!$PARDES_9P"` or a `9ns --mntgen` mount (#doc("fs", section: "other-clients"))],
+  [`N/`], [#file("pane/N/"), N the pane's serial],
+  [`new/ctl`], [read #file("pane/new"): it makes a pane and answers its serial; `rmdir pane/N` closes it],
+  [`index`], [#file("index") lines are serial, kind, dirty, name, column (acme: id, tag and body lengths, isdir, dirty, tag)],
+  [rune offsets], [bytes everywhere, event offsets and counts included; addresses snap to rune boundaries],
+  [`addr` reset on first open], [#file("addr") is the pane's; no open resets it (write `0`)],
+  [OTRUNC on `data` ignored], [`: > data` deletes the addressed text; OTRUNC on #file("body") (`9p write`) replaces it all],
+  [event flags 1, 2, 4, 8], [1, 4 and 8; never 2, so no expansion record follows],
+  [`Get`], [`get` on the pane's #file("ctl")],
+  [`Put`, `Delete`], [#word("Save"); a #word("Del") that does not ask],
+  [`Snarf`, `Cut`, `Paste`], [refused: the chords, #key("y"), #key("p")],
+  [acme's other builtins], [refused: `Putall`, `Zerox`, `Sort`, `Load`, `ID`, `Send`, `Tab`, `Indent`, `Local`, `Incl`, `Abort`],
+  [Edit], [no `< | >`, `X`, `Y`, `b B D e r w f`, no `\1`-`\9`; an alternation takes the first branch that matches, not the longest (#doc("fs", section: "edit"))],
+  [`win`], [#word("Tty") is a VT terminal pane; #file("pty/run") runs a line at its prompt and answers `exit N` and the output; with #word("Repl") bound, #word("Exec") on a source pane types the text into it],
+  [a directory window], [#word("Look") on a directory types `ls` into a terminal idle there, else opens one],
+  [the plumber], [none: #word("Look") on an `http://` or `https://` URL runs `xdg-open` (`open` on macOS); files, addresses and directories follow built-in rules],
+  [#key("Esc") selects what was typed], [#key("Esc") leaves insert mode, or goes back a pane (#doc("tags", section: "modes"))],
+)
+
 = Limits <limits>
 
 #pairs(