diff options
| -rw-r--r-- | docs/typ/guide.typ | 108 |
1 files changed, 61 insertions, 47 deletions
diff --git a/docs/typ/guide.typ b/docs/typ/guide.typ index 7cf2b38f..9149969a 100644 --- a/docs/typ/guide.typ +++ b/docs/typ/guide.typ @@ -3,13 +3,7 @@ // keys on the cheatsheet. #import "style.typ": key, keys, btn, chord, word, tag, addr, file, cmd, doc, pairs, glossary, annotated -pardes reads the text on its screen as things to do, with two builtins. -#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. +Two clicks carry pardes: #word("Look") (right-click) opens `src/bar.c:12`, and #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", @@ -22,7 +16,6 @@ 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], [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)], @@ -30,22 +23,23 @@ 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 keeps its own mode, shown in the box left of its tag. +Each pane keeps its own mode. The box left of its tag shows it. +// TODO: once style.typ has #mode-box(mark), put the box itself in each +// row's first cell instead of naming its mark. #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.], ) -#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. +#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")), unlike helix. #key("Shift-Esc"): the same.], @@ -54,17 +48,17 @@ in the tag steps raw, normal, insert. [a PDF], [#key("Esc"): clears the selection and the search highlights. #key("Shift-Esc"): back to the previous pane.], ) -#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("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)], ) -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"). +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> @@ -75,19 +69,23 @@ the program: leave it before #key("Ctrl-w") or #key("Alt-n"). 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], ) +// TODO: embed the `chords` clip here on the site once it lands (needs a +// clip hook in style.typ). -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. #btn("B3") on `src/bar.c:12:5:` in a compiler's error opens `src/bar.c` at -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"). +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"). -#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. +#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> @@ -95,19 +93,21 @@ exactly what you mean. #key("Enter") and #key("Tab") in normal mode are #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. #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. +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")], [the next #word("Save") writes to the new path], + [#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`, by where you clicked: +#btn("B2") on `make` runs it with the #word("Shell") setting's `-c`. +Where it runs depends on where you clicked: #pairs( [a terminal's text or tag, at a prompt with nothing typed], [typed into that shell, in its current directory], @@ -117,23 +117,23 @@ the #word("Shell") setting's `-c`, by where you clicked: ) 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`, +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") `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. +#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. -#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")). +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")). Closing a column's last pane leaves it empty; #word("Delcol") and #word("Joincol") take columns away. Closing the session's last pane quits @@ -256,3 +256,17 @@ Shell zsh #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, without + modal keys, a terminal emulator or PDFs. pardes puts text as the interface, helix's + keys, terminals, PDFs and a scriptable session in one program. +/ 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?: TODO(user) |