diff options
Diffstat (limited to 'docs/typ/guide.typ')
| -rw-r--r-- | docs/typ/guide.typ | 383 |
1 files changed, 383 insertions, 0 deletions
diff --git a/docs/typ/guide.typ b/docs/typ/guide.typ new file mode 100644 index 00000000..58e5d907 --- /dev/null +++ b/docs/typ/guide.typ @@ -0,0 +1,383 @@ +// The guide: pardes day to day, the path a newcomer reads once. Edge cases +// live in the reference, the pager and the language servers in setup, the +// keys on the cheatsheet. +#import "style.typ": key, keys, btn, chord, word, tag, addr, file, cmd, doc, pairs, glossary, annotated, clip, mode-box + +#word("Look") (right-click) opens `src/bar.c:12`; #word("Exec") (middle-click) runs `make`. + +#annotated("/docs/site/media/themes/orchard.png", (640, 513), + alt: "a pardes window: workspace tag, column tag, a file pane, a terminal and a diff", + ([the workspace tag: words for the whole session], -22, 11), + ([a column's tag], 400, 34), + ([a pane's tag: its path, then its words], 560, 58), + ([the box: the pane's mode, and the handle to drag it], 8, 58), + ([the body: here a file, below it a terminal], 200, 104), + ([the scrollbar: how much of the body is in view], 8, 160), +) + +#glossary("Words you'll see", <words>, + [the pane with the keyboard], [where your keys go; one pane at a time], + [the session's directory], [where pardes started, or the directory `pardes DIR` named; workspace and column tags run there], + [active column], [where the next new pane goes (below)], + [command pane], [a terminal that runs one command line and shows its output], + [`+` names], [panes pardes makes, named in their directory: `+New` a scratch (text with no file yet), `+Search` a query pane or a listing of places, `+Pager` paged text, `+Errors` output, `+Unsaved` the panes holding unsaved text], + [serial], [a pane's number, never reused: the `3` in `@p3:12` and in 9P paths], + [message row], [the line where pardes says what happened, and asks: answer a prompt (#key("s")'s regex, #word("Save")'s path) with #key("Enter"), cancel it with #key("Esc")], +) + += Modes <modes> + +Each pane keeps its own mode. The box left of its tag shows it. + +#pairs( + [#mode-box(" ") normal], [keys move and select; an edit acts on the selection. File and PDF panes start here, and so does a terminal from #key("Alt-n").], + [#mode-box("^") insert], [keys type. #keys("i", "a", "o") and the rest enter it.], + [#mode-box("$") raw, terminals only], [keys go to the program. A terminal from #word("Tty"), the shell a bare `pardes` starts with, and a command pane start here.], +) + +#key("Ctrl-b") switches a terminal between raw and normal. In normal, +its text is a page to move over and copy from. #word("Mode") in the tag +steps raw, normal, insert. + +#pairs( + [#mode-box(" ") normal], [#key("Esc"): back to the previous pane (#word("Last")), unlike helix. #key("Shift-Esc"): the same.], + [#mode-box("^") insert], [#key("Esc"): back to normal. #key("Shift-Esc"): out of insert and back to the previous pane.], + [#mode-box("$") raw], [#key("Esc"): back to the previous pane. #key("Shift-Esc"): an Esc to the program. Either way the terminal stays raw. #word("ProgramEsc") `on` swaps them back: #key("Esc") goes to the program, except at a shell prompt with nothing typed on it, and #key("Shift-Esc") always goes back.], + [a PDF], [#key("Esc"): clears the selection and the search highlights. #key("Shift-Esc"): back to the previous pane.], +) + +In acme, Esc selects the text typed since the last click; here it leaves +insert mode, or goes back a pane. + +#key("Shift-Esc") needs the kitty keyboard protocol or the GUI. Elsewhere +it is a plain Esc. The previous pane is the last one you jumped from, else +the next pane down the column. + +#pairs( + [#key("Ctrl-w") or #key("SPC w")], [window mode (#word("Window")): each pane's tag box shows a letter instead of its mode, and the focused pane's tag is outlined; #keys("h", "j", "k", "l") move the outline, #key("Enter") or #key("Esc") gives that pane the keyboard, #key(":") its tag, a pane's letter gives it that one. #key("k") past a column's top pane goes on to its tag. #key("d") is #word("Del") on the outlined pane (between two panes it waits for #key("k") or #key("j"), as #key("SPC d") does) and the outline moves to the pane that took its rows; #key("c") is #word("Collapse"). The mode stays on for the next key], + [#keys("Ctrl-o", "Ctrl-i")], [back and forward through the places you jumped to (the jump list), this file's first: another file's only once it has none left that way (#word("JumpScope") `all`: every place in order). #key("Ctrl-i") needs the kitty keyboard protocol or the GUI, being #key("Tab") elsewhere: there use #key("SPC j i") and #key("SPC j o"), or the mouse's side buttons], +) + +Raw mode sends almost every key to the program. Leave it (#key("Ctrl-b")) +before #key("Ctrl-w") or #key("Alt-n"). + += The mouse <mouse> + +#pairs( + btn("B1"), [select; a click puts the cursor there and gives the pane the keyboard. In a tag it starts typing, in insert mode. A double click selects the word; at a line's start or end, the line; just inside a bracket or quote, up to its match.], + btn("B2"), [#word("Exec"): a builtin word runs, anything else is a shell line.], + btn("B3"), [#word("Look"): open the file, address, directory or URL, else find the word's next place.], + chord("B1", "B2"), [cut the selection], + chord("B1", "B3"), [paste over it], + chord("B1", "B2", "B3"), [copy], + [Alt-click (Option)], [#btn("B2"), sweeps too, for one button or a trackpad; in a terminal too], + [Super-click (Cmd)], [#btn("B3"); not in a terminal, which never passes Super], + [Ctrl-click], [the language server's definition], +) +#clip("chords") + +A program that takes the mouse gets the plain click. + +#btn("B3") on `src/bar.c:12:5:` in a compiler's error opens `src/bar.c` at +line 12, column 5. A click takes the word under it: letters, digits and +`. - + / : @ _ ~`, less a trailing `:`. Drag to take exactly what you +swept. In normal mode #key("Enter") is #word("Look") and #key("Tab") is +#word("Exec"). + +A builtin's argument: sweep `Find conf` with #btn("B2"), or select `conf`, +then #chord("B2", "B1") on `Find`. + +#key("x") #key("y") then #key("p") copies a line below. Every pane shares +the registers. #key("SPC y") and #key("SPC p") use the system clipboard. + += Tags <tags> + +#tag("Newcol Joincol Find Grep Help Changelog Tutor Dump Themes Config Debug Exit") +#tag("New Tty Find Grep Joincol Delcol") +#tag("Save Tty Collapse Del", path: "/home/me/notes.txt") + +A tag is text with undo. Type `make` into one and #word("Exec") it, or +delete the words you never use. Any word runs from any tag: #word("Exit") +in a pane's tag quits too. + +#pairs( + [#key(":")], [the keyboard to the tag, on #word("Save") the first time; #key("Tab") runs it, #key(":") comes back], + [edit the path, #key("Enter")], [renames: the next #word("Save") writes there; the typed path survives #key("Esc"), pending, and a second #key("Esc") drops it], + [#word("Collapse")], [folds the pane to its tag], + [drag the box], [up or down resizes; onto another column moves the pane], +) + += Where commands run and panes go <command-panes> + +#btn("B2") on `make` runs it with the #word("Shell") setting's `-c`. +Where it runs depends on where you clicked: + +#clip("where-commands-run") + +#pairs( + [a terminal's text or tag, at a prompt with nothing typed], [typed into that shell, in its current directory], + [any other pane's text or tag], [a command pane in that pane's directory, in the last column], + [a column's tag], [a command pane in the session's directory, in that column], + [the workspace tag], [a command pane in the session's directory, in the last column], +) + +A file's text and tag run in its directory: `make` from `README` at the +project root is right, from `src/main.c` it is not. The keyboard stays +where it was. The command pane's tag ends in `running`, then `exit N`: + +#tag("Kill Save Collapse Del", path: "/home/me/src (make) exit 0") + +Click into the command pane: #key("n") selects the next `file:line`, +#key("Enter") opens it, and #key("n") from there goes on to the next error. +A finished command pane is in normal mode, so #key("x") #key("y") copy from +it at once. The next command for that directory reuses it. +#word("Kill") `make` stops the commands pardes started with `make`. +#word("Save") or #word("Del") in a column tag acts on that column's pane +with the keyboard, else its first. + +Every other new pane goes into the *active column*: where you last typed +or left-clicked, or where the last new pane went. The new pane takes the +keyboard. A listing is the exception: it opens below the pane that asked, +which keeps the keyboard, so #keys("n", "N") walk the listing. #btn("B3") +on a file open in another column jumps there, but the next new pane still +lands in the old column. #word("Placement") `pardes` picks other rules +(#doc("reference", section: "placement")). + +To open beside: #word("Newcol"), then #word("Look") a file name typed in +its tag opens it there; #key("Alt-c") moves a pane into a new column. +#clip("columns", wide: true) + +Closing a column's last pane leaves it empty; #word("Delcol") and +#word("Joincol") take columns away. Closing the session's last pane quits +pardes. + += Look <looking> + +#pairs( + addr("notes.txt"), [opens it, or goes to the pane already showing it], + addr("notes.txt:12"), [line 12], + addr("notes.txt:/TODO/"), [the next match of `TODO`], + addr("src/"), [a pane listing it, as acme's directory window: a #word("Look") at an entry opens it, `..` goes up, `Get` reads it again (#word("DirLook") `terminal`: `ls` in a terminal there)], + addr("https://ziglang.org"), [the browser, through `xdg-open` (`open` on macOS); there is no plumber], +) + +#key("Enter") does the same from the keyboard; the other address forms are +on the cheatsheet. A relative path is found in the directory of the pane +the #word("Look") came from, then of each pane on the jump list, most +recent first. + += Search <search> + +#key("/") opens a query pane under the pane: a `+Search` whose first line +is the query, typed into, and whose rows are what it finds, made again at +each key. It takes its rows from the pane it searches and from no other, +is born #word("SearchRows") rows tall and never resizes itself; nothing +found is a count of `0` in its tag, not an exit. + +#pairs( + [#key("/") `vw`], [every match in the text tinted and ticked on its scroll rail, the first after the cursor selected; the rows under line 1 are the lines holding it, each its place as text first (`file:line:col`, the shortest path a #word("Look") from the pane resolves), then the line coloured as the file is, under the declaration it is in], + [#keys("Ctrl-n", "Ctrl-p")], [the next or previous match, typing; the text follows it], + [#key("Enter")], [the keyboard on the match, the pattern in `/`, the rows kept as text (#word("Save") keeps them as a file)], + [#keys("n", "N")], [the next or previous match in the text, round the end without a word], + [#key("Esc")], [typing: the text as it was, the query pane closed], + [#key("*")], [the selection as line 1, the keyboard staying in the text], +) + +Line 1's first word names what it searches, and editing the word changes it: + +#pairs( + [`/pat`], [the pane's own text: a regex, any case unless it has a capital (#key("/"))], + [`Find name`], [the files below the pane's directory, by a fuzzy match of their names (#key("SPC f f"), #word("Find"))], + [`Grep text`], [the lines of those files holding `text`, literally (#key("SPC f g"), #word("Grep")); past 2000 lines #word("More") goes on], + [`Recent name`], [the files opened lately, in any window (#key("SPC f r"), #word("Recent"))], + [`Panes name`], [the open panes, then the ones closed this session, `(closed)` and dimmer: #key("Enter") (or a #word("Look") at its `@pN`) brings one back where it was, its text with it (#key("SPC b b"), #word("Panes"))], + [`Symbols name`], [the text's declarations (#key("SPC s s"))], + [`All pat`], [every open pane's text, its rows under each pane (#key("SPC /"))], + [`Refs`, `Def`, `Impl`, `Diagnostics`], [the language server's lists (#key("g r"), #key("g d"), #key("g i"), #key("SPC l d")): one answer is a jump, none a message; several open the list with the keyboard on its current row in normal mode (#keys("j", "k", "n", "N") step it, #key("Enter") lands, #key("Esc") goes back), the diagnostics' keeping it in the text for `]d`; their places in the text tinted as a `/`'s are], +) + +A row in a file no pane shows is shown in a `+Preview` under the query +pane. The current row follows the keyboard only (#keys("Ctrl-n", "Ctrl-p") +typing, #keys("n", "N") and #keys("j", "k") in the pane's normal mode); +#btn("B1") on the rows places the caret and selects, as in any pane, and +moves nothing else. #key("Enter") lands the current row, making the +preview that file's pane where it stands. +The preview colours the file as its own pane does, and the query's hits +in it are its places, tinted and ticked, the current one selected. +#btn("B3") on a row's place goes there, as on any address; the rows kept +as text (#word("Save")) are a list of places that still work. +#btn("B2") on line 1 runs it again. The next search from the same pane reuses its query pane, +its kept rows back on #key("Esc") (#word("SearchPane") `new`: a pane each; +#word("SearchPlace") `column`: in a finder column at the right). A PDF's +and a terminal's #key("/") still ask on the message row and list a +`+Search`. +#clip("search") + += Unsaved panes <unsaved-panes> + +#word("Del") on a pane with unsaved text, its box filled +(#mode-box(" ", unsaved: true); a `*` in a terminal), refuses once, saying `1 unsaved pane — Del again to discard`, and lists the pane +in `+Unsaved`; #word("Del") again discards it. +#word("Exit") (or #key("SPC q")), #word("Restore") and #word("Delcol") +refuse once the same way. #key("SPC d") between two panes also asks which +takes the rows: #key("k") above, #key("j") below. Typed straight on, +#key("SPC d") then #key("j") just closes the pane; the question shows on its notice band +only if no answer has come after a moment, a hint for a Del that seemed to +do nothing. + += Terminals <terminals> + +#tag("Tty+bash Save Mode Filter Collapse Del", path: "/home/me/src") + +- #word("Tty") opens a terminal in the pane's directory, #key("Alt-n") one in + the session's directory; #word("Tty+bash") picks the shell. +- #word("Del") closes a terminal and its shell at once, running or not, and + a shell that exits closes its pane. +- #word("Save") writes the scrollback to a path it asks for. +- #word("Filter") maps the program's colours through the theme. +- #word("Petscii") draws a program's images as glyph art instead of pixels. +- In raw mode Ctrl-V types what you yanked, Ctrl-Shift-V the clipboard. +- In normal mode, editing a terminal's text edits a copy, and the first + edit says so: #key("Tab") or #btn("B2") runs it, and the program's next + drawing replaces it. +- A program that tracks the mouse gets #btn("B1") and the wheel; + #btn("B2") and #btn("B3") stay pardes's. Hold Shift to swap. +- #word("Repl") `python` in its tag makes #btn("B2") on a `.py` pane send the text + to that REPL. +- `git log` and `man` open in a `+Pager` pane (#doc("setup", section: "pager")). + += Reviewing diffs <reviewing-diffs> + +`git diff` run as a command, or a `.diff` or `.patch` shown as text (below), +is drawn as a diff, each hunk in its file's language. #btn("B3") on: + +#pairs( + [`diff --git`, `---`, `+++`], [the file], + [`@@ -3,7 +3,8 @@`], [the hunk's first new line], + [a line's `+`, `-` or space], [that line in the new file], +) + +A `.diff` or `.patch` looked at, and a diff paged (`git show`), opens as +a `+Diff`, stacked as delta shows one: each hunk under its `path:line` +(`Space j n`/`Space j p` step through them, #btn("B3") opens it) and the declarations +around it, a `+`/`-` before each line, the words a changed line changed +tinted and a line added or removed whole faintly. A mailed patch keeps its +message and diffstat above. The files are found from the diff's directory +or one above it. #word("Diff") on a `+Diff` shows the diff itself as +text (a paged one's `+Pager` is closed once stacked), and on the text stacks +it again; #word("DiffLook") `text` in the startup file opens the text +first. + += Call hierarchy <callstack> + +Put the cursor on a function and run #word("Callstack") (#key("g c") or #key("SPC l b")). +`+Callstack` starts at the outermost callers and follows calls down toward +the selected function, with shared callers grouped and vertical guides +joining the levels with rounded corners. Each caller has a clickable location and its function +signature, extracted by the same tree-sitter context mechanism as other +location results. Signatures and call-site snippets use source syntax colors; +only calls to the selected function receive background emphasis. Guides +continue alongside every line of a multiline signature and through screen +wrapping. Cross-directory Look paths are shortened when possible. +#btn("B3") or #key("Enter") on a location opens and reveals that source +pane. #word("LookNext") / #word("LookPrev") (#keys("SPC j n", "SPC j p")) +select locations without opening them. The view follows the language +server's static call hierarchy; recursive paths are marked `↻`, and a +hierarchy deeper than the limit invites continuing from another function. +Every caller is listed: the walk runs as long as the server keeps answering, +says how many callers it has found on the message row once it takes more +than a second, and shows what it found if the server stops answering. +Asking anything else stops it. A tree too big for one page (about 100,000 +rows, the memory one query may use) ends in a row saying so: running +#word("Callstack") in `+Callstack` shows the next page, from where this +one stopped, with that caller's own callers above it again. +At each level, callers whose function or file name contains "test" come +after the rest. +#word("CallstackDepth") reports the current caller depth; +`CallstackDepth 16` changes it for subsequent queries. The default is 8 +levels, and the accepted range is 1–64. + +`CallstackLayout stacked` (the default) puts each signature and call snippet below its +location, aligned with the location text; `CallstackLayout inline` puts it +beside the location again. A bare #word("CallstackLayout") switches modes. +`CallstackCorners rounded` (the default) uses rounded tree guides; +`CallstackCorners square` restores sharp corners. Bare #word("CallstackCorners") +switches styles. Layout and corner changes apply to the next query. These settings are retained +by #word("Dump") / #word("Restore"). + += `pardes FILE` and `--wait` <editor> + +In a pane's shell: + +``` +pardes notes.txt open it here and return at once (acme's B) +pardes --wait notes.txt return when that pane closes (acme's E) +``` + +A file not there yet opens empty, and #word("Save") creates it. +`--wait` makes pardes an `EDITOR` (#doc("setup", section: "editor-setup")); +refusals and `--nested` are in the reference. + += Keys <keys> + +#pairs( + [#key("w") #key("d")], [select a word, delete it: motions select, edits act on the selection], + [#key("x"), #key("v"), #key(";")], [select the line; extend; collapse to the cursor], + [#key("s")], [a cursor per regex match; every edit acts at each], + [#key("/"), #keys("n", "N")], [search the text in a query pane (#link(<search>)[Search]); step its matches, round the ends], + [#keys("SPC j n", "SPC j p")], [#word("LookNext") / #word("LookPrev"): select locations across panes; #key("Enter") opens one], + [#key("g l")], [line end], + [`12G`], [line 12; a bare #key("G") does nothing], + [#key("SPC ?")], [#word("Help"): every builtin, with its leader path and keys; `SPC w ?` only the paths under `SPC w`; #word("Tutor") (#key("SPC h t")) practises them], + [#keys("g d", "g r"), `SPC l`], [the language keys, once a server is installed (#doc("setup", section: "language-servers"))], +) + +The keys are helix's, and helix's +#link("https://docs.helix-editor.com/keymap.html")[keymap] is their full +reference. Where pardes differs (#key("Esc") leaving the pane, the +#key("SPC") paths, #key("Ctrl-w"), #key("Ctrl-b")), this guide and the +cheatsheet (#doc("cheatsheet")) say so. + += Sessions <sessions> + +``` +pardes --detach=work & a session with no screen of its own +pardes --attach=work show it here +``` + +The session owns the panes, shells and files; frontends come and go, and +all of them see the same screen. #word("Attach") `work` (#key("SPC s a")) +switches this window to it; #word("Detach") (#key("SPC s D")) leaves it +running. + += Config <config> + +#word("Config") (#key("SPC f c")) opens the startup file, +`~/.config/pardes/init`: one builtin a line, run at start, `#` a comment. + +``` +Theme atelier +Shell zsh +# Placement acme is the default; Placement pardes picks the other rules +``` + +#word("DumpConfig") opens every live setting as the line that sets it. +#word("Dump") saves the workspace and #word("Restore") brings it back +(what a dump keeps is in the reference). Keys are compile-time, in +`src/config.zig`. + += Questions <questions> + +/ Why not helix and tmux, or acme?: helix and tmux edit and run shells + well, but their text is inert. acme makes text the interface and is + modeless by design, with win for shells and page and the plumber for + documents. pardes keeps acme's text as the interface and trades the rest + for helix's modal keys, a VT terminal and PDFs in a pane. What changes + for acme users and scripts is in #doc("reference", section: "from-acme"). +/ Does it run inside tmux?: Yes, as in any terminal. Where tmux does not + pass kitty's protocols, #key("Shift-Esc") is a plain Esc and images draw + as glyph art. +/ Does my helix config carry over?: No. The keys are compiled in + (`src/config.zig`); `~/.config/helix` is not read. +/ How do I quit?: #key("SPC q"), or #word("Exit") in any tag. +/ What does "pardes" mean?: The name of the four levels of reading a text in rabbinical exegesis (#link("https://en.wikipedia.org/wiki/Pardes_(exegesis)")[Wikipedia]). |
