The docs: Kill leaves bash and fish to run the rest of a line, index rows split from the right, busy names its program, chord follow-ups, /commands rows, Exit's second refusal

Dogfood round 16 took these literally and found them false: bash ran the
echo after Kill as fish does; a name with spaces broke split(maxsplit=3)
since the row ends with the column serial; pty/run's busy line names the
program; /commands rows end in a description; a second Exit refusal names
only panes edited since.

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

1 files changed, 31 insertions, 14 deletions

diff --git a/docs/fs.md b/docs/fs.md
index 0da2ccd0..e7c85681 100644
--- a/docs/fs.md
+++ b/docs/fs.md
@@ -167,8 +167,10 @@ builtins, one a line, at whichever pane has the keyboard as each runs --
 `Newcol`, `Dump`, `Mount name dial`, `Theme ink`, `Verbose off`; `Exit`,
 which quits the editor as acme's does (it refuses once, naming each pane with
 unsaved text, a `+New` scratch of 100 bytes or more too, in one line,
-`<name>, <name>: Modified (Exit again to discard)`, and a second `Exit`
-with nothing edited since quits, throwing that text away; a scratch or a
+`<name>, <name>: Modified (Exit again to discard)`, whether it came
+through a `ctl` write or a click; an `Exit` after more editing refuses
+again naming only the panes edited since the last refusal, as acme's does,
+and an `Exit` with nothing edited since quits, throwing all of it away; a scratch or a
 command's output under 100 bytes is not asked about, as acme's winclean
 asks about no small unnamed window (so a scratch's `dirty` of 1 in `/index`
 blocks nothing until it holds 100 bytes: it has no file to be out of step
@@ -209,9 +211,10 @@ shell's group, so there is none to signal: Kill says `Kill: no job to
 signal`, and a write of it to `ctl` fails with that; with nothing running
 it says `Kill: nothing running`; and, of a typed line, only the
 foreground job, after which what the rest of the line does is the shell's
-affair: of `sleep 30; echo done` typed at a prompt, fish goes on and runs
-the `echo`, and bash abandons the line, as each does when a job it waits
-on is killed --
+affair: of `sleep 30; echo done` typed at a prompt, bash (saying
+`Terminated`) and fish (saying `Job 1, 'sleep 30' terminated by signal
+SIGTERM`) both go on and run the `echo`: SIGTERM, unlike an interrupt,
+ends only the job, not the line --
 and reads every setting there is, one a line, in the words a write of it
 takes (`Verbose on`, `WindowOpacity 70`, `PanelSlide off`, `DumpDir
 <the directory in effect>`, `LocationsConfig ...`), so writing what it reads
@@ -256,10 +259,19 @@ performed what it asked for (a save written, a shell started). A click on
 the same word, or the word written to `exec`, still opens its prompt.
 
 `/commands` lists every builtin the registry holds, in registry order, one
-a line: its word, `arg` when it takes one, `root` or `pane` for the ctl
-that takes it, and for a setting that chooses among words those words,
-comma-joined, e.g. `Newcol root`, `Save arg pane`, `Verbose arg root on,off`,
-`Placement arg root acme,pardes`. Such a setting written bare steps to its
+a line: its word, `arg` when it takes one, `root`, `pane` or `both` for the
+ctl that takes it, for a setting that chooses among words those words,
+comma-joined, then ` -- ` and one sentence of what it does (a builtin's doc
+comment's first sentence, a setting's doc), e.g.
+
+```
+Newcol root -- An empty column right of the keyboard's, its tag taking the keyboard.
+Save arg pane -- Write the pane's text to its file, or to the file its argument names.
+Verbose arg root on,off -- A builtin says its own name on the message row as it runs, on or off.
+Placement arg root acme,pardes -- Where a new pane goes: acme, as makenewwindow does, or pardes, the older rules.
+```
+
+Every builtin has its sentence; a test fails the build of one without. Such a setting written bare steps to its
 next value, so a two-valued one flips (`Crt`, `Placement`, `BootShell`), as
 its word clicked in a tag does; a value it does not take is refused with
 `bad value in control message; takes ...` naming those it does. It is
@@ -709,10 +721,12 @@ for every line the editor says (with `verbose` on, that includes each
 builtin announcing itself as it runs, on purpose: the log says which ran --
 unless the builtin then says something of its own that starts with its
 name, `Kill: nothing running`, which takes the announcement's place; a
-builtin that fails a ctl write is logged by that write's `err` alone, no
-announcement and no `msg`, so the same failure again is the same record
+builtin that fails its write (`ctl`, `exec`, `/tagexec` or a column's
+`exec`) is logged by that write's `err` alone, no announcement and no `msg`, so the same failure again is the same record
 again; a line said again word for word is counted, `msg 3 Undo: nothing to
-undo (x40)`, as `err` is (below); its serial is the pane it ran at, `-` when the keyboard was on a
+undo (x40)`, as `err` is (below); a text past 256 bytes is cut there,
+between words, and ends in an ellipsis, `…`, as an `err`'s reason is past
+200; its serial is the pane it ran at, `-` when the keyboard was on a
 column or workspace tag, or the line came to the root's ctl, `/tagexec` or
 a column's ctl or exec), and `err <serial|->
 <file>: <why>` for every write or truncation the tree refused or that
@@ -746,7 +760,9 @@ action's case says where: `x`/`l` a click executed or looked at in the tag
 of the tag. The flag is acme's: 1 the text is a builtin's word, 2 the range
 was expanded from a click (a second record gives the original range), 4 (a
 look) the text is a file name or address, 8 (an exec) chorded: two records
-follow, the argument's text and where it came from, `<file>:#q0,#q1`.
+follow, the argument's text and where it came from, `<file>:#q0,#q1`, each
+with no place of its own: offsets `0 0` and flag 0, `Mx0 0 0 5 hello` (as
+acme's exec.c:182 writes them).
 Written back, an `X`/`x` record executes and an `L`/`l` record looks, as
 the click would have. A chorded one (flag 8) runs with its argument: the
 record after it in the same write, else the one kept from the click; its
@@ -814,7 +830,8 @@ are read so that the answer costs the editor a bounded amount. `exit ?` is a
 command whose end mark carried no status, which is not a success; `error out
 of memory` is an answer that could not be made. The header is always the
 whole first line. It reads
-`busy` at once when a command is running or text is typed at the prompt
+`busy: <program> is running` at once when a command is running (bare `busy`
+where the host cannot name the program, and when text is typed at the prompt)
 -- a run is a line typed at the shell's prompt, so a program holding the
 terminal (a REPL, `less`) takes none: write to `pty/data` for it --
 which is also when the third field of `pty/status` reads 1. `pty/status` is