Scripts find the session as m=\$PARDES_MOUNT, else 9p; SPC q quits; upper keeps a selection's newline and its tag words once; the reference takes line files, init errors, dumps, dials and Save on +Tutor

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

1 files changed, 28 insertions, 15 deletions

diff --git a/docs/typ/reference.typ b/docs/typ/reference.typ
index 14243384..5ef871a3 100644
--- a/docs/typ/reference.typ
+++ b/docs/typ/reference.typ
@@ -38,7 +38,7 @@ one-screen summary of this page.
 ```
 
 Panes and columns are named by serials the editor gives: stable while they
-live, never reused. Nothing is created by a listing, stat, walk or read:
+live, never reused (so they can have gaps). Nothing is created by a listing, stat, walk or read:
 only an open of #file("/pane/new") makes a pane (so `ls -l` and `find` are
 safe), only `rmdir` of #file("/pane/<n>") or an empty #file("/col/<n>")
 removes. Tcreate is refused everywhere.
@@ -104,10 +104,11 @@ kinds of #file("ctl") and a column's #file("exec") take one command a line.
 The whole write is checked first (a control character other than a tab
 fails it all, EINVAL); then lines run in order, and a failing line fails
 the write after the lines before it took effect, as acme's ctl does. Blank
-lines are skipped. A line runs once it is whole: a write's last line runs
-without its newline, except where a mount cut the write
-(#doc("building", section: "writes-through-a-mount")); end a write with a newline when its result
-matters. An `Edit` whose `{` or `a`/`c`/`i` text is still
+lines are skipped. A line runs at its newline; the last one, unended, runs
+after its open is closed, the close answered first, so its failure is only
+its `err` in the log: end a write with a newline when its result matters
+(#doc("building", section: "writes-through-a-mount")). `> exec` (a
+truncating open) is fine through a mount. An `Edit` whose `{` or `a`/`c`/`i` text is still
 open waits for the next write on that open. A line or Edit block over
 1 MiB is refused once (EINVAL), and the rest of it, through its newline,
 is dropped.
@@ -283,8 +284,9 @@ Explicit paths skip that search:
   [`/n/peer/pane/2/body`], [a mounted session: the peer's #file("/pane/2/body")],
 )
 
-`--mount=peer=work` or `Mount peer <dial>` mounts a session name, an
-absolute socket path, `unix!/path`, `tcp!host!port` or `quic!host!port`;
+`--mount=peer=work` or `Mount peer <dial>` mounts a dial: `unix!/path`,
+`/path`, `tcp!<numeric-ip>!<port>`, a session name, or with `-Dquic`
+`quic!…`; a missing socket is ENOENT, `no such socket`;
 `Unmount peer` removes it. #word("Mount") dials at once and fails if
 nothing answers (`dial failed: no answer`, `timed out`, `hung up`); with no
 dial it is `wrong #args`, and any other `x!y` `bad dial address`, both
@@ -490,7 +492,9 @@ 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
-255 bytes a component. The ctl word `name x` takes all after its one
+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
 blank; a second blank there is refused rather than read as the name's
 first byte. A directory (`/`, `~`, `foo/`) is no file name: refused,
 EISDIR (`name: /home/u is a directory, not a file`).
@@ -544,7 +548,8 @@ takes:
   asks which takes the rows; a click, a ctl write or an `init` line never
   asks and gives them to the pane above; `Del k`/`Del j`, or
   #word("DelAbove")/#word("DelBelow"), give its rows to the pane above or
-  below), `Save [path]` (making the directories the file goes in first,
+  below), `Save [path]` (bare, on a `+`-named pane that is no output,
+  such as `+Tutor`, it asks for a path; making the directories the file goes in first,
   whichever name it writes), #word("Collapse"), #word("Undo")/#word("Redo")
   (256 steps each), `Find pat`, `Edit ...`, `Tty [shell]` (a new terminal
   in its directory), #word("Delcol") for its column, and
@@ -816,7 +821,7 @@ at 200, ending in `…`. Control characters become spaces.
 - #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 regular file `not
-  a directory`, ENOTDIR), one line; then, on the same open, the text to
+  a directory`, ENOTDIR), one line; what follows that line, on the same open, is the text to
   page, escapes and all. A read of that open answers the serial of the
   directory's one `+Pager`, made or emptied for it, once the text is in. This is what
   `pardes -` uses; from a directory you may not write, it pages into the
@@ -840,7 +845,8 @@ its directories. What the session refuses (a bad name; a name under a
 directory you may not search or write, `permission denied`) is printed and
 the exit is 1. `--` ends the options (`pardes -- -name`).
 `pardes --wait FILE` (`-w`) returns 0 when the pane showing FILE is
-deleted, 1 when the session goes away or no longer answers; with
+deleted, 1 when the session goes away (against a dead `$PARDES_9P` it
+says the session is gone); with
 `PARDES_9P` set but no pane of its own it opens FILE in that session and
 waits there. Bare `pardes` in a pane refuses and names `--nested`, which
 starts a separate session whose shells do not forward to it.
@@ -906,9 +912,13 @@ it was.
   (8×16 before any), as CSI 14, 16 and 18 t do.
 - *Config.* The startup file is `$XDG_CONFIG_HOME/pardes/init` when that is
   absolute, else `~/.config/pardes/init` (macOS:
-  `~/Library/Application Support/pardes/init`); a line that fails is
-  skipped, and text that is no builtin is not run. A dump keeps panes,
-  columns, tags, selections, the theme and changed settings; a terminal
+  `~/Library/Application Support/pardes/init`). A line that fails is a
+  notice and `err - init file line N: why`, and the rest still run; a
+  setting only the other frontend has (`Font` in a terminal) is skipped;
+  text that is no builtin is not run; saving the init file in a pane
+  applies its settings again. A dump keeps panes, columns, tags,
+  selections, the theme and changed settings, but not a picture or a PDF
+  that is on disk (Restore reads it from there); a terminal
   comes back with its last MiB of output and a new shell in its old
   directory; undo history and REPL bindings are not kept. A crash appends
   two lines (build, time, platform, pid; the panic message) to `crashes`
@@ -943,7 +953,10 @@ A session listens on `$XDG_RUNTIME_DIR/pardes-9p-<name>.sock` (else under
 `$XDG_RUNTIME_DIR/9p/pardes/<name>`. Its pane shells get `PARDES_PID`,
 `PARDES_9P` and `PARDES_PANE`. A dead session's registry entry stays
 listed and answers `Input/output error`: name the session, never glob.
-Under `9ns --unix SOCK -- cmd` the session is `$NINE_MOUNT` itself.
+Under `9ns --mntgen` (which sets `NINE_MNTGEN=1`) a session is at
+`$NINE_MOUNT/<service>/<name>`, pardes's `$NINE_MOUNT/pardes/<name>`, and
+every pane pardes spawns gets it as `$PARDES_MOUNT`. Under `9ns --unix SOCK
+-- cmd` the session is `$NINE_MOUNT` itself, and `$PARDES_MOUNT` is unset.
 plan9port's `9p write` opens with OTRUNC, so it replaces a whole
 #file("body"); append with `>>` through a mount. Through a FUSE mount
 bash's `read -t` cannot time out: wrap a follow loop in `timeout`. The