diff options
Diffstat (limited to 'docs/typ/guide.typ')
| -rw-r--r-- | docs/typ/guide.typ | 216 |
1 files changed, 112 insertions, 104 deletions
diff --git a/docs/typ/guide.typ b/docs/typ/guide.typ index 8c378c70..e2b9ae77 100644 --- a/docs/typ/guide.typ +++ b/docs/typ/guide.typ @@ -4,13 +4,12 @@ #import "style.typ": key, keys, btn, chord, word, tag, addr, file, cmd, doc, pairs, glossary 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) on `src/bar.c:12` opens that line; on a URL, +the browser; on any other word, its next place. #word("Exec") +(middle-click) on `Save` runs that builtin; on `make`, a shell line. The +screen is columns of panes, each a tag (a line of words) over a file, a +terminal, a PDF or an image. The keys are helix's, and every session is a +virtual filesystem, served over 9P, for scripts. #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], @@ -26,8 +25,7 @@ session is also a virtual filesystem, served over 9P, for scripts. = 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, shown in the box left of its tag. #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").], @@ -35,26 +33,28 @@ at the left of a pane's tag shows 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.], ) -#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, prompts hidden. #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.], + [normal], [#key("Esc"): back to the previous pane (#word("Last")), unlike helix. #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 `$`.], [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. +#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. + +#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)], +) + +Raw mode sends every key but #key("Ctrl-b"), Esc and the paste chords to +the program: leave it before #key("Ctrl-w") or #key("Alt-n"). = The mouse <mouse> @@ -62,21 +62,22 @@ 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], ) 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 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 with no drag takes the run of letters, digits +and `. - + / : @ _ ~` under it, a trailing `:` dropped. Drag to say +exactly what you mean. #key("Enter") and #key("Tab") in normal mode are +#word("Look") and #word("Exec"). -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("y") yanks and #key("p") pastes after (#key("x") #key("y") then +#key("p") puts the line in below), through registers every pane shares; +#key("SPC y") and #key("SPC p") use the system clipboard. = Tags <tags> @@ -84,19 +85,19 @@ 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. +A tag is text with undo: type `make` into one and #word("Exec") it, or +delete the words you never use. #key(":") moves the keyboard onto the +tag's #word("Save") the first time (#key("Tab") runs it), and back. Any word runs from any +tag: #word("Exit") in a pane's tag quits too. Edit the path to +`/home/me/notes2.txt` and press #key("Enter"): 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. = 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: +the #word("Shell") setting's `-c`, by where you clicked: #pairs( [a terminal's text or tag, at a prompt with nothing typed], [typed into that shell, in its current directory], @@ -105,58 +106,58 @@ 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`: +So run `make` from a column or the workspace tag, not a file's. The +keyboard stays where it was, and 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. +#word("Kill") `make` stops what pardes started whose line starts with +`make`; #word("Exit") quits pardes. #word("Save") or #word("Del") in a +column tag acts on that column's pane with the keyboard, or 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")). +#btn("B3") on a file open in another column jumps there, but 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")). -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. +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/"), [`ls` typed into a terminal idle there, else a new terminal there], + addr("https://ziglang.org"), [the browser], +) + +#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`, the cursor on the first; #keys("n", "N") step through], + [#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], +) = 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 (marked on its grip) 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> @@ -174,42 +175,49 @@ over unsaved panes too. #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], + [#key("SPC ?")], [every leader path; #word("Help") every key and builtin; #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 normal and insert keys are helix's, and helix's +The keys are helix's, and helix's #link("https://docs.helix-editor.com/keymap.html")[keymap] is their full -reference. pardes's own keys and where it differs from helix -(#key("Esc") leaving the pane, the #key("SPC") paths, #key("Ctrl-w"), -#key("Ctrl-b")) are in this guide and on the cheatsheet (#doc("cheatsheet")). +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> @@ -218,10 +226,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> @@ -235,6 +243,6 @@ 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`. |