Recipes work through a pane of their own, its look and exec, and keep a command pane while their open lasts; the docs give cmd panes, the err grep, alt-screen prompts, /pager's refusals, Tty+ on a ctl, --, and theme failures in words

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

1 files changed, 23 insertions, 11 deletions

diff --git a/docs/typ/reference.typ b/docs/typ/reference.typ
index cf5e66d0..748f6f3c 100644
--- a/docs/typ/reference.typ
+++ b/docs/typ/reference.typ
@@ -44,7 +44,8 @@ safe), only `rmdir` of #file("/pane/<n>") or an empty #file("/col/<n>")
 removes. Tcreate is refused everywhere.
 
 #file("/index") rows are `serial kind dirty name column`, kind `text`,
-`term`, `pdf` or `image`, the name `<dir>/+New` for an unnamed scratch.
+`term` (a shell), `cmd` (a command's pane, no shell to type into), `pdf` or
+`image`, the name `<dir>/+New` for an unnamed scratch.
 Names may hold blanks, so split `head, col = row.rsplit(maxsplit=1)`, then
 `serial, kind, dirty, name = head.split(maxsplit=3)`. Names in
 #file("/index"), the log and a terminal's tag are escaped: a newline `\n`, a
@@ -55,9 +56,9 @@ is not UTF-8 `\xNN`, so a name decodes to the bytes it is.
 
 *Failure.* A write fails whenever what it asked for fails, and logs one
 `err <serial|-> <file>: <why>` record, with no `msg`; a write that succeeds
-logs none. So check a write's status first, and read the log's last `err`
-only for a write that failed (`echo x > f || tail -1 log`): after a success
-the tail may still hold an older `err`. Only writes log: a
+logs none. A refused write says why in the log's last `err` record, found
+with `grep '^err' log | tail -1`: after a refused Del, Exit or Restore the
+newest line may be `new N .../+Unsaved`. Only writes log: a
 refused open or truncation (an OTRUNC open such as `> data` after a failed
 `addr`), create or remove answers its error alone, as do a write to
 #file("pane/new") (`permission denied`) and a write on a read-only fid
@@ -96,7 +97,7 @@ write. An open that never wrote reads the session's last answer, from
 whichever client wrote it, so read on the open you wrote. A read is a stream: once read,
 the next read on that fid is EOF until the next write (or seek to 0). With
 other clients about, write and read on one open:
-#cmd("exec 3<>$m/look; echo x >&3; cat <&3; exec 3<&-")
+#cmd("exec 3<>$m/pane/$n/look; echo x >&3; cat <&3; exec 3<&-")
 
 *Snapshots.* #file("/index"), #file("/layout"), #file("/recent"),
 #file("/commands"), #file("/status"), #file("/listeners"), a read-only
@@ -206,7 +207,10 @@ A line written to #file("exec") is a #btn("B2") click:
 - Anything else is a command line, at most 1024 bytes, run as the guide
   says (#doc("tags", section: "command-panes")): typed into a terminal idle
   at an empty prompt, else run in a command pane. #file("exec") reads back
-  the command pane's serial; the log says `run <serial> <line>` and `exit <serial> <N|?>`. A reused pane's #file("body") keeps every earlier run
+  the command pane's serial, and while that open stays open the pane is its
+own: another client's command in the same directory gets a pane of its
+own. The log says `run <serial> <line>` and `exit <serial> <N|?>`. A
+reused pane's #file("body") keeps every earlier run
   above a `% <line>` row naming each command, so to take only the last
   run's output read from after the last `% ` row:
   #cmd("awk '/^% /{out=\"\"; next} {out = out $0 \"\\n\"} END {printf \"%s\", out}' body")
@@ -287,7 +291,9 @@ Writes take settings and session builtins (`scope = .session` in
   wrote). The Restore write is answered, then *every connection is hung
   up*: dial again, and restart a 9ns mount. The new log has a `new` per
   pane, `restore <path>`, then `restored <old> <new>` per pane and
-  `restoredcol <old> <new>` per column.
+  `restoredcol <old> <new>` per column. A Restore that fails says why in
+  words, a dump's ZON error with its line (`line 3: expected ','`); a
+  ThemeFile the dump names that fails to load changes nothing.
 - `Kill [word...]` (above), `Mount name dial`, `Unmount name`, `Theme x`.
 - `size C R` sizes a `--detach` session no frontend is attached to (160x50
   until then): from 20x6 to 4096x4096, else `invalid size`; refused while a
@@ -295,7 +301,9 @@ Writes take settings and session builtins (`scope = .session` in
   rows (`size: too small for the panes, each its tag and 2 rows`). A bad
   `size` is refused quoting the value it got (`"5 2"`).
 
-A write is refused whole, before anything runs, in Plan 9's words:
+A word that takes its argument after a `+` (`Tty+bash`) works on a ctl as
+in a tag. A write is refused whole, before anything runs, in Plan 9's
+words:
 `unknown control message "X"`, `wrong #args in control message "X"`, `bad value in control message ...`, or a word of the other ctl: `not a session control message "Undo": write it to pane/<n>/ctl`, `... "Delcol": write it to col/<serial>/ctl`, `not a window control message "X": write it to /ctl`. A builtin that would open a prompt (#word("Save") on a scratch)
 fails `control message needs its argument "Save"`. A line that fails as it
 runs fails with the editor's words (`Mount: already mounted`, `Save /root/x: access denied`), changing nothing.
@@ -677,7 +685,9 @@ Terminal panes also have #file("pty/"):
   Ctrl-C); read the live output stream (a consuming queue shared by
   readers, not a replay).
 - #file("pty/status"): one line, `cols rows busy`; busy is 1 while a
-  command runs or text is typed at the prompt.
+  command runs or text is typed at the prompt. A terminal whose program was
+  killed on the alternate screen is at its prompt once the shell draws one
+  there: busy is 0, and the next #file("pty/run") reads its output whole.
 - #file("pty/ctl"): `winsize C R` (at least 2 rows, fewer refused `invalid winsize: at least 2 rows`; at most 4096 a side), `sig INT|TERM|HUP|QUIT|KILL`, `exec` (restart the shell in its directory:
   refused on a command pane, `a command pane does not restart`; `exec: <dir>: no such directory` if it is gone; a shell that cannot start fails
   and leaves the old one running).
@@ -689,7 +699,7 @@ Terminal panes also have #file("pty/"):
   goes to a `+Pager` pane through the terminal's `pardes -` pager; the last 64 KiB, `exit N cut M` when M bytes were left
   out, bare `cut` only when the start of that output scrolled out of the
   scrollback; after a `clear`, the answer is what the command printed from
-  the clear onward). Or: `busy: <program> is running` (bare `busy` when text is typed at the prompt),
+  the clear onward). Or: `busy: <program> is running` (bare `busy` when text is typed at the prompt, `busy alternate screen` on the alternate screen with no prompt drawn),
   `exit ?` (no status reported, not a success), `error not run` (the shell
   refused the line, e.g. a fish syntax error), `error shell gone`, `error no prompt marks`, and on a command pane `error a command runs here, not a shell` (`error command done; not a shell` once it ended). A line written
   before a fresh terminal's first prompt waits for it. One line per run; a
@@ -746,7 +756,9 @@ at 200, ending in `…`. Control characters become spaces.
   closed one at its last (a PDF's is its page); a look at a row reopens it
   there.
 - #file("/status"): `pid`, `version`, `panes`.
-- #file("/pager"): write a directory (empty means the session's); a read on
+- #file("/pager"): write an absolute directory that exists (an empty line
+  is the session's; one not there is refused `no such directory`, ENOENT,
+  a relative one `the directory must be absolute`); a read on
   the same open answers the serial of that directory's one `+Pager`, made
   or emptied for it. It takes one directory a write. This is what
   `pardes -` uses.