summaryrefslogtreecommitdiff
path: root/docs/typ/reference.typ
diff options
context:
space:
mode:
authorGabriel Schneider <[email protected]>2026-10-22 09:50:43 -0300
committerGabriel Schneider <[email protected]>2026-10-22 10:03:24 -0300
commita8b457a306a4442975210bcac3f04b56513c61c3 (patch)
tree6e2026ecb15da2fb919a0202f5d8b38e3b36a595 /docs/typ/reference.typ
parenta8a1499bdffffc5b6919e24ec957e92fabaf003b (diff)
parent7e9d2c4169245072265b483ffaa6aa05f23f08d3 (diff)
downloadpardes-a8b457a306a4442975210bcac3f04b56513c61c3.tar.gz
pardes-a8b457a306a4442975210bcac3f04b56513c61c3.zip
Merge: Def/Refs, the diff viewer, Helix n/N, Callstack, Zig 0.17, Window mode and the terminal cwd fix onto 0.24
The docs keep both sides: 0.24's Ctrl-i fallbacks and typed ls with this line's Window mode, raw Esc and Helix n/N wording. The CHANGELOG's unreleased entries go above 0.24, Def/Refs and the context rows among them. cheatsheet-a4.pdf rendered again; .scratch/ ignored. Co-Authored-By: Claude Opus 5.5 <[email protected]>
Diffstat (limited to 'docs/typ/reference.typ')
-rw-r--r--docs/typ/reference.typ46
1 files changed, 31 insertions, 15 deletions
diff --git a/docs/typ/reference.typ b/docs/typ/reference.typ
index 148ef30e..bb13b011 100644
--- a/docs/typ/reference.typ
+++ b/docs/typ/reference.typ
@@ -22,7 +22,7 @@ index a line per pane: serial kind dirty name column @ru
status pid, version, panes @other-files
look write a line: a #word("Look") at the pane with the keyboard; read: the serials touched @look-and-exec
exec write a line: an #word("Exec") there; read: the serials touched @look-and-exec
-pager write a directory: its one +Pager, made or emptied; read: its serial @pardes-stdin
+pager write a directory: a new +Pager there; read: its serial @pardes-stdin
log the event log; write follow to wait for more @log
screen the rendered screen as JSON @on-screen
listeners dial addresses @other-files
@@ -252,7 +252,9 @@ A line written to #file("exec") is #word("Exec"):
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`; #word("Rename") `new` renames the symbol in the file and says how many
+ `+Hover`; #word("Def") and #word("Refs"), in the tag of a file a server
+ speaks for, are `gd` and `gr`, and given a symbol (a 2-1 chord's
+ selection) ask at its occurrence nearest the cursor; #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
@@ -260,6 +262,16 @@ A line written to #file("exec") is #word("Exec"):
the server answers in this file alone while another open file of its
language still holds the old name, a row per such file (zls renaming at
a declaration; from a use it reaches every file);
+ #word("Callstack") (#key("g c") or #key("SPC l b")) opens and focuses `+Callstack`,
+ with static caller ancestry, tree-sitter signatures and Look locations
+ for callers and call sites. #word("CallstackDepth") reports or sets the
+ runtime depth (1–64, default 8) for subsequent queries.
+ `CallstackLayout stacked` (the default) aligns snippets below their locations;
+ `CallstackLayout inline` places the snippets beside them.
+ `CallstackCorners rounded` (the default) or `CallstackCorners square`
+ selects the tree corner style for the next query; bare, it switches styles.
+ #word("Callers") and #word("Callees") keep their short
+ lists and single-result jumps.
#word("Diagnostics") and #word("Symbols") list the file's in `+Search`;
#word("Lspinfo") fills `+Lsp`, the pane its write answers, with which
server serves the file and its state (`not started yet` until its first
@@ -403,6 +415,7 @@ word clicked in a tag does. The same lines go in the startup file
[#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("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],
@@ -457,7 +470,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 #word("Look") would take, 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 or a `+Pager`'s
#word("Filter") keeps each foreground at least `tty_filter_min_contrast`
(WCAG 1.5, `src/config.zig`) against its background.
@@ -587,8 +600,10 @@ takes:
(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.
+ keyboard to the pane beside it that way, up from a column's top pane to
+ its tag; #word("Window") (#key("Ctrl-w"), #key("SPC w")) picks the pane
+ first: #keys("h", "j", "k", "l") move an outline, #key("Enter") or
+ #key("Esc") or a pane's letter focuses.
- `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`
@@ -900,10 +915,10 @@ at 200, ending in `…`. Control characters become spaces.
line is the session's; one not there is refused ENOENT, a relative one
EINVAL, one you may not write `permission denied`, a regular file `not
a directory`, ENOTDIR), one line; what follows that line, on the same open, is the text to
- page, escapes and all. A read of that open answers the serial of the
- directory's one `+Pager`, made or emptied for it, once the text is in. This is what
- `pardes -` uses; from a directory you may not write, it pages into the
- session's `+Pager`.
+ page, escapes and all. A read of that open answers the serial of a new
+ `+Pager` in the directory, once the text is in. This is what
+ `pardes -` uses; from a directory you may not write, it pages into a
+ `+Pager` of the session's.
- #file("/listeners"): the session's dial addresses, a line each
(#doc("building", section: "listeners")).
- #file("/os/"): existing regular files take read, write and truncation to
@@ -968,7 +983,7 @@ it was.
= On screen <on-screen>
-- *Esc at a prompt.* pardes knows a shell prompt with nothing typed on it
+- *Esc at a prompt* (with #word("ProgramEsc") on). pardes knows a shell prompt with nothing typed on it
from the OSC 133 marks it injects into bash and fish (marks a shell sends
itself do not count); for other shells, from no program holding the
terminal, typed text or not.
@@ -1005,12 +1020,13 @@ it was.
= pardes - <pardes-stdin>
-`pardes -` reads stdin to its end and shows it in the directory's one
-`+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
+`pardes -` reads stdin to its end and shows it in a new `+Pager` pane of
+the directory, left clean, opening at its top, with no line numbers; a
+`+Pager` already there keeps its page. The session parses the text with
ghostty-vt: SGR colours become the `+Pager`'s own display, never part of
-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,
+its body or any read (#word("PagerColor") `off` pages plain), mapped
+through the theme as a terminal's are until its #word("Filter") shows them
+as sent; 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
whose name holds a newline or control byte, the pane is the session