summaryrefslogtreecommitdiff
path: root/docs/typ/reference.typ
diff options
context:
space:
mode:
Diffstat (limited to 'docs/typ/reference.typ')
-rw-r--r--docs/typ/reference.typ80
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`.