From 449a75652d07a3df8254ee1b9fc0fa14e7a62643 Mon Sep 17 00:00:00 2001 From: Gabriel Schneider Date: Thu, 1 Oct 2026 14:01:10 -0300 Subject: The guide opens with one line and the annotated pane, drops the glossary entries its legend shows, loosens its first half into short sentences and tables, and ends with Questions Co-Authored-By: Claude Opus 5.5 --- docs/typ/guide.typ | 110 ++++++++++++++++++++++++++++++----------------------- 1 file changed, 62 insertions(+), 48 deletions(-) (limited to 'docs/typ/guide.typ') 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", , - [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 -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 @@ -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 @@ -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 -#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. - -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")). +#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")). 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 + +/ 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) -- cgit v1.3