From 35e865eba278a1ef48a6ce160767d652a9c54ae8 Mon Sep 17 00:00:00 2001 From: Gabriel Schneider Date: Tue, 29 Sep 2026 06:22:15 -0300 Subject: 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 --- docs/fs.md | 45 +++++++++++++++++++++++++++++++-------------- 1 file changed, 31 insertions(+), 14 deletions(-) (limited to 'docs') 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, -`, : Modified (Exit again to discard)`, and a second `Exit` -with nothing edited since quits, throwing that text away; a scratch or a +`, : 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 `, `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 : ` 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, `:#q0,#q1`. +follow, the argument's text and where it came from, `:#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: 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 -- cgit v1.3