diff options
Diffstat (limited to 'docs/typ/reference.typ')
| -rw-r--r-- | docs/typ/reference.typ | 80 |
1 files changed, 51 insertions, 29 deletions
diff --git a/docs/typ/reference.typ b/docs/typ/reference.typ index b83b4a83..4de57d64 100644 --- a/docs/typ/reference.typ +++ b/docs/typ/reference.typ @@ -338,7 +338,13 @@ 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 -#word("Save") still uses. Mounts are dumped. +#word("Save") still uses. Mounts are dumped. A mount keeps its connection, +and sends each walk, open and first read or write together: an operation +through it costs one round trip (a directory, or a file of no stated +length, one more to see its end). A session on another machine mounts +through a forwarded socket: `ssh -C -N -L /tmp/box.sock:<its socket> host`, +then #word("Mount") `box /tmp/box.sock` (`-C`: a link far away carries +fewer bytes in each round trip). 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 @@ -368,27 +374,25 @@ Writes take settings and session builtins (`scope = .session` in #word("Delcol") and a pane's `get` refuse the same way with their own 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"), +- #word("Dump") writes `pardes-<date>-<time>.dump` (UTC) in #word("DumpDir"), 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). #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 #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 #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 #word("ThemeFile") the dump names that fails to load changes + pane, then `restore <path>`. Its panes and columns keep the serials they + had when dumped; one made after takes a serial past every one the old + session handed out. A dump keeps every pane's text and undo: a clean + file changed on disk since comes back as it is now, an unsaved one with + its own text, marked changed on disk, and its first #word("Save") asks + before overwriting. A #word("Restore") of a file that is no dump fails + before anything is replaced (`not a pardes dump: it is cut short`), with + EIO: read the `err` record for why. A #word("ThemeFile") the dump names that fails to load changes nothing. - #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 +- `size C R` sizes a session no terminal or window is attached to (160x50 + for a `--detach` one until then): from 20x6 to 4096x4096, else `invalid + size`; refused while a terminal or window 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"`). @@ -454,8 +458,7 @@ turning it off: #word("PanelSlide"), #word("PanelZoom"), #word("PanelDissolve"), #word("PanelAscii"), #word("PanelVertical"), #word("PanelEdges"), #word("PanelFall"), #word("PanelWave"), #word("PanelCurtain"), #word("PanelScramble"), #word("PanelType"); all -start off, and the web shell has none. Scene passes (the SDL window, and -one attached to a detached session), each at a level 0-3 (`on` is 2), all +start off, and the web shell has none. Scene passes (the SDL window), each at a level 0-3 (`on` is 2), all off: #word("Crt"), #word("Bloom"), #word("Vignette"), #word("Grain"). #word("Shader") `<file.glsl>` adds a Shadertoy file written for ghostty to the chain (#word("Shader") `off` removes it; it recompiles when saved); @@ -891,7 +894,6 @@ just before the #word("Restore") are not lost. [`changed <serial> [reloaded|deleted]`], [its file changed on disk (bare: under unsaved edits)], [`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 @@ -1010,12 +1012,28 @@ to its end before the write is answered, and one that finds nothing fails, another; a removed line's `-` goes to the line now standing where it was. git's `a/` `b/` (and `c/ i/ w/ o/`) prefixes are dropped; a `--no-prefix` diff's paths are kept. -- *Sessions.* Bare `--detach` names the session after its pid; bare - `--attach` needs exactly one session; a second `--detach=NAME` while NAME - runs (a plain session is named by its pid) says so in words and exits 1. Frontends share the smallest common size. With - none attached, `size C R` sets the screen, messages clear by the clock, - and a pty reports its size in pixels at the last frontend's cell size - (8×16 before any), as CSI 14, 16 and 18 t do. +- *Sessions.* `pardes --ps` prints what the daemon keeps: each session + (its pid, terminal or window, attached or detached, name) with the pids + and commands of the shells it holds, then the shells no session holds, + which #word("Adopt") takes. `--kill=NAME` ends that session and its + shells (a TERM, then a KILL 2 s later; unsaved changes are lost), + `--kill-all` every session and every kept shell; with no daemon running + each says so and exits 1. Bare `--detach` names the session after its pid; bare + `--attach` needs exactly one detached session of its kind (a terminal's + for `pardes`, a window's for `pardes-gui`), or with none detached the + only session of that kind; a second `--detach=NAME` + while NAME runs (a plain session is named by its pid) says so in words + and exits 1. A session attached already takes another view, up to four: + each terminal or window its own layout, focus, cursors, selections, + modes, scroll and jumps, over the panes, texts, tags, terminals, + messages and registers they share. A terminal pane shown in two takes the + size of the view that typed into it last; a shorter view shows the + rows down to its cursor, an arrow in the gutter when rows are above. #word("Detach"), or a terminal closing, lets that view go and + leaves the others. With none + attached, `size C R` sets the screen, messages clear by the clock, and a + pty reports its size in pixels at the last cell size (8×16 before any), + as CSI 14, 16 and 18 t do. Attaching from another machine is gone until + the replicated clients (docs/next-daemon.md, phase 5). - *Config.* The startup file is `$XDG_CONFIG_HOME/pardes/init` when that is absolute, else `~/.config/pardes/init` (macOS: `~/Library/Application Support/pardes/init`). A line that fails is a @@ -1023,11 +1041,15 @@ to its end before the write is answered, and one that finds nothing fails, setting only the other frontend has (#word("Font") in a terminal) is skipped; text that is no builtin is not run; saving the init file in a pane applies its settings again and says a bad line as startup does - (`err - init file line N: why`), its commands not run again. A dump keeps panes, columns, tags, - selections, the theme and changed settings, but not a picture or a PDF - that is on disk (#word("Restore") reads it from there); a terminal - comes back with its last MiB of output and a new shell in its old - directory; undo history and REPL bindings are not kept. A crash appends + (`err - init file line N: why`), its commands not run again. A dump keeps the whole + session: panes with their text, undo, selections and places, terminals + with their screens, history and kitty images, pictures, registers, + columns, tags, the theme and settings. A terminal comes back with a new + shell in its old directory under its history (not the REPL it ran), a + PDF read from its file. + A dump made by another build loads: a field added since takes its + default, and what cannot be read (a pane whose kind changed) is left out + and said in a notice. A crash appends two lines (build, time, platform, pid; the panic message) to `crashes` beside `init`. |
