// 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 pardes reads the text on its screen as things to do. Right-click (#btn("B3")) any text to *look* at it: open the `file:line`, address or URL it names, or else find the text. Middle-click (#btn("B2")) it to *execute* it: run the builtin it 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. #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)], [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 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, 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 has its own mode and keeps it while you are elsewhere. The box at the left of a pane's 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.], ) #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. #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 `$`.], [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. = The 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"), [execute: a builtin word runs, anything else is a shell line.], btn("B3"), [look: open the file, address, directory or URL, else find the word's next place.], ) A #btn("B2") or #btn("B3") 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 look and execute. Hold #btn("B1") and click #btn("B2") to cut the selection, #btn("B3") 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. = 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 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. = 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`. Where 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], [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], ) 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`: #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 (`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. Every other new pane goes into the *active column*: the column you last typed or #btn("B1")-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. A 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")). 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. = 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 looked for in the looking pane's directory, then in the directory 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. = 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 click #word("Exit") in the workspace tag with #btn("B2"); it refuses once over unsaved panes too. = 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; `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. - A program that tracks the mouse gets #btn("B1") and the wheel; #btn("B2") and #btn("B3") stay pardes's. Hold Shift to swap. - `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")). = 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. = `pardes FILE` and `--wait` 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. = 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 a 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")). = 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. #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. = 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`.