summaryrefslogtreecommitdiff
path: root/docs/typ/reference.typ
diff options
context:
space:
mode:
authorGabriel Schneider <[email protected]>2026-11-05 00:08:16 -0300
committerGabriel Schneider <[email protected]>2026-11-05 00:32:56 -0300
commit2367ed34beccf3f2f1b8bbf6b8a171f50933d7a1 (patch)
tree8dcc7111d1e78806c6ac0e0bd1493c25d86bfc85 /docs/typ/reference.typ
parent43a4c24e607a456d7a23eb8a779bce5651f18222 (diff)
downloadpardes-2367ed34beccf3f2f1b8bbf6b8a171f50933d7a1.tar.gz
pardes-2367ed34beccf3f2f1b8bbf6b8a171f50933d7a1.zip
config, exec, look: Placement, BootShell, LookWord, DirLook and DiffLook go, with what each kept of pardes before it took acme's ways (exec's pardesPlace, atFoot, belowParent, pardesDoc and evictLonePristineTty with mouse.zig's call, layout's splitParent and columnFitsHalves that only they called, look's ls in a terminal for a directory, the word and patch looks' other branches, the SPC c p key, their Help and builtins-JSON rows, their lines in docs/typ and a changelog line), and the tests of them: Dir.zig's "DirLook terminal: a look at a directory opens a terminal there, no pane listing it", pardes.zig's "first document fallback splits like Term from the originating pane", "first document keeps its originating shell and only opens a column when it fits", "BootShell keep leaves the untouched boot shell a dragged document joins; replace closes it" and "a Look on a directory does not type ls into an occupied terminal", keys.zig's "keys: SPC j n and SPC j p walk on from the place a Look's +Search listing chose, its keyboard left in the file", look_and_exec.zig's "look-and-exec: a second LookWord list look in a directory refills its +Search rather than stacking another", placement.zig's "placement: Placement pardes puts a new pane right under the asking one, and bare it steps back to acme", output.zig's "LookNext/LookPrev keeps the result output a Look chose through a no-match answer, and a stale serial once it is deleted", and the snapshot scripts that turned them on (cmdword, doccol, look-dir, lookpanes, rsearch, splitparent, ttylook); the Del question's test makes its middle panes the acme way, a New at the column's foot, and the others that turned one on for their layout run without it
Co-Authored-By: Claude Opus 5.5 <[email protected]> Claude-Session: https://claude.ai/code/session_016Y9MNAtZenFv4weoMD3cge
Diffstat (limited to 'docs/typ/reference.typ')
-rw-r--r--docs/typ/reference.typ34
1 files changed, 12 insertions, 22 deletions
diff --git a/docs/typ/reference.typ b/docs/typ/reference.typ
index 5e277f20..663bc0af 100644
--- a/docs/typ/reference.typ
+++ b/docs/typ/reference.typ
@@ -229,10 +229,10 @@ 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. #word("LookWord") `list`
- on the root ctl lists a row per line holding it in a `+Search` pane
- 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 plain word selects its next place after dot, wrapping. In a terminal a
+ word is listed instead, a row per line holding it in a `+Search` pane,
+ rows spelled `@p3:12:5-9`; the next word given to #word("Look") in that
+ directory refills it.
A miss logs `err <serial> look: ...` (`no match for "zzq:#3"` quoting what
was written when nothing by that name exists; `<path>:99 has no line 99`
@@ -357,15 +357,15 @@ 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 (#word("Theme") `orchard`, #word("Verbose") `on`, #word("Placement") `acme`, #word("DumpDir") `<dir>`,
+takes (#word("Theme") `orchard`, #word("Verbose") `on`, #word("DumpDir") `<dir>`,
#word("Shell") `/bin/bash`, ...), as #word("DumpConfig") does, and one the
frontend lacks as a comment (`# Lift unsupported`), 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:
-- A setting written bare steps to its next value (a switch flips; so do
- #word("Placement"), #word("BootShell"), #word("Crt")). A value it does not
+- A setting written bare steps to its next value (a switch flips; so does
+ #word("Crt")). A value it does not
take is `bad value in control message; ...` naming what it takes;
#file("/commands") lists them. A setting the frontend cannot show is
refused (`Lift is GUI-only, invalid here`).
@@ -411,8 +411,7 @@ runs fails with the editor's words (`Mount: already mounted`, `Save /root/x: acc
== Settings <settings>
-A setting that chooses among words (`on`/`off` switches,
-#word("Placement"), #word("BootShell"), #word("Crt"), #word("Bloom"),
+A setting that chooses among words (`on`/`off` switches, #word("Crt"), #word("Bloom"),
#word("Vignette"), #word("Grain"), #word("Lift"), #word("Motion"),
#word("ShaderAnimation")) steps to its next value when given bare, as its
word clicked in a tag does. The same lines go in the startup file
@@ -429,10 +428,6 @@ word clicked in a tag does. The same lines go in the startup file
[#word("PagerColor")], [on: the next paged text keeps its colours],
[#word("ProgramEsc")], [off: in a raw terminal #key("Esc") goes back a pane and #key("Shift-Esc") is the program's Esc; on swaps them, and #key("Esc") goes back only at an empty shell prompt],
[#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("DirLook") `pane|terminal`], [`pane`: #word("Look") on a directory opens a pane listing it, as acme's directory window (#doc("reference", section: "from-acme")); `terminal` types `ls` into a terminal idle there, else opens one],
[#word("JumpScope") `file|all`], [`file`: #word("Back") and #word("Forward") keep to the focused pane's file, that pane's places first, then the file's in another pane, and go to another file only when the file has no place left that way; from a terminal or a pane with no file they step through every place; `all`: every place, in the order it was jumped to],
[#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 tui 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`],
@@ -986,8 +981,7 @@ starts a separate session whose shells do not forward to it.
= Placement <placement>
-#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,
+A new pane goes 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
@@ -995,12 +989,8 @@ opened from a pane's text (#word("Look"), #word("Term"), #key("Alt-n")) goes und
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. #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.
+goes to the last column, or the column whose tag ran it. 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 a relative #word("Look") in it resolves there. The next command
@@ -1166,7 +1156,7 @@ with Client(sys.argv[1]) as c: # a socket path, or (ip, port)
[acme's other builtins], [refused: `Sort`, `Local`, `Abort` (plan9port's debugging word)],
[Edit], [every acme command but `B <cmd`, `D <cmd` and the `'` address; no `\1`-`\9`, and an alternation takes the first branch that matches, not the longest; a failing `< | >` command changes nothing, where acme puts in what it wrote (#doc("fs", section: "edit"))],
[`win`], [#word("Term") is a VT terminal pane; #file("pty/run") runs a line at its prompt and answers `exit N` and the output; with #word("Repl") bound, #word("Exec") on a source pane types the text into it],
- [a directory window], [as acme's: a text pane named `dir/` (#file("index") kind `text`, #file("ctl") isdir 1), its entries in columns sorted bytewise, dotfiles shown, a directory's marked `/`; blanks pad the columns where acme's tabs do; a #word("Look") at an entry is from that directory, `Get` or a look at it again reads it again, and an edit is kept until then rather than lost to a resize; never dirty, #word("Save") refuses it; #word("DirLook") `terminal` types `ls` into a terminal there instead],
+ [a directory window], [as acme's: a text pane named `dir/` (#file("index") kind `text`, #file("ctl") isdir 1), its entries in columns sorted bytewise, dotfiles shown, a directory's marked `/`; blanks pad the columns where acme's tabs do; a #word("Look") at an entry is from that directory, `Get` or a look at it again reads it again, and an edit is kept until then rather than lost to a resize; never dirty, #word("Save") refuses it],
[the plumber], [none: #word("Look") on an `http://` or `https://` URL runs `xdg-open` (`open` on macOS); files, addresses and directories follow built-in rules],
[#key("Esc") selects what was typed], [#key("Esc") leaves insert mode, or goes back a pane (#doc("tags", section: "modes"))],
)