PARDES TUTOR tmux + vi + acme, from scratch. The model is acme's: EVERYTHING is text, editable and executable the same way. Modal editing (helix-style) lives on top of that. Press j until you reach part 1. The lessons follow the guide (docs/typ/guide.typ, the "Guide" chapter of the pardes book), and each ends by naming its section. Words written in backticks, like `Save`, are builtins: type one in any tag and middle-click it. Lines starting with "| " are tags as pardes draws them, words only. PRACTICE BLOCKS (part 9): the "# keys:" line lists keystrokes (space-separated; esc/enter/bs are special, the rest type each char). The lines under "# before" are what you practise on; "# after" is what you should end up with. Nothing runs them. What pins the real behaviour is `zig build hxdiff`, which replays test/hxcases against goldens recorded from a real helix, and `zig build hxparity`, which runs each case in a file pane and in a shell and demands they agree. ================================================================= = PART 1 — MODES = ================================================================= A pane is text on screen, a tag over a body. Some panes are live terminals; most are text you move a cursor over. 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: NORMAL keys move and select. The box is BLANK. ^ INSERT keys type text at the cursor. $ RAW keys go straight to the program (terminals only). Where each pane starts: a file or a PDF in NORMAL; a terminal from `Tty` in RAW, one from Alt-n in NORMAL; a command pane in RAW while its command runs. A bare `pardes` starts a shell in RAW with an empty text pane under it; `pardes FILE` starts on the file. Esc and Shift-Esc, by mode: NORMAL Esc back to the previous pane (`Last`, SPC j j) Shift-Esc the same; in a terminal it switches to RAW INSERT Esc back to NORMAL Shift-Esc the same; in a terminal it switches to RAW RAW Esc goes to the program, except at an idle, EMPTY shell prompt: back to the previous pane Shift-Esc always back to the previous pane a PDF Esc clears the selection and search highlights Shift-Esc back to the previous pane Leaving a RAW terminal leaves it RAW. Ctrl-b switches a terminal between RAW and NORMAL; `Mode` in its tag steps RAW, NORMAL, INSERT. "The previous pane" is the last other pane on the jump list, else the next pane down its column. Shift-Esc needs a terminal that reports modifiers on Escape (the kitty keyboard protocol); elsewhere it arrives as a plain Escape. -> Guide: Modes ================================================================= = PART 2 — THE MOUSE = ================================================================= Three buttons, three verbs: B1 LEFT select; a plain click puts the cursor there and gives the pane the keyboard. In a tag: type there. B2 MIDDLE EXECUTE the word or selection: a builtin, or a shell line. B3 RIGHT LOOK: open the file, address, directory or URL under the pointer, or else find the word's next place. A B2 or B3 click with no drag takes the word around it: letters, digits and . - + / : @ _ ~, a trailing : dropped. So a right click anywhere on src/bar.c:12:5: in a compiler error opens that file at line 12, column 5. Drag to say exactly what you mean. CHORDS: hold one button and click another without letting go: 1-2 (hold left, click middle) CUT the left selection 1-3 (hold left, click right) PASTE over it 1-2 then 1-3, in one hold COPY 2-1 (hold middle, click left) execute the middle word WITH the left selection as its argument KEYBOARD EQUIVALENTS, in NORMAL mode: Enter = LOOK (right button) Tab = EXECUTE (middle button) Both act on the selection when there is one, else the word under the cursor. -> Guide: The mouse ================================================================= = PART 3 — TAGS = ================================================================= Three kinds of tag, every word live. The workspace tag on top: | Newcol Joincol Find Grep Help Changelog Tutor Dump Themes Config Debug Exit Each column's tag: | New Tty Find Grep Joincol Delcol Each pane's tag, after its path: a file's, a terminal's, a PDF's, an image's: | Save Tty Collapse Del | Tty Save Mode Filter Collapse Del | Tty PdfSections PdfTint Collapse Del | Tty Collapse Del Commands from the workspace or a column tag run in the session's directory; commands from a pane's tag run in the pane's directory. A tag is text, with undo: type a word into it and middle-click it, or delete the defaults. `:` in NORMAL mode moves the keyboard to the pane's tag and back. Clicking the path at the start of a pane's tag drafts a new name: Enter confirms, `Save` writes there. `Collapse` folds a pane to its tag; again unfolds it. The grip, the box left of the tag, marks unsaved text; drag it up or down to resize the pane, or onto another column to move it there. -> Guide: Tags ================================================================= = PART 4 — PANES AND COLUMNS = ================================================================= FOCUS A NEIGHBOUR (not in INSERT or RAW mode) Ctrl-w h/j/k/l the pane left / down / up / right; up from a column's top pane reaches its tag SPC w h/j/k/l the same GO BACK Esc the previous pane (`Last`, also SPC j j) Ctrl-o walk the jump history BACK (`Back`) Ctrl-i walk it FORWARD (`Forward`) SPC j l the jump list as a pane (`Jumplist`) Ctrl-i and Tab are the same byte on an old terminal; there Tab keeps meaning execute and Ctrl-i does nothing. MAKE, MOVE AND CLOSE Alt-n a new terminal (in NORMAL mode) Alt-c move the pane into a new column (not when it is alone in its column, nor past 16 columns) `New` a scratch pane, +New, in this pane's directory `Newcol` an empty column right of this one `Tty` a terminal in this pane's directory `Del` close the pane; from the keyboard (SPC d), between two panes, it asks which one gets the rows: k or j `Delcol` close the column and its panes `Joincol` fold this column into the one on its right THE ACTIVE COLUMN is where new panes go: the column you last typed or left-clicked in, or the one that got the last new pane. A look moves the keyboard but not the active column, so after a look jumps to a file open in another column, the next new pane still lands in the old one. Type or click to move it. Closing a column's last pane leaves the column empty; closing the session's last pane quits pardes. -> Guide: The active column and the keyboard ================================================================= = PART 5 — LOOKING = ================================================================= Type an address anywhere, then right-click it or press Enter: notes.txt:12 line 12 notes.txt:12:5 line 12, byte column 5 notes.txt:/re/ the next match; notes.txt:0/re/ the first :40 this pane, line 40 @p3:12 pane 3 (by serial), line 12 src/ a directory: ls in an idle terminal there A relative path is looked for in this pane's directory first, then in the directory of each pane on the jump list, most recent first. n and N step through everything a look would open, across panes, as a ring; Enter opens what you land on. -> Guide: Looking ================================================================= = PART 6 — COMMANDS AND TERMINALS = ================================================================= Middle-click a line that is no builtin (make, git log) and it runs. In a terminal idle at an empty prompt, a line from its own text is typed into its shell; anywhere else it runs in a COMMAND PANE, a terminal of its own whose tag says running, then exit N: | Kill Save Collapse Del The next command for the same directory reuses a finished command pane; one still running is never reused. `Kill` stops what pardes started (`Kill make`: those starting with make). `Exit` quits pardes. A TERMINAL IS A PANE. In NORMAL mode its prompts are hidden and the same keys that edit a file move over its text; in RAW mode the real shell has the keys. pardes --tty-toggle=g picks another letter than b for the toggle. `Tty+bash` another terminal, on that shell `Save` asks for a path, then writes the scrollback there `Filter` maps the program's colours through the theme Ctrl-V in RAW: types what you yanked (with nothing yanked, the program gets the key); Ctrl-Shift-V types the desktop clipboard A program that tracks the mouse (htop, vim with mouse=a) gets B1 and the wheel; B2 and B3 stay pardes's. Hold Shift to swap them. -> Guide: Command panes, Terminals ================================================================= = PART 7 — UNSAVED PANES, DIFFS, AND pardes FILE = ================================================================= `Del` on a pane with unsaved text refuses once and lists it in +Unsaved; the same `Del` again, with nothing edited since, discards it. `Exit`, `Restore` and `Delcol` refuse once the same way. Run git diff as a command, or open a .patch: it shows as a coloured diff. Right-click a diff --git, --- or +++ line to open the file, a @@ line for the hunk's first new line, a hunk line's first column for that line in the new file. In a pane's shell, pardes FILE opens FILE in this session, and EDITOR='pardes --wait' makes git commit open its message in a pane and carry on when you close it. -> Guide: Unsaved panes, Reviewing diffs, pardes FILE and --wait ================================================================= = PART 8 — SESSIONS AND CONFIG = ================================================================= A session is a core (text, undo, layout, the pane shells) and a frontend that draws it. They do not have to be one process: pardes --detach=work a session with no screen of its own pardes --attach=work show it here pardes-gui --attach=work an SDL window is a frontend too From inside: `Attach` work (SPC s a) switches this window to it, and `Detach` (SPC s D) leaves it running, shells and all. Frontends attached together share ONE screen at the smallest common size. The session ends when its last pane closes. `Config` (SPC f c) opens the startup file, ~/.config/pardes/init: a builtin a line, run at start (Theme atelier, Shell zsh). `Dump` and `Restore` save and reload the workspace. -> Guide: Sessions, Config ================================================================= = PART 9 — THE KEYS (helix-style modal) = ================================================================= Same core as helix: a block cursor you move with h/j/k/l, motions that SELECT what they cross, and an edit that acts on the selection. There is no verb+noun: the motion already selected, so wd is what dw was in vim. ----------------------------------------------------------------- = 9.1 MOTION AND COUNTS = ----------------------------------------------------------------- k h left, l right, j down, k up (also arrows) h l w/b/e word forward/back/end (W/B/E long) j 0 line start, gl line end, ^ first non-blank gg first line, ge START of the last line f/F/t/T find a character forward/back Bare G does NOTHING; a count first (5G) goes to that line. $ is not line end: it keeps the selections a shell command succeeds on. # keys: l l l # before abcdef # after abcdef A number typed FIRST is a count, and only some keys take one, among them the motions, f/F/t/T and the Alt-. that repeats them, gg/gj/gk, x, o/O, > and <, p/P, R, Ctrl-a/Ctrl-x, the cursor-list keys C and ( ), q and the . repeat. Elsewhere it is swallowed: 3d deletes once, 3i types once. 0 is always line start and never starts a count. Ctrl-d/u/f ignore counts: a page is a page. # keys: 3 l i Z esc # before abcdef # after abcZdef ----------------------------------------------------------------- = 9.2 ENTERING INSERT = ----------------------------------------------------------------- i at the cursor. a after it. I first non-blank. A end of line. o open below. O open above. Esc returns to NORMAL. # keys: i X esc # before abc # after Xabc # keys: o line2 esc # before line1 # after line1 line2 ----------------------------------------------------------------- = 9.3 MOTIONS SELECT = ----------------------------------------------------------------- w/b/e and f/F/t/T leave a SELECTION behind them, so i after a motion types at the selection's START. ; collapses the selection to the cursor first; w left the cursor on the space. # keys: w i Z esc # before one two # after Zone two # keys: w ; i Z esc # before one two # after oneZ two ----------------------------------------------------------------- = 9.4 SELECT AND EDIT = ----------------------------------------------------------------- x select the LINE (again: one more) v extend by characters, then move d delete the selection c change it y yank it p / P paste after / before u undo U redo > < indent / outdent Ctrl-a / Ctrl-x increment / decrement # keys: x c typed esc # before replace me # after typed ----------------------------------------------------------------- = 9.5 THE REST, IN ONE PLACE = ----------------------------------------------------------------- s / S regex, one cursor per match, previewing as you type; C , ( ) Alt-s Alt-- Alt-_ _ work the resulting LIST m i / m a textobjects: w W p, the bracket pairs, the quotes m s/r/d surround add / replace / delete; m m the match ] p, [ p step by paragraph; ] d, [ d by diagnostic ] space a blank line below; [ space above | filter every selection through the shell / case-insensitive SUBSTRING search, one hit a line; the regex lives on s and S n / N the next/previous look-able text, as above Ctrl-c comment or uncomment the lines VIEWPORT z t, z z, z b scroll the cursor to the top / centre / bottom z j, z k scroll a line, the cursor pushed along Ctrl-d/u half a page down / up Ctrl-f a page down. Ctrl-b pages up in a file; in a terminal it is the RAW toggle. LANGUAGE SERVERS run as child processes, one per language on PATH (zls, rust-analyzer, clangd, gopls, typescript-language-server, pyright): g d definition, g r references, g D g y g i, SPC l k hover, SPC l r rename, SPC l i what is running, ] d diagnostics, = format. ----------------------------------------------------------------- = 9.6 SPC — THE LEADER = ----------------------------------------------------------------- Nearly every builtin has a NAME you can execute wherever text lives and a KEY PATH you can press. SPC in NORMAL mode starts the path; what you have typed shows on the message row until it fires. Esc abandons it, and so does any key that leads nowhere. SPC ? list every path SPC d `Del` (`Exit` has no path: use the top tag) SPC f s `Save` SPC f f `Find` SPC f n `New` SPC y yank to the clipboard SPC p paste from it SPC w h focus left (and j, k, l) SPC j j `Last` SPC j o / SPC j i back / forward SPC s a `Attach` SPC s D `Detach` SPC t ... the toggles SPC l ... the language SPC h t this tutor -> Guide: Keys ================================================================= = PART 10 — SCRIPTING = ================================================================= Every session serves its panes as files over 9P: a program that opens files IS an extension, with no plugin API. Pane shells get $PARDES_9P (the socket) and $PARDES_PANE (their pane's serial). 9ns --mntgen mount every session (9ns is cloud9's) m=$NINE_MOUNT/pardes/ cat $m/index a line per pane echo notes.txt:12 > $m/look a right click echo Save > $m/pane/3/ctl a builtin on pane 3 While a program holds a pane's event file open, middle and right clicks in that pane come to it instead of acting, and writing a click back makes pardes perform it: arbitrary command execution by design. The socket sits in your private runtime directory. -> The Scripting chapter (docs/typ/scripting.typ) ================================================================= = SUMMARY = ================================================================= MODES blank NORMAL, ^ INSERT, $ RAW; each pane keeps its own Esc: back to the previous pane (RAW: only at an empty prompt; INSERT: back to NORMAL) Shift-Esc: out of RAW always; in a terminal's NORMAL, into RAW; Ctrl-b toggles RAW and NORMAL MOUSE L select/focus M execute R look 1-2 cut 1-3 paste 1-2 then 1-3 copy 2-1 execute the middle word with the left selection keyboard: Enter = look, Tab = execute PANES Ctrl-w h/j/k/l focus a neighbour (NORMAL mode) Ctrl-o / Ctrl-i jump history back / forward Alt-n new terminal Alt-c pane into a new column KEYS h j k l w b e 0 gl ^ gg ge f F t T v x d c y p i a I A o O u undo U redo motions SELECT: i types at the selection's start, and ; collapses first bare G does nothing; ge is the START of the last line s / S regex cursors; m i/a textobjects; m s/r/d surround / is a case-insensitive SUBSTRING search, not a regex SPC is the leader (SPC ? lists every path) vs HELIX selection is LINE-first (x), v for characters; / is a substring search; n/N walk look-able text. vs VIM no verb+noun: the motion already selected, so wd is what dw was; Esc goes back a pane; bare G does nothing. vs BOTH a terminal is just a pane, and the session can outlive the terminal that is showing it. Open this tutor again: middle-click `Tutor` in the top tag, or SPC h t. It is a file pane: close it with `Del` in its tag. `Exit` in the top tag quits everything; `Kill` only stops commands.