diff options
Diffstat (limited to 'docs/typ/reference.typ')
| -rw-r--r-- | docs/typ/reference.typ | 200 |
1 files changed, 100 insertions, 100 deletions
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 <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 <serial|-> <file>: <why>` 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 <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:<addr>` 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<serial>:<addr>` 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 <serial> look: ...` (`no match for "zzq:#3"` quoting what @@ -205,22 +207,22 @@ for a line past a file's end, `<path> has no page 99` for a PDF's page; `<path>: no match for regexp` or `<path>: 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: <dir>: 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/<n>/look") and #file("exec") at pane n; #file("/tagexec") and #file("/col/<n>/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 <mounts> +== Paths and mounts <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 <dial>` mounts a dial: `unix!/path`, +`--mount=peer=work` or #word("Mount") `peer <dial>` mounts a dial: `unix!/path`, `/path`, `tcp!<numeric-ip>!<port>`, 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 <root-ctl> Reading #file("/ctl") gives every setting, one a line, in the words a write -takes (`Theme orchard`, `Verbose on`, `Placement acme`, `DumpDir <dir>`, -`Shell /bin/bash`, ...), so writing back what it reads changes nothing. +takes (#word("Theme") `orchard`, #word("Verbose") `on`, #word("Placement") `acme`, #word("DumpDir") `<dir>`, +#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-<date>-<time>.zon` (UTC) in #word("DumpDir"), - logs `dump <path>`, and adds a `Restore <path>` word naming it to the + logs `dump <path>`, and adds a #word("Restore") `<path>` word naming it to the workspace tag (the last dump's, replacing an earlier one's). - `Restore [path]` replaces every pane (bare: the last dump this session - wrote). The Restore write is answered, then *every connection is hung + #word("Restore") `[path]` replaces every pane (bare: the last dump this session + wrote). The #word("Restore") write is answered, then *every connection is hung up*: dial again, and restart a 9ns mount. The new log has a `new` per pane, `restore <path>`, then `restored <old> <new>` per pane and `restoredcol <old> <new>` per column. A dump keeps an unsaved pane's text and the hash of the file it was read against; a clean file pane's - text is read from disk at Restore, so a file changed since comes back as + text is read from disk at #word("Restore"), so a file changed since comes back as it is now. An unsaved one whose file changed comes back with its own - text, marked changed on disk, and its first Save asks before - overwriting. A PDF's fit and tint are kept too. A Restore that fails says why in + text, marked changed on disk, and its first #word("Save") asks before + overwriting. A PDF's fit and tint are kept too. A #word("Restore") that fails says why in the parser's words, a ZON error with its line (`line 3: expected ','`), so the errno a mount gives depends on them (usually EIO): read the `err` - record for why. A ThemeFile the dump names that fails to load changes + record for why. A #word("ThemeFile") the dump names that fails to load changes nothing. -- `Kill [word...]` (above), `Mount name dial`, `Unmount name`, `Theme x`. +- #word("Kill") `[word...]` (above), #word("Mount") `name dial`, #word("Unmount") `name`, #word("Theme") `x`. - `size C R` sizes a `--detach` session no frontend is attached to (160x50 until then): from 20x6 to 4096x4096, else `invalid size`; refused while a frontend owns the size, and when a column would lose its panes' minimum rows (`size: too small for the panes, each its tag and 2 rows`). A bad `size` is refused quoting the value it got (`"5 2"`). -A word that takes its argument after a `+` (`Tty+bash`) works on a ctl as +A word that takes its argument after a `+` (#word("Tty+bash")) works on a ctl as in a tag. A write is refused whole, before anything runs, in Plan 9's words: `unknown control message "X"`, `wrong #args in control message "X"`, `bad value in control message ...`, or a word of the other ctl: `not a session control message "Undo": write it to pane/<n>/ctl`, `... "Delcol": write it to col/<serial>/ctl`, `not a window control message "X": write it to /ctl`. A builtin that would open a prompt (#word("Save") on a scratch) @@ -362,25 +363,25 @@ word clicked in a tag does. The same lines go in the startup file (#doc("config")). #pairs( - [`Theme <name>`], [`orchard`; names as #word("Themes") lists them, #word("NextColor") steps to the next in that list (#doc("themes"))], - [`ThemeFile <path>`], [a `.zon` theme, relative to the config directory; reloads live when saved], - [`FocusTint`], [on: tint the focused pane's and column's tags], - [`SyntaxBold`], [off: bold syntax keywords], - [`Verbose`], [on: a builtin announces its name on the message row], - [`MessageAnimation`], [on: messages ease in and dissolve], - [`MessageLinger`, `MessageFall`, `MessageDissolve`], [800, 180, 150 milliseconds, at most 60000], - [`PagerColor`], [on: the next paged text keeps its colours], - [`Pager pardes|off`], [`pardes`: what a terminal's commands page through, `pardes -`; `off` leaves `PAGER`, `GIT_PAGER` and `SYSTEMD_PAGER` as the environment has them (#doc("fs", section: "pardes-stdin")). It applies to terminals started after it], - [`Placement acme|pardes`], [`acme`: where new panes go (#doc("fs", section: "placement"))], - [`BootShell keep|replace`], [`keep`; `replace` closes the untouched lone shell a dragged document lands beside], - [`LookWord search|list`], [`search`: a looked-at word selects its next place, or lists all in `+Search`], - [`TermImages real|petscii`], [`real`: a new terminal draws its program's kitty graphics (yazi's previews) as pixels where the shell can; #word("Petscii") flips one terminal; a tty under a terminal without kitty graphics draws them as glyph art either way], - [`Shell <name or path>`], [`$SHELL` when it is executable, else `/bin/sh`: the shell the next terminal and command pane run; a bare name is looked for in the usual bin directories, not `$PATH`; bare #word("Shell"): `$SHELL` if it is executable, else `/bin/sh`], - [`DumpDir <dir>`], [`$XDG_DATA_HOME/pardes`, else `~/.local/share/pardes`: where #word("Dump") writes, an absolute or `~` path to a directory that may be written (made if missing); a relative one, or one under a directory that may not be written, is refused; bare returns to the default], - [`TreeContext`], [off: sticky declaration headers in a source pane (per pane, dumped)], - [`TreeContextTagStyle`], [on: draw those headers in the tagline style], - [`LocationsConfig ...`], [the layout of #word("Grep"), search and language-server results (below)], - [`Wrap`, `Colors`, `Tagbottom`, `Debug`], [toggles], + [#word("Theme") `<name>`], [`orchard`; names as #word("Themes") lists them, #word("NextColor") steps to the next in that list (#doc("themes"))], + [#word("ThemeFile") `<path>`], [a `.zon` theme, relative to the config directory; reloads live when saved], + [#word("FocusTint")], [on: tint the focused pane's and column's tags], + [#word("SyntaxBold")], [off: bold syntax keywords], + [#word("Verbose")], [on: a builtin announces its name on the message row], + [#word("MessageAnimation")], [on: messages ease in and dissolve], + [#word("MessageLinger"), #word("MessageFall"), #word("MessageDissolve")], [800, 180, 150 milliseconds, at most 60000], + [#word("PagerColor")], [on: the next paged text keeps its colours], + [#word("Pager") `pardes|off`], [`pardes`: what a terminal's commands page through, `pardes -`; `off` leaves `PAGER`, `GIT_PAGER` and `SYSTEMD_PAGER` as the environment has them (#doc("fs", section: "pardes-stdin")). It applies to terminals started after it], + [#word("Placement") `acme|pardes`], [`acme`: where new panes go (#doc("fs", section: "placement"))], + [#word("BootShell") `keep|replace`], [`keep`; `replace` closes the untouched lone shell a dragged document lands beside], + [#word("LookWord") `search|list`], [`search`: a word given to #word("Look") selects its next place, or lists all in `+Search`], + [#word("TermImages") `real|petscii`], [`real`: a new terminal draws its program's kitty graphics (yazi's previews) as pixels where the shell can; #word("Petscii") flips one terminal; a tty under a terminal without kitty graphics draws them as glyph art either way], + [#word("Shell") `<name or path>`], [`$SHELL` when it is executable, else `/bin/sh`: the shell the next terminal and command pane run; a bare name is searched for in the usual bin directories, not `$PATH`; bare #word("Shell"): `$SHELL` if it is executable, else `/bin/sh`], + [#word("DumpDir") `<dir>`], [`$XDG_DATA_HOME/pardes`, else `~/.local/share/pardes`: where #word("Dump") writes, an absolute or `~` path to a directory that may be written (made if missing); a relative one, or one under a directory that may not be written, is refused; bare returns to the default], + [#word("TreeContext")], [off: sticky declaration headers in a source pane (per pane, dumped)], + [#word("TreeContextTagStyle")], [on: draw those headers in the tagline style], + [#word("LocationsConfig") `...`], [the layout of #word("Grep"), search and language-server results (below)], + [#word("Wrap"), #word("Colors"), #word("Tagbottom"), #word("Debug")], [toggles], [`Font <name>[:<size>]`, `Fonts`], [SDL and macOS only; size 8-72 (pixels in SDL, points on macOS)], [`TaglineSize <1-100>`], [82: tagline face, percent; SDL and macOS], [`WindowOpacity <0-100>`], [100; SDL only: everything but text and the cursor], @@ -388,7 +389,7 @@ word clicked in a tag does. The same lines go in the startup file [`Pet cat|frog|off`], [off; SDL only: a sprite in the workspace tag's blank space], ) -`LocationsConfig` with no argument prints the current settings as a line +#word("LocationsConfig") with no argument prints the current settings as a line that can be run again; with fields it changes only those: `LocationsConfig context:5 tscontext:on tslocations:off layout:stacked`. `context` (0) is the source lines shown above and below each match; @@ -396,7 +397,7 @@ that can be run again; with fields it changes only those: `tslocations` (on) shows a location on each declaration header; `layout` (`stacked`) puts the location on its own line, `inline` beside the source, padded in groups of eight matches. An invalid field rejects the whole line; -a repeated field's last value wins. The settings survive Dump and Restore. +a repeated field's last value wins. The settings survive #word("Dump") and #word("Restore"). Source analysis is cached for 64 files and 64 MiB. *Effects.* Panel transitions, one at a time, running the active one again @@ -411,7 +412,7 @@ off: `Crt`, `Bloom`, `Vignette`, `Grain`. chain (`Shader off` removes it; it recompiles when saved); `ShaderAnimation off|on|always` says when the chain animates by itself. The focused pane can stand off the page: `Lift shadow|rim|auto|off`, -`InactiveDim <percent>`, `Motion off|crisp|smooth|bouncy|playful` (default +#word("InactiveDim") `<percent>`, #word("Motion") `off|crisp|smooth|bouncy|playful` (default `smooth`), `SelectionGlow`, `HoverGlow`, `Occlusion`, `Parallax`, #word("JumpTrail"), #word("ChipShadow"), #word("ThumbFlash"), `CursorBlink`, `GripWidth <50-300>`. Most are @@ -422,7 +423,7 @@ may lower the contrast of text, the selection or a focus indicator. build embeds them. Resting the pointer on text for about 32 ms (`look_preview_delay_frames`, -2 frames, in `src/config.zig`; `null` turns it off) tints what a right-click would look at, with no other effect. A terminal's +2 frames, in `src/config.zig`; `null` turns it off) tints what #word("Look") would take, with no other effect. A terminal's #word("Filter") keeps each foreground at least `tty_filter_min_contrast` (WCAG 1.5, `src/config.zig`) against its background. @@ -477,7 +478,7 @@ of one open answer the same serial. It goes where a #word("New") from a tag would (#doc("fs", section: "placement")): in the active column, filling it if empty, else the bottom half of its last pane. A session holds 64 panes (`no space for a pane: 64 max`), and every pane keeps its -tag and 2 rows (`no space for a pane in that column: each keeps its tag and 2 rows`); both are ENOSPC, for this open and for a look, exec, +tag and 2 rows (`no space for a pane in that column: each keeps its tag and 2 rows`); both are ENOSPC, for this open and for #word("Look"), #word("Exec"), #word("New") or #word("Tty") alike. A #file("pane/new") whose column is full takes its rows from a pane in another column that has them, last column first, as acme does, and is refused only when no pane anywhere can @@ -504,8 +505,7 @@ child as typed keys, never a paste: no bracketed-paste marks around it, even when the program asked for them, so a newline in it is Enter. A PDF's body is the text layer of the page shown, each line of the page's text a line of the body, read-only: it is no text of the -pane's, so #file("addr"), #file("data"), #file("dot") and a `file:<addr>` -look do not address it (a PDF's `:<n>` is its page); images and PDFs take +pane's, so #file("addr"), #file("data"), #file("dot") and a `file:<addr>` #word("Look") do not address it (a PDF's `:<n>` is its page); images and PDFs take no write (`this pane has no text`). *Image panes.* An image pane's tag reads `img petscii:on|off @@ -514,7 +514,7 @@ instead of pixels (#word("Petscii") toggles it); `palette` is which 16 colours the glyph art uses, the C64's (`commodore`) or the terminal theme's own 16 (#word("Palette") toggles it); `ascii` is whether the printable ASCII bitmaps join the glyph set the matcher picks from -(#word("Ascii") toggles it). Palette and ascii only change the glyph art. +(#word("Ascii") toggles it). #word("Palette") and ascii only change the glyph art. #word("Petscii") and #word("Ascii") (`on|off`) and #word("Palette") (`commodore|terminal`) take the value their tag word shows and set it, as a PDF's #word("PdfFit") (`width|height`) and #word("PdfTint") @@ -544,17 +544,17 @@ takes: - the pane builtins: #word("Del") (from the keyboard between two panes it asks which takes the rows; a click, a ctl write or an `init` line never - asks and gives them to the pane above; `Del k`/`Del j`, or + asks and gives them to the pane above; #word("Del") `k`/#word("Del") `j`, or #word("DelAbove")/#word("DelBelow"), give its rows to the pane above or - below), `Save [path]` (bare, on a `+`-named pane that is no output, + below), #word("Save") `[path]` (bare, on a `+`-named pane that is no output, such as `+Tutor`, it asks for a path; making the directories the file goes in first, whichever name it writes), #word("Collapse"), #word("Undo")/#word("Redo") - (256 steps each), `Find pat`, `Edit ...`, `Tty [shell]` (a new terminal + (256 steps each), #word("Find") `pat`, #word("Edit") `...`, #word("Tty") `[shell]` (a new terminal in its directory), #word("Delcol") for its column, and #word("Left")/#word("Right")/#word("Up")/#word("Down"), which give the keyboard to the pane beside it that way (#key("Ctrl-w") with #keys("h", "l", "k", "j")), up from a column's top pane to its tag. -- `get`: reload from the file (refused once over unsaved edits, `<name>: Modified (get again to discard)`). It is an undo step, so Undo brings back what was there: the sure way back to the file on disk. +- `get`: reload from the file (refused once over unsaved edits, `<name>: Modified (get again to discard)`). It is an undo step, so #word("Undo") brings back what was there: the sure way back to the file on disk. - `lock`/`unlock` (acme's). The lock binds only clients that take it and belongs to the open that wrote it: `exec 3>$pane/ctl; echo lock >&3; ...; exec 3>&-`. A `lock` another open holds fails at once, `file in use` (EBUSY): retry. @@ -619,7 +619,7 @@ and #file("limit") on a terminal, an image or a PDF), `bad address syntax`, `no sam details kept: `$-1` is the last line when the text ends in a newline, else the one before; with a final newline the empty place after it is a -line (`1` of an empty text is `#0,#0`, so `Edit 1i/x/` works on an empty +line (`1` of an empty text is `#0,#0`, so #word("Edit") `1i/x/` works on an empty file); `2,1` is an empty range at line 2's start; `/^/` finds the empty place after a final newline; a pattern that can match empty (`^`) passes over the match where the search starts. @@ -629,12 +629,12 @@ over the match where the search starts. Patterns are mvzr's (classes, `\d\w\s`, `{m,n}`, lazy `*?`), searched as sam searches, line by line: `^` and `$` match at any line's start and end, `.` and `[^...]` never match a newline. The same code (`src/regexp.zig`) -serves addresses, Edit, and normal mode's #key("s") and #key("S"). The +serves addresses, #word("Edit"), and normal mode's #key("s") and #key("S"). The ceiling: - The leftmost match wins, but among alternatives the first that matches, not sam's longest (`/gam|gamma/` finds `gam`). mvzr keeps no submatches, - so Edit's `s` has no `\1`-`\9`. + so #word("Edit")'s `s` has no `\1`-`\9`. - A pattern holding `\n` runs over the whole text: there `^` may only come first and `$` only just before a `\n`, else it is refused. - An alternation must anchor every branch with `^` or none (`^def|^ ` @@ -643,14 +643,14 @@ ceiling: wider range or a negated class with one (`[^é]`) is refused. - At most 512 operations (about 512 characters, counted after that rewriting): `bad regular expression: longer than mvzr's 512 operations (about 512 pattern characters)`. -- Each search has a step budget (about 300 ms; each search of an Edit `x` +- Each search has a step budget (about 300 ms; each search of an #word("Edit") `x` its own): `regular expression search took too much time, gave up`. What runs out is exponential backtracking (`a?` twenty times then twenty `a`s) or a quadratic pattern over a very long line. == Edit <edit> -`Edit <sam commands>` on a pane's #file("ctl") or #file("exec") (or the +#word("Edit") `<sam commands>` on a pane's #file("ctl") or #file("exec") (or the root's, at the pane with the keyboard) runs acme's Edit on the body: addresses as above, commands `x y g v c a i d s p = m t u` and `{ }`. All changes are one undo step, applied only if every command succeeds; a failure changes @@ -680,7 +680,7 @@ one step: `echo 1 > mark` (a point now), `echo 0 > mark`, the writes, == event <event> -Holding #file("event") open takes the pane's look and execute clicks: they +Holding #file("event") open takes the pane's #word("Look") and #word("Exec") clicks: they come to the reader as records instead of acting, as do lines written to the pane's own #file("look")/#file("exec") (or the root's while it has the keyboard). A record is acme's `<origin><action><q0> <q1> <flag> <n> <text>\n`; read `n` *bytes* of text, which may hold newlines. Reads may be shorter @@ -692,10 +692,10 @@ closed. A reader whose pane has closed reads EOF. - origin: `E` a 9P write to body or tag, `F` other files and the editor's own lines, `K` keyboard, `M` mouse. -- action: `X`/`L` executed/looked in the body, `x`/`l` in the tag (offsets +- action: `X`/`L` #word("Exec")/#word("Look") in the body, `x`/`l` in the tag (offsets into the whole tag, path included), `I`/`D` body text inserted/deleted, `i`/`d` the tag's. -- flag: 1 the text's first word is a builtin, 4 (look) a file name or +- flag: 1 the text's first word is a builtin, 4 (#word("Look")) a file name or address, 8 (exec) chorded: two records follow, the argument and where it came from. pardes never sends flag 2. - A written line, or a click in a terminal's body, has no place: `0 0` @@ -715,15 +715,15 @@ back as a record: run it through #file("ctl") instead. == REPLs <repls> -`Repl python` on a terminal's #file("ctl") (or in its tag) binds it as +#word("Repl") `python` on a terminal's #file("ctl") (or in its tag) binds it as that language's REPL: a middle-click or #key("Tab") on a `.py` body then types the text into the REPL instead of running it; builtin words, -tag words, `Exec <text>` and #raw("@`cmd`") words still run. #word("Repl") +tag words, #word("Exec") `<text>` and #raw("@`cmd`") words still run. #word("Repl") takes the languages a code fence names (ada, bash, c, c_sharp, clojure, cpp, css, elixir, erlang, fortran, go, haskell, html, java, javascript, json, kotlin, ocaml, markdown, pascal, php, powershell, python, ruby, rust, scala, typst, zig) and aliases such as `py` and `sh`. Its tag and -#file("ctl") line show its id, `python-a`. `Repl -` unbinds, bare +#file("ctl") line show its id, `python-a`. #word("Repl") `-` unbinds, bare #word("Repl") says the binding. With several bound, the pane asks (`ask <serial> repl a b`). Bindings are not dumped. A 9P #file("exec") is never sent to a REPL. A script either writes the @@ -776,13 +776,13 @@ A program holding the terminal (a REPL, `less`) takes no run: write to One 64 KiB ring, one record a line, kept whether or not anyone reads it. An open freezes it and reads to EOF. Write `follow` to that open to then wait for each new record (`follow new` skips the history, as `tail -n0 -f`); `tail -f` never writes `follow`, so it sees nothing new. A follower -the 64 KiB ring outran (it keeps only the newest records) reads `lost N` first. A Restore hangs the follower up: dial +the 64 KiB ring outran (it keeps only the newest records) reads `lost N` first. A #word("Restore") hangs the follower up: dial again and read from `restore <path>`. A follower's read held when the -Restore comes takes every queued record that fits first, so records written -just before the Restore are not lost. +#word("Restore") comes takes every queued record that fits first, so records written +just before the #word("Restore") are not lost. #pairs( - [`new <serial> <name>`, `del`, `rename`, `save`], [a pane made, closed, renamed (a terminal's too, as its shell changes directory), saved (`Save path` of a copy: `save <serial> <path>`, the path written)], + [`new <serial> <name>`, `del`, `rename`, `save`], [a pane made, closed, renamed (a terminal's too, as its shell changes directory), saved (#word("Save") `path` of a copy: `save <serial> <path>`, the path written)], [`newcol <serial>`, `delcol <serial>`], [a column made or closed], [`msg <serial|-> <text>`], [the editor said something (not a builtin's own name under #word("Verbose"))], [`err <serial|-> <file>: <why>`], [a write was refused or failed], @@ -790,9 +790,9 @@ just before the Restore are not lost. [`send <from> <to> <repl-id>`], [text went to a REPL], [`ask <serial> <what> <choices>`, `answer <serial> <choice|->`], [a pane asked, and was answered (`-`: taken back, or the pane closed)], [`changed <serial> [reloaded|deleted]`], [its file changed on disk (bare: under unsaved edits)], - [`unsaved <serial> <name>`], [a pane an Exit, Restore, Del or Delcol refused over, before the `err`], - [`dump <path>`, `restore <path>`], [a Dump written; a Restore, after its panes' `new`s], - [`restored <old> <new>`, `restoredcol <old> <new>`], [serial maps after a Restore], + [`unsaved <serial> <name>`], [a pane an #word("Exit"), #word("Restore"), #word("Del") or #word("Delcol") refused over, before the `err`], + [`dump <path>`, `restore <path>`], [a #word("Dump") written; a #word("Restore"), after its panes' `new`s], + [`restored <old> <new>`, `restoredcol <old> <new>`], [serial maps after a #word("Restore")], ) The serial is the pane the line ran at (the pane with the keyboard for the root's @@ -808,12 +808,12 @@ at 200, ending in `…`. Control characters become spaces. `cells` of `[grapheme, style_index]`; one frame per open. Compare a cell's style through `styles`, not the index. - #file("/commands"): `Word [arg] root|pane|both [values] -- sentence`, one - a line, generated from the builtin registry (`both`: Edit, at the active + a line, generated from the builtin registry (`both`: #word("Edit"), at the active pane from the root). - #file("/recent"): up to 200 files, PDFs and images, most recent first, `open <path>` or `closed <path>`; kept in `$XDG_STATE_HOME/pardes/recent`. #word("Recent") shows them in a pane, an open one at its dot now and a - closed one at its last (a PDF's is its page); a look at a row reopens it + closed one at its last (a PDF's is its page); a #word("Look") of a row reopens it there. - #file("/status"): `pid`, `version`, `panes`. - #file("/pager"): write a directory, `~` expanded and resolved (an empty @@ -851,33 +851,33 @@ starts a separate session whose shells do not forward to it. = Placement <placement> -`Placement acme` (the default) puts a new pane in the column whose tag +#word("Placement") `acme` (the default) puts a new pane in the column whose tag asked, else the active column (last typed or left-clicked in, dropped into, its tag given the keyboard, or given the last new pane), never a new column. An empty column it takes whole; #word("New") and #file("pane/new") take the bottom half of the column's last pane; a pane -opened from a pane's text (a look, #word("Tty"), #key("Alt-n")) goes under +opened from a pane's text (#word("Look"), #word("Tty"), #key("Alt-n")) goes under the pane with the most blank rows, or halves the biggest. #word("New") in a pane's tag names its `+New` in that pane's directory and column; from a column tag, in that column and the session's directory. A command pane goes to the last column, or the column whose tag ran it, under either -placement. `Placement pardes` fills an empty column whose tag asked or has +placement. #word("Placement") `pardes` fills an empty column whose tag asked or has the keyboard, puts a scratch or a shell under the pane that asked, and a document beside the last one read (or in a column of its own on a wide screen). No pane is made shorter than its tag and two rows; with no room the pane is refused. A command pane runs in the directory it started in, whatever its command -does with `cd`, and relative looks in it resolve there. The next command +does with `cd`, and a relative #word("Look") in it resolves there. The next command for that directory reuses a finished one (from a column tag, only one in that column); one still running, one a background job still prints to, or one a #file("exec") open still holds is never reused. = Find and Grep <find-grep> -Find matches file names, Grep the text of lines, both literally and -ignoring ASCII case. Grep reads at most 256 KiB of a file and stops at 512 -hits, Find at 512 names. The walk stops at 20000 files or 100000 entries, +#word("Find") matches file names, #word("Grep") the text of lines, both literally and +ignoring ASCII case. #word("Grep") reads at most 256 KiB of a file and stops at 512 +hits, #word("Find") at 512 names. The walk stops at 20000 files or 100000 entries, 16 deep, and passes over `.git`, `.jj`, `target`, `node_modules`, `.venv`, `__pycache__`, `.zig-cache` and `zig-out`. A cap hit, or a directory it could not open, is said at the end: `cut at 512 hits`, `N @@ -928,7 +928,7 @@ it was. `+Pager` pane, made or emptied for it and left clean, opening at its top; the next paged text refills it. The session parses the text with ghostty-vt: SGR colours become the `+Pager`'s own display, never part of -its body or any read (`PagerColor off` pages plain), and every other +its body or any read (#word("PagerColor") `off` pages plain), and every other escape is dropped; a carriage return keeps a progress line's last state, and CRLF becomes LF. Empty stdin shows nothing. Inside a pardes pane it returns at once; a text the session cannot take is printed to stderr with why, and the exit is 1. From a directory @@ -937,7 +937,7 @@ directory's. Outside a pardes pane it starts a new editor whose first pane the text is. Stdin up to a file's limit (256 MiB) arrives whole; past that it is cut, with a note saying so. -With `Pager pardes`, a terminal's shell gets `PAGER`, `GIT_PAGER` and +With #word("Pager") `pardes`, a terminal's shell gets `PAGER`, `GIT_PAGER` and `SYSTEMD_PAGER` set to this pardes plus ` -` (the path quoted only when it needs it), and `SYSTEMD_PAGERSECURE=0` (it has no shell escape), each only where your environment does not set it. `man` pages through `MANPAGER` @@ -998,7 +998,7 @@ with Client(sys.argv[1]) as c: # a socket path, or (ip, port) [open records], [64 a session, every client's together], [held reads a connection], [128], [named mounts], [8], - [command line], [1024 bytes; a held line or Edit block 1 MiB], + [command line], [1024 bytes; a held line or #word("Edit") block 1 MiB], [tag text], [4096 bytes], [regular expression], [512 operations; a step budget per search (about 300 ms)], [undo], [256 steps], |