From be7fb126aefedee221d0d32109acb9fc4b71d474 Mon Sep 17 00:00:00 2001 From: Gabriel Schneider Date: Wed, 30 Sep 2026 23:53:38 -0300 Subject: The docs take the 9P agent's round 30: log stats 0, names escape every control byte, $winid and the pager defaults, the one client rule, and Shift-Esc said one way in the guide and the cheatsheet Co-Authored-By: Claude Opus 5.5 --- docs/typ/reference.typ | 66 ++++++++++++++++++++++++++++++++++++++++---------- 1 file changed, 53 insertions(+), 13 deletions(-) (limited to 'docs/typ/reference.typ') diff --git a/docs/typ/reference.typ b/docs/typ/reference.typ index 37f3acbc..28f0c756 100644 --- a/docs/typ/reference.typ +++ b/docs/typ/reference.typ @@ -47,7 +47,8 @@ removes. Tcreate is refused everywhere. Names may hold blanks, so split `head, col = row.rsplit(maxsplit=1)`, then `serial, kind, dirty, name = head.split(maxsplit=3)`. Names in #file("/index"), the log and a terminal's tag are escaped: a newline `\n`, a -backslash `\\`, a byte that is not UTF-8 `\xNN`. +backslash `\\`, and any other control byte, DEL, a C1 control or a byte that +is not UTF-8 `\xNN`, so a name decodes to the bytes it is. = Rules for every file @@ -57,7 +58,8 @@ refused open or truncation (an OTRUNC open such as `> data` after a failed `addr`), create or remove answers its error alone, as do a write to #file("pane/new") (`permission denied`) and a write on a read-only fid (`bad use of fid`). Errors are words (Plan 9's where pardes has none of its -own), never a C library string. Through 9ns the kernel sees an errno 9ns +own), never a C library string; a ctl refusal quotes the offending word +alone (`wrong #args in control message "Newcol"`). Through 9ns the kernel sees an errno 9ns reads from those words (cloud9's `9ns/src/nine.zig`, `enameToErrno`): `control message`, `invalid` or `bad ` is EINVAL (malformed input); `no such`, `not found` ENOENT; `in use` EBUSY; `no space` ENOSPC; `denied` EACCES; anything else, such as `no match for regexp`, `address out of range`, `Modified` or an `Edit` command pardes leaves out (`w is a sam command pardes's Edit leaves out`), EIO; no refusal reads as EOPNOTSUPP. @@ -112,9 +114,8 @@ connection, and it keeps answering everything else beside its held reads. the range and flag files, the workspace's #file("tag"), the root #file("ctl"), #file("status"), #file("commands"), #file("README"), the #file("look")/#file("exec") answers, #file("focus"); #file("event") and -#file("pty/data") the next record's, zero when none waits; #file("log") -what an open would freeze. A view generated by each read stats 0, as -acme's do: #file("screen"), #file("data"), #file("xdata"), #file("index"), +#file("pty/data") the next record's, zero when none waits. A stream and a +view generated by each read stat 0, as acme's do: #file("log"), #file("screen"), #file("data"), #file("xdata"), #file("index"), #file("layout"), #file("recent"), #file("listeners"), #file("pane/new"). Read those to the end rather than trust a length (`cat` does). The qid version of #file("body"), #file("data") and #file("xdata") is the pane's @@ -143,8 +144,12 @@ files. `pardes '~/x'`), even beside a file named `~`: write `./~` for that. - A path to no file is a miss, as a search that finds nothing is: said on the message row and logged as an `err`, the write still answered. A file - that is there but will not open (no permission to read it, say) fails the - write, with why. + that is there but will not open fails the write and is named: + `look: : permission denied`. A zero column is refused, `file:0:0` + included: columns count from 1. +- A whole line of a diff pane written to #file("look") is the look a + #btn("B3") click on its first column makes. The line is matched in the + pane from its cursor row on, wrapping, and the first match wins. - A plain word selects its next place after dot, wrapping (`LookWord list` on the root ctl lists every place in a `+Search` pane instead). In a terminal a word is always listed, rows spelled `@p3:12:5-9`. @@ -251,7 +256,8 @@ Writes take settings and session builtins (`scope = .session` in - #word("Exit") quits. While panes hold unsaved text it refuses once (#doc("tags", section: "unsaved-panes")): one `unsaved ` record per pane, then the write fails `: Modified (Exit again to discard)` or `4 unsaved panes: Modified (Exit again to discard)` (EIO), - and the list stays in a `+Unsaved` pane. #word("Restore"), #word("Del"), + and the list stays in a `+Unsaved` pane (in the active pane's directory, + or the session's when that directory is not on disk). #word("Restore"), #word("Del"), #word("Delcol") and a pane's `get` refuse the same way with their own word. - #word("Dump") writes `pardes--