The reference takes rounds 38 and 39: a file read's directory, permission and device refusals, an Undo back to unsaved edits being no change on disk, an Edit filter writing its own ctl without truncating, n in a command pane, a name write's one line, Putall's Zerox pair, bare Tab from the root ctl, and Get and e over a small scratch

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

1 files changed, 12 insertions, 9 deletions

diff --git a/docs/typ/reference.typ b/docs/typ/reference.typ
index f094a224..ed88905a 100644
--- a/docs/typ/reference.typ
+++ b/docs/typ/reference.typ
@@ -123,6 +123,8 @@ sam command pardes's #word("Edit") leaves out, `B <cmd`):
   [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],
 )
 
+A file pardes reads (#word("Get"), #word("Look"), #word("Edit")'s `e` and `r`) that is a directory where a file is wanted says `is a directory` (EISDIR), an unreadable one `permission denied` (EACCES), and a device (`/dev/zero`, a tty) `not a regular file` (EIO), never read to the stream limit; #word("Incl") of a file says `not a directory` (ENOTDIR).
+
 The `err` record has the words; a shell sees only the errno.
 
 Not failures: a #word("Look") that finds nothing (it answers nothing and logs one
@@ -521,8 +523,8 @@ renames the buffer (relative to the pane's directory) and marks nothing
 dirty; #word("Save") then writes under the new name. A name takes any byte
 a file name can hold, blanks, control bytes and bytes not UTF-8 included,
 so what #file("name") reads writes back as it was; refused (EINVAL) are
-an empty name, a second line and a NUL (`bad character in file name: an
-empty name`, `...: a NUL`). Up to
+an empty name, a NUL (`bad character in file name: an
+empty name`, `...: a NUL`) and a second line, by the write that brings it (`invalid file name: one name a write, on one line`). Up to
 255 bytes a component. A name that can never be valid (a terminal's, a
 component over 255 bytes, a path too long) is refused by the write that
 holds it. The ctl word `name x` takes all after its one
@@ -600,7 +602,7 @@ takes:
 
 A file changed on disk reloads by itself only when the buffer has no
 unsaved edits; otherwise it stays dirty, says `<name> changed on disk (get reloads it, Save overwrites it)`, logs `changed <serial>`, and its next
-#word("Save") warns once.
+#word("Save") warns once. A file whose disk text is what the pane was read or saved as is no change: an #word("Undo") back across #word("Get") `file` or `e` to unsaved edits says nothing changed, and #word("Save") writes it.
 
 == Addresses and data <addresses>
 
@@ -696,7 +698,8 @@ open file whose line matches. Commands:
   #word("Del")).
 - `e` loads a file over the whole text as #word("Get") `file` does, once the
   rest of the Edit is done: the pane takes its name and is clean, one undo
-  step puts both back, and unsaved edits are asked about once; the file
+  step puts both back, and unsaved edits are asked about once (a scratch
+  under 100 bytes is not); the file
   takes no other command in that Edit. `r` reads a file over dot. `w` writes
   all of it, or the address, to its file or a name; all of it to its own
   name leaves it clean. A `w` to its own file changed on disk since it was
@@ -711,7 +714,7 @@ Each command runs in its file's directory through #word("Shell"), off the
 loop, so the editor goes on, with what a pane's command is given:
 `$PARDES_MOUNT`, `$PARDES_9P`, `$PARDES_PID`, and `$winid` the Edit's pane. The write that ran the Edit is held and
 answered when they are done, its connection serving other requests
-meanwhile (a command may read the session through its mount); a flush of
+meanwhile (a command may read the session through its mount; one that writes the #file("ctl") its Edit came by must not truncate it, `1<>ctl` rather than `>ctl`, as Linux holds the inode lock through an O_TRUNC open and the write waits out the 10-second limit); a flush of
 that write (an interrupted writer) kills the commands and changes nothing.
 Such an Edit is a write of its own: one with other lines is refused before
 any runs. One Edit's commands run at a time in a session, at most 1024 of
@@ -937,7 +940,7 @@ A command pane runs in the directory it started in, whatever its command
 does with `cd`, and a relative #word("Look") in it resolves there. The next command
 for that directory reuses a finished one (from a column tag, only one in
 that column); one still running, one a background job still prints to, or
-one a #file("exec") open still holds is never reused.
+one a #file("exec") open still holds is never reused. In a command pane, #key("n") walks that pane's own `file:line` places first (make's errors), whichever pane was walked last, then on through the others.
 
 = Find and Grep <find-grep>
 
@@ -1064,11 +1067,11 @@ with Client(sys.argv[1]) as c:    # a socket path, or (ip, port)
   [`addr` reset on first open], [#file("addr") is the pane's; no open resets it (write `0`)],
   [OTRUNC on `data` ignored], [`: > data` deletes the addressed text; OTRUNC on #file("body") (`9p write`) replaces it all],
   [event flags 1, 2, 4, 8], [1, 4 and 8; never 2, so no expansion record follows],
-  [`Get`], [#word("Get") reads the file again, refusing unsaved edits once; `Get file` loads that file into the pane, which takes its name, and one that fails changes nothing; #word("Undo") after it, or after #word("Edit")'s `e`, puts the old name back with the old text and its saved state; in a directory pane #word("Get") reads the directory again and `Get file` is refused (#word("Look") opens the file) (also `get` on #file("ctl"))],
+  [`Get`], [#word("Get") reads the file again, refusing unsaved edits once (a scratch under 100 bytes unasked, as #word("Del") closes it); `Get file` loads that file into the pane, which takes its name, and one that fails changes nothing; #word("Undo") after it, or after #word("Edit")'s `e`, puts the old name back with the old text and its saved state; in a directory pane #word("Get") reads the directory again and `Get file` is refused (#word("Look") opens the file) (also `get` on #file("ctl"))],
   [`Put`, `Delete`, `Load`], [#word("Save"); a #word("Del") that does not ask; #word("Restore")],
-  [`Putall`], [#word("Putall"): every pane with unsaved edits to a file is saved, a refused one said; with a refusal, its write is answered once the other saves have landed],
+  [`Putall`], [#word("Putall"): every pane with unsaved edits to a file is saved, a #word("Zerox") pair once, a refused one said; with a refusal, its write is answered once the other saves have landed],
   [`Zerox`], [#word("Zerox"): a second pane on the buffer, one text, undo and unsaved state, its own scroll and cursor; an event reader on one hears no edit made through the other; the twins are kept across #word("Dump") and #word("Restore")],
-  [`Tab`], [#word("Tab") `N`, 1-16: for every pane, not per window; bare, it says the width],
+  [`Tab`], [#word("Tab") `N`, 1-16: for every pane, not per window; bare, it says the width, from the root's #file("ctl") as from a pane's #file("exec")],
   [`Incl`], [#word("Incl"): for the session, not per window, seeded with `/usr/include` and `/usr/local/include`; it takes absolute (or `~`) directories that exist, and `Incl -` alone clears the list; a name found nowhere else (`stdio.h`, `<stdio.h>`) is tried there],
   [`Indent`], [always on: #key("Enter"), #key("o") and #key("O") keep the line's indent as it is],
   [`Snarf`, `Cut`, `Paste`], [refused: the chords, #key("y"), #key("p")],