From cda0b279a24e8becc3c2836c42e7321830e2467a Mon Sep 17 00:00:00 2001 From: Gabriel Schneider Date: Thu, 1 Oct 2026 05:37:37 -0300 Subject: 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 --- docs/typ/reference.typ | 34 +++++++++++++++++++++++----------- 1 file changed, 23 insertions(+), 11 deletions(-) (limited to 'docs/typ/reference.typ') 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/") or an empty #file("/col/") removes. Tcreate is refused everywhere. #file("/index") rows are `serial kind dirty name column`, kind `text`, -`term`, `pdf` or `image`, the name `/+New` for an unnamed scratch. +`term` (a shell), `cmd` (a command's pane, no shell to type into), `pdf` or +`image`, the name `/+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 : ` 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 ` and `exit `. 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 ` and `exit `. A +reused pane's #file("body") keeps every earlier run above a `% ` 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 `, then `restored ` per pane and - `restoredcol ` per column. + `restoredcol ` 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//ctl`, `... "Delcol": write it to col//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: : 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: is running` (bare `busy` when text is typed at the prompt), + the clear onward). Or: `busy: 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. -- cgit v1.3