1 files changed, 42 insertions, 10 deletions
diff --git a/docs/typ/reference.typ b/docs/typ/reference.typ
index c27a6084..7cbcea29 100644
--- a/docs/typ/reference.typ
+++ b/docs/typ/reference.typ
@@ -97,9 +97,17 @@ other clients about, write and read on one open:
 #file("/commands"), #file("/status"), #file("/listeners"), a read-only
 #file("ctl"), #file("/log"), #file("/screen") and a terminal's
 #file("body") freeze at the open, so one read in several chunks never
-splices two moments; open again for now. Such an open, or a #file("run"),
-#file("event") or #file("pty/data") open, takes one of 64 open records;
-past that the open fails `too many open files`.
+splices two moments; open again for now.
+
+*Open records.* A session holds 64 open records, shared by every client.
+An open that keeps state takes one: such a snapshot, a #file("run"),
+#file("event") or #file("pty/data") open, a write open of #file("data"),
+#file("xdata"), #file("sel") or a text pane's #file("body"), and every
+write open of a command file (#file("look"), #file("exec"),
+#file("tagexec"), a #file("ctl")). A plain read of a pane's text takes
+none. Past 64 an open is refused `too many open files`, which a mount
+reports as EMFILE. Close what you open: a shell's `exec 3>$m/exec` holds
+its record until fd 3 is closed.
 
 *Held reads.* A read with nothing to give yet (a followed #file("log"),
 #file("event"), #file("pty/data"), #file("pty/run") before its answer)
@@ -162,7 +170,10 @@ was written when nothing by that name exists; `<path>:99 has no line 99`
 for a line past a file's end, `<path> has no page 99` for a PDF's page;
 `<path>: no match for regexp` or `<path>: address out of range` when an
 address fails), opens nothing, and leaves #file("look") reading empty; the
-write succeeds. A path too long to repeat whole gives up its middle to `…`.
+write succeeds. A look whose address fails says so and leaves open no file
+it opened. A look of `file:12:` reads as `file:12`: a trailing colon is
+dropped, as a click leaves it off. A path too long to repeat whole gives up
+its middle to `…`.
 
 A line written to #file("exec") is a #btn("B2") click:
 
@@ -275,7 +286,8 @@ Writes take settings and session builtins (`scope = .session` in
 - `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
   frontend owns the size, and when a column would lose its panes' minimum
-  rows (`size: too small for the panes, each its tag and 2 rows`).
+  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:
 `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)
@@ -435,6 +447,19 @@ pane's, so #file("addr"), #file("data"), #file("dot") and a `file:<addr>`
 look do not address it (a PDF's `:<n>` is its page); images and PDFs take
 no write (`this pane has no text`).
 
+*Image panes.* An image pane's tag reads `img petscii:on|off
+palette:commodore|terminal ascii:on|off <path>`. `petscii` is glyph art
+instead of pixels (#word("Petscii") toggles it); `palette` is which 16
+colours the glyph art uses, the C64's (`commodore`) or the terminal
+theme's own 16 (#word("Palette") toggles it); `ascii` is whether the
+printable ASCII bitmaps join the glyph set the matcher picks from
+(#word("Ascii") toggles it). Palette and ascii only change the glyph art.
+A terminal pane showing kitty graphics shows `petscii:on` or `petscii:off`
+after its directory in its tag; #word("Petscii") toggles it there too: on
+draws the program's images as glyph art instead of host pixels, off goes
+back to pixels. A terminal with no images shows the word only while it is
+on.
+
 *#file("sel")* reads the selected text; a write replaces it and leaves
 the written text selected, and one open's writes run on from the last.
 *#file("errors")* is write-only: text appended to the directory's
@@ -518,7 +543,8 @@ address lands on a rune boundary: `#n` or `L:C` inside a rune snaps to its
 start, a match covers the runes it touches, and a combining mark or a
 CRLF's `\r` is addressable alone.
 
-Refusals: `bad address syntax`, `no match for regexp`, `address out of range`, `addresses out of order` (`#100,#50`), `bad regular expression`.
+Refusals: `this pane has no text to address` (#file("addr"), #file("dot")
+and #file("limit") on a terminal, an image or a PDF), `bad address syntax`, `no match for regexp`, `address out of range`, `addresses out of order` (`#100,#50`), `bad regular expression`.
 
 sam details kept: `$-1` is the last line when the text ends in a newline,
 else the one before; with a final newline the empty place after it is a
@@ -655,7 +681,9 @@ Terminal panes also have #file("pty/"):
   (as the screen showed it: no colour, tabs expanded to blanks, `\r`
   progress collapsed, trailing blanks dropped; a paging command's text
   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` when the start scrolled away or was cleared). Or: `busy: <program> is running` (bare `busy` when text is typed at the prompt),
+  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),
   `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
@@ -673,7 +701,9 @@ One 64 KiB ring, one record a line, kept whether or not anyone reads it.
 An open freezes it and reads to EOF. Write `follow` to that open to then
 wait for each new record (`follow new` skips the history, as `tail -n0 -f`); `tail -f` never writes `follow`, so it sees nothing new. A follower
 the ring outran reads `lost N` first. A Restore hangs the follower up: dial
-again and read from `restore <path>`.
+again and read from `restore <path>`. A follower's read held when the
+Restore comes takes every queued record that fits first, so records written
+just before the Restore are not lost.
 
 #pairs(
   [`new <serial> <name>`, `del`, `rename`, `save`], [a pane made, closed, renamed (a terminal's too, as its shell changes directory), saved (`Save path` of a copy: `save <serial> <path>`, the path written)],
@@ -731,7 +761,9 @@ nothing. Inside a pardes pane it returns at once; a text the session cannot
 take is printed to stderr with why, and the exit is 1. From a directory
 whose name holds a newline or control byte, the pane is the session
 directory's. Outside a pardes pane it starts a new editor whose first pane
-the text is.
+the text is. It writes stdin through one open of the body, so any size up
+to a file's limit (256 MiB) arrives whole; past that it is cut, with a note
+saying so.
 
 With `Pager pardes`, a terminal's shell gets `PAGER`, `GIT_PAGER` and
 `SYSTEMD_PAGER` set to this pardes plus ` -` (the path quoted only when it
@@ -779,7 +811,7 @@ with Client(sys.argv[1]) as c:    # a socket path, or (ip, port)
   [rows a pane keeps], [its tag and 2],
   [msize], [65536 (64 KiB) offered],
   [connections], [16 Unix and TCP, 16 QUIC],
-  [opens holding state], [64],
+  [open records], [64 a session, every client's together],
   [held reads a connection], [128],
   [named mounts], [8],
   [command line], [1024 bytes; a held line or Edit block 1 MiB],