// 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 any text to *look* at it: open the `file:line`, address or URL it names, or else find the text. Middle-click 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 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 look and execute. 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. = 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 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. 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 middle-click #word("Exit") in the workspace tag; 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`.