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