From a99edf403dbcebae2ce557e2ba39078ffe876a92 Mon Sep 17 00:00:00 2001 From: Gabriel Schneider Date: Thu, 1 Oct 2026 12:48:17 -0300 Subject: Builtins are written by name: each chapter and the tutor define Look and Exec once and then say Look and Exec; the cheatsheet draws every mouse button as its icon; one-button clicks (Alt is B2, Super is B3) are in the guide and cheatsheet; building says how to send patches to the list Co-Authored-By: Claude Opus 5.5 --- docs/typ/reference.typ | 200 ++++++++++++++++++++++++------------------------- 1 file changed, 100 insertions(+), 100 deletions(-) (limited to 'docs/typ/reference.typ') diff --git a/docs/typ/reference.typ b/docs/typ/reference.typ index 0f9a9341..e79f9c4d 100644 --- a/docs/typ/reference.typ +++ b/docs/typ/reference.typ @@ -9,7 +9,10 @@ not .L), in acme's manner: panes, columns, tags and the session are files. Paths here are the served ones (#file("/pane/2/body")); through a mount they sit under the session's directory (`$m`; #doc("scripting", section: "find-the-session") says how to find it). The served #file("/README") is a -one-screen summary of this page. +one-screen summary of this page. Two builtins carry the core: #word("Look") (right-click): open what the +text names, or else find it; #word("Exec") (middle-click): run the builtin +it names, or else run it as a shell line. The files #file("look") and +#file("exec") take a line each, as those clicks would. = The tree @@ -57,7 +60,7 @@ is not UTF-8 `\xNN`, so a name decodes to the bytes it is. *Failure.* A write fails whenever what it asked for fails, and logs one `err : ` record, with no `msg`; a write that succeeds logs none. A refused write says why in the log's last `err` record, found -with `grep '^err' log | tail -1`: after a refused Del, Exit or Restore the +with `grep '^err' log | tail -1`: after a refused #word("Del"), #word("Exit") or #word("Restore") the newest line may be `new N .../+Unsaved`. Only writes log: a 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 @@ -68,7 +71,7 @@ itself (`bad value in control message; takes on, off "maybe"`); 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 `fs.enameErrno`): the first of these that the words hold, case aside, wins, and anything else is EIO (`Modified`, an -`Edit` command pardes leaves out): +#word("Edit") command pardes leaves out): #pairs( [`control message`], [EINVAL], @@ -94,8 +97,8 @@ words hold, case aside, wins, and anything else is EIO (`Modified`, an The `err` record has the words; a shell sees only the errno. -Not failures: a look that finds nothing (it answers nothing and logs one -`err`), an Edit `x` that matches nothing, #word("Undo") with nothing to +Not failures: a #word("Look") that finds nothing (it answers nothing and logs one +`err`), an #word("Edit") `x` that matches nothing, #word("Undo") with nothing to undo (a `msg`), and a command pane's command, which ends in its own time with an `exit` record. @@ -108,8 +111,8 @@ 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 +truncating open) is fine through a mount. An #word("Edit") whose `{` or `a`/`c`/`i` text is still +open waits for the next write on that open. A line or #word("Edit") block over 1 MiB is refused once (EINVAL), and the rest of it, through its newline, is dropped. @@ -163,18 +166,17 @@ read-only, 0222 write-only. = look and exec -A line written to #file("look") is a right-click on it, on the line as +A line written to #file("look") is #word("Look") on it, on the line as written: its leading blanks are its own (` return x` finds that -indented line, and a diff's blank context line ` ` is a look too); only its +indented line, and a diff's blank context line ` ` is a #word("Look") too); only its newline and `\r` go. An #file("exec") line's blanks at either end are -trimmed. The guide says what a look opens and where it looks for a relative -path (#doc("tags", section: "looking")); here is what is particular to the +trimmed. The guide says what #word("Look") opens and where it finds a relative path (#doc("tags", section: "looking")); here is what is particular to the files. - `file:12` selects line 12, newline included; `file:12:5` puts the caret at line 12, byte column 5; `file:` takes any address (below), *evaluated from the file's dot*: `file:/re/` finds the next match after - the selection, `file:0/re/` the first. A bare `:N` or `:N:M` (or any `:addr`) addresses the pane looked from. + the selection, `file:0/re/` the first. A bare `:N` or `:N:M` (or any `:addr`) addresses the pane the #word("Look") came from. `@p:` addresses a pane by serial, a terminal's logical lines too. - A leading `~` is the home directory (`$HOME`, else the passwd entry's; @@ -194,9 +196,9 @@ files. second number is a section, `file.pdf:PAGE:SECTION`, and only such rows are checked against the outline: a section not there, or not on that page, is a miss. -- A plain word selects its next place after dot, wrapping. `LookWord list` +- A plain word selects its next place after dot, wrapping. #word("LookWord") `list` on the root ctl lists a row per line holding it in a `+Search` pane - instead; the next word looked at in that directory refills it. In a + instead; the next word given to #word("Look") in that directory refills it. In a terminal a word is always listed, rows spelled `@p3:12:5-9`. A miss logs `err look: ...` (`no match for "zzq:#3"` quoting what @@ -205,22 +207,22 @@ for a line past a file's end, ` has no page 99` for a PDF's page; `: no match for regexp` or `: address out of range` when an address fails), opens nothing, and leaves #file("look") reading empty; the write succeeds. A `./x` or `../x` that is not there is such a miss too -(`look: ./x: no such file`). A look whose address fails says so and leaves open no file -it opened. A look of `file:12:` reads as `file:12`: a trailing colon is +(`look: ./x: no such file`). A #word("Look") whose address fails says so and leaves open no file +it opened. A #word("Look") of `file:12:` reads as `file:12`: a trailing colon is dropped, as a click leaves it off. A path too long to repeat whole gives up its middle to `…`. -A line written to #file("exec") is a middle-click: +A line written to #file("exec") is #word("Exec"): - A builtin word runs (#file("/commands") lists them). A builtin that needs its argument (#word("Msg"), #word("Mount"), #word("Find")) written bare is `wrong #args in control message "Msg"`, and so is one that takes none - written with one (`Config extra`). + written with one (#word("Config") `extra`). - A line starting with `#` is a comment, as in a shell: it runs as nothing, silently, here and in every ctl. - The language server's words ask about a file pane's text at its cursor (set it with #file("addr") and `dot=addr` first): #word("Hover") fills - `+Hover`; `Rename new` renames the symbol in the file and says how many + `+Hover`; #word("Rename") `new` renames the symbol in the file and says how many ranges it changed (on the message row, and so in the log) without listing them, and fails when there is nothing to rename. One that reaches other files applies nothing: it opens a `+Search` preview of the edits, which @@ -253,8 +255,7 @@ reused pane's #file("body") keeps every earlier run From a pane whose directory is gone nothing runs: `exec: : no such directory` (ENOENT). The root's #file("look") and #file("exec") act at the pane with the keyboard and log as -that pane's (with no pane at all, in the session's directory: a look opens -its file, making a column as #word("New") does, and an exec runs its +that pane's (with no pane at all, in the session's directory: a #word("Look") opens its file, making a column as #word("New") does, and an exec runs its command there); #file("/pane//look") and #file("exec") at pane n; #file("/tagexec") and #file("/col//exec") click in the workspace's or that column's tag, run commands in the session's directory, and log as @@ -263,7 +264,7 @@ at #file("/tagexec") and a column's exec: `not a session control message "Undo": A background job (`&`) outlives a command that exits on its own; its output goes on below `exit N` until it lets go of the pty. #word("Kill") -(root ctl) stops the commands pardes started: bare, all; `Kill make ls`, +(root ctl) stops the commands pardes started: bare, all; #word("Kill") `make ls`, those whose line starts with one of the words. For a command pane it signals the whole line, `&` jobs included; for a line typed into a shell only the foreground job (SIGTERM), and the shell decides the rest. With @@ -271,9 +272,9 @@ nothing running, named or not, it says `Kill: nothing running` and the write succeeds; words that name none of what runs fail it (`Kill: no running command has that first word`). #word("Kill") does not reach a REPL's code: use `sig INT` on its #file("pty/ctl"). -== Look paths and mounts +== Paths and mounts -A look resolves the OS filesystem first, then the editor's own tree. +#word("Look") resolves the OS filesystem first, then the editor's own tree. Explicit paths skip that search: #pairs( @@ -283,25 +284,25 @@ 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 ` mounts a dial: `unix!/path`, +`--mount=peer=work` or #word("Mount") `peer ` mounts a dial: `unix!/path`, `/path`, `tcp!!`, 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 +#word("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 EINVAL. There are eight named mounts; `os` and `self` are reserved. #word("Unmount") refuses a mount a pane, a working directory or a pending -Save still uses. Mounts are dumped. +#word("Save") still uses. Mounts are dumped. -A session may open its own tree through a mount (a look at `$m/pane/2/body` +A session may open its own tree through a mount (a #word("Look") of `$m/pane/2/body` from the editor serving `$m`): requests are answered on the connection's task while the editor waits in its syscall. Through QUIC that still hangs. = The root ctl Reading #file("/ctl") gives every setting, one a line, in the words a write -takes (`Theme orchard`, `Verbose on`, `Placement acme`, `DumpDir `, -`Shell /bin/bash`, ...), so writing back what it reads changes nothing. +takes (#word("Theme") `orchard`, #word("Verbose") `on`, #word("Placement") `acme`, #word("DumpDir") ``, +#word("Shell") `/bin/bash`, ...), so writing back what it reads changes nothing. Writes take settings and session builtins (`scope = .session` in `src/builtins.zig`), acting at the pane with the keyboard: @@ -322,30 +323,30 @@ Writes take settings and session builtins (`scope = .session` in word, except that #word("Delcol") opens no `+Unsaved` pane: it names the panes only in its `unsaved` records and its notice. - #word("Dump") writes `pardes--