An Edit's held write: < | > commands no longer block their 9P connection (answered like a held read, so a status read or a filter reading the session's own mount runs beside it), a Tflush or hang-up of the write kills the commands' process groups and changes nothing; e loads by Get's way (asked once, clean after, undo puts the name back); ~ in e r w f B; B checks every name first; an Edit that runs commands is a write of its own, refused up front with other lines; Edit's +Errors output keeps the keyboard where it was; X goes in pane order; a refused write open says its errno; the reference's Coming from acme rows say what Get file's undo, failure and directory refusal, Putall's answer, Zerox across Dump and Incl's directories now do

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

1 files changed, 24 insertions, 15 deletions

diff --git a/docs/typ/reference.typ b/docs/typ/reference.typ
index 321860d6..efc08a9b 100644
--- a/docs/typ/reference.typ
+++ b/docs/typ/reference.typ
@@ -689,21 +689,30 @@ open file whose line matches. Commands:
 
 - `x y g v c a i d s p = m t u` and `{ }`.
 - `X`/`Y` run a command in each open file whose line (` +. /path`, `'` when
-  edited) matches, or does not: `X/'/w` writes every edited file.
-- `b` makes a file current, `B` opens files, `D` closes panes (an edited one
-  on the second asking, as #word("Del")).
-- `e` reads a file over the whole text and names the pane after it, `r`
-  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. `f` names the pane and prints
-  its line.
+  edited) matches, or does not, in the order the panes were opened (as
+  #file("index") lists them): `X/'/w` writes every edited file.
+- `b` makes a file current; `B` opens files, every name checked before any
+  opens; `D` closes panes (an edited one on the second asking, as
+  #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
+  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. `f` names the pane and prints its line. File names
+  are relative to the file's directory, and `~` is the home directory.
 - `<cmd` replaces dot with what `cmd` writes, `|cmd` pipes dot through it,
   `>cmd` sends dot to it and prints what it writes.
 
 Each command runs in its file's directory through #word("Shell"), off the
-loop, so the editor goes on; the write that ran the Edit is answered when
-they are done, and a line after it in the same write is refused. A command
-that fails (an exit status, 10 seconds, 1 MiB of output) fails the Edit, its
-stderr in `+Errors`. Each file's changes are one undo step, applied only if
+loop, so the editor goes on. 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
+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
+them. A command that fails (an exit status, 10 seconds, 1 MiB of output)
+fails the Edit, its stderr in `+Errors`. Each file's changes are one undo step, applied only if
 every command succeeds; a failure changes nothing and fails the write with
 acme's words (`Edit: no substitution`), as does a file edited while the
 commands ran. An `x` that finds nothing succeeds silently. `p`, `=` and `>`
@@ -1049,12 +1058,12 @@ 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; in a directory pane it reads the directory again (also `get` on #file("ctl"))],
+  [`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"))],
   [`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],
-  [`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],
+  [`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],
+  [`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],
-  [`Incl`], [#word("Incl"): for the session, not per window, seeded with `/usr/include` and `/usr/local/include`; a name found nowhere else (`stdio.h`, `<stdio.h>`) is tried there],
+  [`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")],
   [`Font`, `Send`, `ID`], [#word("Font"); #word("Repl") and #word("Exec"); `$winid`],