The docs take round 35: cloud9's errno table, Restore's parser words, insert after a match, LookWord list rows, the last-run awk without exit, command pane directories, rename previews, listings that keep the keyboard, set-value toggles, pty/run one line a write, /pager resolving, PDF :N:H, skipped directories and Lspinfo

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

1 files changed, 59 insertions, 22 deletions

diff --git a/docs/typ/reference.typ b/docs/typ/reference.typ
index 80fbb1ac..feabd4e2 100644
--- a/docs/typ/reference.typ
+++ b/docs/typ/reference.typ
@@ -65,12 +65,34 @@ refused open or truncation (an OTRUNC open such as `> data` after a failed
 (`bad use of fid`). Errors are words (Plan 9's where pardes has none of its
 own), never a C library string; a bad setting value is quoted, the value
 itself (`bad value in control message; takes on, off "maybe"`); a ctl
-refusal quotes the offending word alone (`wrong #args in control message "Newcol"`). Through 9ns the kernel sees an errno 9ns
-reads from those words (cloud9's `9ns/src/nine.zig`, `enameToErrno`):
-`control message`, `invalid` or `bad ` is EINVAL (malformed input); `no such`, `not found` ENOENT; `in use` EBUSY; `no space` ENOSPC; `denied`
-EACCES; anything else, such as `no match for regexp`, `address out of range`, `Modified` or an `Edit` command pardes leaves out (`w is a sam command pardes's Edit leaves out`), EIO; no refusal reads as EOPNOTSUPP.
-The `err` record has the words; a shell sees only the errno, most often
-`Invalid argument` or `Input/output error`.
+refusal quotes the offending word alone (`wrong #args in control message "Newcol"`). Through 9ns the kernel sees an errno 9ns reads
+from those words (cloud9's `fs.enameErrno`): the first of these that the
+words hold, case aside, wins, and anything else is EIO (`Modified`, an
+`Edit` command pardes leaves out):
+
+#pairs(
+  [`control message`], [EINVAL],
+  [`interrupt`], [EINTR],
+  [`shut down`], [EIO],
+  [`not exist`, `not found`, `no such`], [ENOENT],
+  [`exists`], [EEXIST],
+  [`not empty`], [ENOTEMPTY],
+  [`not a dir`], [ENOTDIR],
+  [`is a dir`], [EISDIR],
+  [`permission`, `denied`], [EACCES],
+  [`read-only`, `read only`, `readonly`], [EROFS],
+  [`no space`], [ENOSPC],
+  [`not allowed`, `not permitted`, `cannot`], [EPERM],
+  [`fid`], [EBADF],
+  [`bad offset`, `invalid`, `bad `], [EINVAL],
+  [`busy`, `in use`], [EBUSY],
+  [`too long`], [ENAMETOOLONG],
+  [`too many open files`], [EMFILE],
+  [`not supported`, `unsupported`], [EOPNOTSUPP],
+  [acme's address and argument words: `no match for regexp`, `no previous regular expression`, `address out of range`, `addresses out of order`, `past end of body`, `written to addr failed`, `not locked by this open`, `too small for the panes`, `owns the size`, `no question asked`, `answer takes`], [EINVAL],
+)
+
+The `err` record has the words; a shell sees only the errno.
 
 Not failures: a look that finds nothing (it answers nothing and logs one
 `err`), an Edit `x` that matches nothing, #word("Undo") with nothing to
@@ -165,10 +187,13 @@ files.
 - A whole line of a diff pane written to #file("look") is the look a
   #btn("B3") click on its first column makes. The line is matched in the
   pane from its cursor row on, wrapping, and the first match wins.
-- A `+PdfSections` row is `file.pdf:PAGE:SECTION`; a look at a section that
-  is not there, or not on that page, fails as a miss.
-- A plain word selects its next place after dot, wrapping (`LookWord list`
-  on the root ctl lists every place in a `+Search` pane instead). In a
+- On a PDF pane `:N:H` is page N, search hit H, as `file.pdf:N:H` is.
+  Only a `+PdfSections` row's second number is a section,
+  `file.pdf:PAGE:SECTION`, and only such rows are checked against the
+  outline: a section not there, or not on that page, is a miss.
+- A plain word selects its next place after dot, wrapping. `LookWord list`
+  on the root ctl lists a row per line holding it in a `+Search` pane
+  instead; the next word looked at in that directory refills it. In a
   terminal a word is always listed, rows spelled `@p3:12:5-9`.
 
 A miss logs `err <serial> look: ...` (`no match for "zzq:#3"` quoting what
@@ -193,10 +218,12 @@ A line written to #file("exec") is a #btn("B2") click:
   (set it with #file("addr") and `dot=addr` first): #word("Hover") fills
   `+Hover`; `Rename new` renames the symbol in the file and says how many
   ranges it changed (on the message row, and so in the log) without listing
-  them, fails when there is nothing to rename, and lists the files of a
-  rename the server spreads over several in `+Search`;
+  them, and fails when there is nothing to rename. One that reaches other
+  files applies nothing: it opens a `+Search` preview of the edits, which
+  is the pane the write answers, and says how many it lists;
   #word("Diagnostics") and #word("Symbols") list the file's in `+Search`;
-  #word("Lspinfo") says which server serves the file and its state;
+  #word("Lspinfo") says which server serves the file and its state (`not
+  started yet` until its first query starts it);
   #word("Lspwhy") narrates the last query step by step (in `+Lsp`). The
   write returns once the answer is in; a pane with no file is refused.
 - acme's words run as pardes's where it has one (`Put` is #word("Save"),
@@ -212,8 +239,8 @@ 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")
+  run's output read from after the last `% ` row, leaving out its `exit N`:
+  #cmd("awk '/^% /{out=\"\"; next} /^exit [0-9?]+/{next} {out = out $0 \"\\n\"} END {printf \"%s\", out}' body")
   From a pane whose directory is gone nothing runs: `exec: <dir>: no such directory` (ENOENT).
 
 The root's #file("look") and #file("exec") act at the active pane and log as
@@ -292,8 +319,10 @@ Writes take settings and session builtins (`scope = .session` in
   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. 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.
+  the parser's words, a ZON error with its line (`line 3: expected ','`),
+  so the errno a mount gives depends on them (usually EIO): read the `err`
+  record for why. 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
@@ -468,6 +497,10 @@ 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.
+#word("Petscii") and #word("Ascii") (`on|off`), #word("Palette")
+(`commodore|terminal`), and a PDF's #word("PdfFit") (`width|height`) and
+#word("PdfTint") (`disabled|filtered|full`) take the value their tag word
+shows and set it; bare, they step to the next.
 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
@@ -691,7 +724,10 @@ Terminal panes also have #file("pty/"):
 - #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).
-- #file("pty/run"): one line at the shell's prompt, answered on the same
+- #file("pty/run"): one line a write (two lines in one write are refused
+  whole; through a mount a shell's `printf` of two lines arrives as two
+  writes, so the first runs and the second is refused EINVAL), at the
+  shell's prompt, answered on the same
   open: #cmd("exec 3<>$m/pane/$n/pty/run; echo make >&3; cat <&3; exec 3<&-")
   The answer's first line is the header: `exit N` then the command's output
   (as the screen showed it: no colour, tabs expanded to blanks, `\r`
@@ -756,12 +792,13 @@ 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 an absolute directory that exists (an empty line
-  is the session's; one not there is refused `no such directory`, ENOENT,
-  a relative one `invalid directory "<dir>": must be absolute`, EINVAL); a read on
+- #file("/pager"): write a directory, `~` expanded and resolved (an empty
+  line is the session's; one not there is refused ENOENT, a relative one
+  EINVAL, one you may not write `permission denied`); 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.
+  `pardes -` uses; from a directory you may not write, it pages into the
+  session's `+Pager`.
 - #file("/listeners"): the session's dial addresses, a line each
   (#doc("building", section: "listeners")).
 - #file("/os/"): existing regular files take read, write and truncation to