From 6dacd7778b846967fb945297420148e783f48f95 Mon Sep 17 00:00:00 2001 From: Gabriel Schneider Date: Tue, 29 Sep 2026 05:33:31 -0300 Subject: The docs: which writes fail, mark for one undo step, directory looks, the skill's log line Round 15's doc findings: one table of which files fail a write and which only say so; mark to make a loop's data writes one undo step; the 100-byte scratch exemption and the chord write-back in the skill; the skill's log line with ask, answer, changed, newcol, delcol and the restored records; a directory looked at opens a terminal that runs ls, and why; a plain word in a terminal is listed in +Search, its rows @p. Co-Authored-By: Claude Opus 5.5 --- docs/fs.md | 27 +++++++++++++++++++++++---- 1 file changed, 23 insertions(+), 4 deletions(-) (limited to 'docs') diff --git a/docs/fs.md b/docs/fs.md index 14b82d48..0a7cee7d 100644 --- a/docs/fs.md +++ b/docs/fs.md @@ -313,11 +313,16 @@ same tree without leaving the process. `/look` and `/exec` are the editor's two clicks, one per line of a write: - a line written to `look` is a right click on it: a path opens a file, - `file:12` jumps to a line, a directory opens a shell there, a URL opens in - the browser, and a plain word, as acme's look3 does, selects its next + `file:12` jumps to a line, a directory opens a terminal there that runs + `ls` once (pardes has no directory listing pane of acme's kind; a shell + in it is where one goes on from a directory), a URL opens in the + browser, and a plain word, as acme's look3 does, selects its next place in that pane after the dot, wrapping at the end, opening nothing (`LookWord list` on the root ctl lists every place in a `+Search` pane - instead, as pardes did before; `LookWord search` is the default). + instead, as pardes did before; `LookWord search` is the default). In a + terminal, which has no dot to go on from, a plain word is always listed + in a `+Search` pane, its rows naming the terminal as `@p:`, + and look reads that pane back. - a line written to `exec` is a middle click: a command word from `src/builtins.zig` (`Save`, `Del`, `New`, `Newcol`, `Mount NAME DIAL`, `Unmount NAME`, `Dump`, `Restore`, `Msg TEXT`, `Find`, `Grep`, `Tty`, ...; @@ -622,7 +627,21 @@ missed its target cannot then write at the last one. The three flag files `dirty`, `mark` and `scroll` read `0` or `1` and take `0` or `1`: whether the buffer differs from its file, whether a write pushes an undo point (writing `1` pushes one now), and whether a write scrolls the -pane. +pane. Every `data`, `xdata` or `body` write is an undo step of its own +while `mark` is 1; to make a loop's writes one step, write `1` (an undo +point here), then `0`, the writes, then `1` again. + +Which writes fail and which only say so: + +| file | a write fails (the errno, an `err` record) | said on the message row and logged as `msg`, the write succeeding | +|---|---|---| +| `ctl` (root, pane, column) | a malformed line, an unknown word, a builtin's failure, a refusal (Modified...) | what a builtin says when it works | +| `look`, `exec`, `tagexec`, a column's `exec` | a control character, a line over 1024 bytes, no pane slot or room | a look that finds nothing, a command's own failure, a builtin's failure | +| `addr`, `dot`, `limit` | an address that does not evaluate | -- | +| `data`, `xdata` | no address (the last one failed) | -- | +| `body`, `tag`, `name`, `sel`, the flag files | a bad value, a pane gone | -- | +| `event` | a malformed record, a range past the text | what the action it runs says | +| `pty/ctl`, `pty/data`, `pty/run` | a malformed verb, a size out of range, a pane that is no terminal | -- | `tag` reads the whole tag as the pane shows it: the computed path or PDF page (no mark for unsaved text: the grip shows that, and `dirty` says it), -- cgit v1.3