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]>

3 files changed, 73 insertions, 27 deletions

diff --git a/docs/typ/guide.typ b/docs/typ/guide.typ
index 1079b763..9f45350b 100644
--- a/docs/typ/guide.typ
+++ b/docs/typ/guide.typ
@@ -116,7 +116,10 @@ column's last pane; a pane opened from a pane's text (a look, #word("Tty"),
 biggest; a command pane goes to the last column. #word("New") in a pane's
 tag opens a `+New` scratch named in that pane's directory, in that pane's
 column; from a column tag, in that column and the session's directory.
-Every new pane but a command pane takes the keyboard. No pane is made
+Every new pane takes the keyboard, except a command pane and a listing
+(`+Search`, #word("Recent"), #word("Jumplist"), #word("Themes"), `Fonts`),
+which opens below the pane that asked and leaves it the keyboard, so
+#keys("n", "N") walk the listing and #key("Tab") runs a row. No pane is made
 shorter than its tag and two rows; where there is no room the pane is
 refused. `Placement pardes` instead fills an empty column whose tag asked
 or has the keyboard, puts a scratch or a shell under the pane that asked,
@@ -136,7 +139,8 @@ a terminal there. A URL opens in the browser. #word("Find") `name` lists the fil
 below the pane's directory whose names hold it; #word("Grep") `text` lists
 the lines that contain that text, literally (ASCII case aside, no regular
 expression), in files under every pane's directory. Both land in `+Search`,
-a place per row for #btn("B3").
+a place per row for #btn("B3"); a directory the walk cannot open is
+skipped, and the list ends `N directories skipped: permission denied`.
 
 A relative path is looked for where the click was, then where you have
 been: first in the looking pane's own directory, then in the directory of
@@ -154,7 +158,9 @@ command pane, a terminal of its own:
 
 #tag("Kill Save Collapse Del", path: "/home/me/src (make) exit 0")
 
-Its tag says `running`, then `exit N`. The next command for the same
+Its tag says `running`, then `exit N`. Its directory is the one it
+started in, and relative looks in it resolve there, whatever the command
+did with `cd`. The next command for the same
 directory reuses a command pane that has finished (from a column tag, only
 one in that column), below what it showed; a pane still running, or one a
 background job still prints to, is never reused, so a second command
@@ -278,8 +284,10 @@ turns one off):
 One answer jumps; several open a list where #key("Enter") on a row goes
 there. In insert mode #key("Tab") after a `.` lists the candidate
 declarations and inserts nothing. A format or a rename within the file is
-one undo step; a rename that reaches other files opens a preview instead
-of changing them.
+one undo step. A rename that reaches other files applies nothing: it opens
+a `+Search` preview of the edits, telling the server first of every open
+file of its language so those are included. A server is `not started yet`
+until its first query.
 
 = Sessions <sessions>
 
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
diff --git a/docs/typ/scripting.typ b/docs/typ/scripting.typ
index 7bf04efe..f3aa5a18 100644
--- a/docs/typ/scripting.typ
+++ b/docs/typ/scripting.typ
@@ -59,6 +59,7 @@ and #file("exec"), not the root's (see the traps):
   [fill, name, save, close], [#cmd("printf 'hello\\n' > $p/body # > replaces, >> appends\necho \"$PWD/notes.txt\" > $p/name\necho Save > $p/ctl\nrmdir $p")],
   [say something], [#cmd("echo 'Msg hello' > $p/exec")],
   [replace everywhere], [#cmd("echo 'Edit ,x/foo/c/bar/' > $p/ctl\ngrep -c foo $p/body # 0: none left")],
+  [insert after a match], [#cmd("echo 'Edit /old/a/ text/' > $p/ctl # from dot; one undo step")],
   [replace one match], [#cmd("echo /old/ > $p/addr && printf new > $p/data")],
   [delete line 3], [#cmd("echo 3 > $p/addr; : > $p/data")],
   [select line 3, read it], [#cmd("echo 3 > $p/addr; cp $p/addr $p/dot; cat $p/sel")],