diff options
Diffstat (limited to 'docs/typ/guide.typ')
| -rw-r--r-- | docs/typ/guide.typ | 293 |
1 files changed, 175 insertions, 118 deletions
diff --git a/docs/typ/guide.typ b/docs/typ/guide.typ index d07ab6cd..578e7ea8 100644 --- a/docs/typ/guide.typ +++ b/docs/typ/guide.typ @@ -1,19 +1,21 @@ // 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 +#import "style.typ": key, keys, btn, chord, word, tag, addr, file, cmd, doc, pairs, glossary, annotated, clip, mode-box -pardes reads the text on its screen as things to do, with two builtins. -#word("Look") (right-click): open the `file:line`, address or URL the text -names, or else find the text. #word("Exec") (middle-click): run the builtin -the text names, or else run it as a shell line. Everything else is where -that happens: columns of panes, each a tag (a line of words) over a body -that is a file you edit, a terminal, a PDF or an image, with a tag for each -column and the workspace above. The keys are helix's, in modes, and every -session is also a virtual filesystem, served over 9P, for scripts. +#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>, - [tag], [the line of words over a pane, a column or the screen; every word in it can be clicked], [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)], @@ -21,40 +23,43 @@ session is also a virtual filesystem, served over 9P, for scripts. [`+` names], [panes pardes makes, named in their directory: `+New` a scratch (text with no file yet), `+Search` 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 (a search, #word("Save")'s path) with #key("Enter"), cancel it with #key("Esc")], - [the box], [left of a pane's tag: drag it to move or resize the pane; it shows the mode, and marks unsaved text (`*`, or filled in the window)], ) = Modes <modes> -Each pane has its own mode and keeps it while you are elsewhere. The box -at the left of a pane's tag shows it. +Each pane keeps its own mode. The box left of its tag shows it. #pairs( - [normal (blank)], [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").], - [insert (`^`)], [keys type. #keys("i", "a", "o") and the rest enter it.], - [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.], + [#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 mode -its prompts are hidden and its text is a page to move over and copy from. -#word("Mode") in the tag steps raw, normal, insert. +#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( - [normal], [#key("Esc"): back to the previous pane (#word("Last")). #key("Shift-Esc"): the same.], - [insert], [#key("Esc"): back to normal. #key("Shift-Esc"): out of insert and back to the previous pane.], - [raw `$`], [#key("Esc"): to the program, except at a shell prompt with nothing typed on it, where it goes back to the previous pane. #key("Shift-Esc"): always back. Either way the terminal stays `$`.], + [#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"): to the program, except at a shell prompt with nothing typed on it, where it goes back to the previous pane. #key("Shift-Esc"): always back. Either way the terminal stays raw.], [a PDF], [#key("Esc"): clears the selection and the search highlights. #key("Shift-Esc"): back to the previous pane.], ) -Unlike helix, #key("Esc") in normal mode leaves the pane: it is how you go -back. #key("Shift-Esc") needs the kitty keyboard protocol or the GUI; -elsewhere it is a plain Esc. "The previous pane" is the last other pane on -the jump list, else the next pane down its column. #key("Ctrl-w") then -#keys("h", "j", "k", "l") moves the keyboard to the pane left, below, -above or right; #keys("Ctrl-o", "Ctrl-i") walk back and forward through the -places you have jumped to, the jump list. In raw mode every key but #key("Ctrl-b"), Esc and the -paste chords goes to the program, so #key("Ctrl-w") and #key("Alt-n") need -you out of raw mode first. +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") #key("h")], [the keyboard to the pane on the left; #key("j") below, #key("k") above, #key("l") right], + [#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> @@ -62,21 +67,28 @@ you out of raw mode first. 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") -With one button, as on a trackpad, Alt-click (Option on a Mac) is #btn("B2") and Super-click (Cmd) is #btn("B3"), sweeps included; Ctrl-click stays the language server's definition, a program that takes the mouse gets the plain click, and in a terminal only Alt-click works, since Super never reaches pardes there. +A program that takes the mouse gets the plain click. -A middle- or right-click with no drag takes the word under it: the -run of letters, digits and `. - + / : @ _ ~`, a trailing `:` dropped. So #btn("B3") on `src/bar.c:12:5:` in a compiler's error opens `src/bar.c` at -line 12, column 5. Drag to say exactly what you mean. #key("Enter") and -#key("Tab") in normal mode are #word("Look") and #word("Exec"). +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`. -Hold the left button and click the middle one to cut the selection, the -right one to paste over it, both one after the other to copy. #key("y") yanks and -#key("p") pastes after (a line yanked with #key("x") #key("y") goes in as a -new line below), through registers every pane shares; #key("SPC y") and -#key("SPC p") use the system clipboard. +#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> @@ -84,19 +96,23 @@ new line below), through registers every pane shares; #key("SPC y") and #tag("New Tty Find Grep Joincol Delcol") #tag("Save Tty Collapse Del", path: "/home/me/notes.txt") -A tag is text with undo: type a word into it and click it, or delete the -defaults. #key(":") moves the keyboard to the tag, onto its #word("Save") -the first time, in normal mode (#key("Tab") runs it), and back. Any word -runs from any tag: #word("Exit") in a pane's tag quits too. The path -at the start of a pane's tag is computed: typing into it drafts a new name, -#key("Enter") confirms and the next #word("Save") writes there. -#word("Collapse") folds a pane to its tag. Drag the grip up or down to -resize, or onto another column to move the pane. +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 a line that is no builtin (`make`, `git log`) runs it with -the #word("Shell") setting's `-c`. Where depends on where you clicked: +#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], @@ -105,58 +121,66 @@ the #word("Shell") setting's `-c`. Where depends on where you clicked: [the workspace tag], [a command pane in the session's directory, in the last column], ) -The keyboard stays where it was. A file's tag runs in the file's directory, -so run project commands (`make`) from a column or the workspace tag, or a -shell. A command pane's tag says `running`, then `exit N`: +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") -The next command for that directory reuses a finished command pane. -#word("Kill") stops what pardes started (#word("Kill") `make`: those whose line -starts with `make`); #word("Exit") quits pardes. A pane word from a column -tag (#word("Save"), #word("Del")) acts on that column's pane with the -keyboard, or its first. +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*: the column you last -typed or left-clicked in, or the one that got the last new pane. It -takes the keyboard, except a listing, which opens below the pane that -asked and leaves it the keyboard, so #keys("n", "N") walk the listing. -#word("Look") moves the keyboard but not the active column: #btn("B3") on a file -already open in another column jumps there, and the next new pane still -lands in the old column until you type or click. #word("Placement") -`pardes` picks other rules (#doc("reference", section: "placement")). +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")). -A column can be empty: closing its last pane leaves it. #word("Delcol") -and #word("Joincol") take columns away. Closing the session's last pane -quits pardes. +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> -#btn("B3") (or #key("Enter")) on a path opens it, or goes to the pane that -already shows it; `file:12` goes to line 12, `file:/re/` to the next -match of `re`, and the other address forms are on the cheatsheet. -#key("/"), text and #key("Enter") list the lines holding it in a `+Search` -and go to the first; #keys("n", "N") step through the rest. A directory types `ls` into a terminal idle there, -else opens one there. A URL opens in the browser. 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. +#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. -#word("Find") `name` lists the files below the pane's directory whose -names hold it; #word("Grep") `text` lists the lines that hold the text, -literally (no regular expression), under every pane's directory. Both land -in a `+Search` listing; their limits are in the reference. +#pairs( + [#key("/") `TODO` #key("Enter")], [a `+Search` of the lines holding `TODO`; #key("n") moves the keyboard into it and walks its rows (#key("N") back), and #key("Enter") on a row takes the searched pane there], + [#word("Find") `conf`], [a `+Search` of the files below the pane's directory with `conf` in their names], + [#word("Grep") `TODO`], [a `+Search` of the lines holding `TODO`, literally, under every pane's directory], +) +#clip("search") = Unsaved panes <unsaved-panes> -A pane with unsaved text is marked on its grip. #word("Del") on it refuses -once: the message row says `1 unsaved pane — Del again to discard` and the -pane is listed in `+Unsaved`. The same #word("Del") again discards it. -#word("Exit"), #word("Restore") and #word("Delcol") refuse once the same -way. A pane with nothing unsaved closes at once. From the keyboard -(#key("SPC d")), #word("Del") between two panes also asks which takes its -rows: #key("k") above, #key("j") below. To quit, press #key("SPC q") or -middle-click #word("Exit") in the workspace tag; it refuses once -over unsaved panes too. +#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. = Terminals <terminals> @@ -170,40 +194,57 @@ over unsaved panes too. - #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. -- Paged output (`git log`, `man`) opens in a `+Pager` pane (#doc("setup", section: "pager")). +- `git log` and `man` open in a `+Pager` pane (#doc("setup", section: "pager")). = Reviewing diffs <reviewing-diffs> -Open a `.diff` or `.patch`, or run `git diff` as a command: the output is -drawn as a diff, each hunk coloured in its file's language. #btn("B3") on a -`diff --git`, `---` or `+++` line opens the file; on `@@` the hunk's first -new line; on a hunk line's `+`, `-` or space, that line in the new file. +`git diff` run as a command, or a `.diff` or `.patch` opened, 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], +) = `pardes FILE` and `--wait` <editor> -In a pane's shell, `pardes FILE` opens FILE in this session and returns at -once, as acme's `B` does; a FILE not there yet opens an empty pane that -#word("Save") creates. `pardes --wait FILE` returns when that pane is -closed, as acme's `E` does, which makes it an `EDITOR` -(#doc("setup", section: "editor-setup")). Refusals and `--nested` are in -the reference. +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> -Motions select what they cross, and an edit acts on the selection: #key("w") -then #key("d") deletes a word. #key("x") selects lines, #key("v") extends, -#key(";") collapses to the cursor. #key("s") makes a cursor per regex match -and every edit acts at each. #key("/") is a substring search; the regexes -are on #key("s") and #key("S"). #keys("n", "N") step through everything -#word("Look") would open, across panes. Line end is #key("g l"). #key("SPC") starts -the leader, #key("SPC ?") lists every path, #word("Help") every key and -builtin, and #word("Tutor") (#key("SPC h t")) practises them. The language -keys (#keys("g d", "g r"), `SPC l`) work once a server is installed -(#doc("setup", section: "language-servers")). +#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")], [substring search; step through everything #word("Look") would open, across panes], + [#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> @@ -212,10 +253,10 @@ 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. -#word("Attach") `work` (#key("SPC s a")) switches this window to it, and -#word("Detach") (#key("SPC s D")) leaves it running. Every attached frontend -sees the same screen. +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> @@ -229,6 +270,22 @@ Shell zsh ``` #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 +#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]). |