From d3638abbb3d177ea08beed3b09cd9682b3732daf Mon Sep 17 00:00:00 2001 From: Gabriel Schneider Date: Thu, 1 Oct 2026 11:03:21 -0300 Subject: The docs give back the day-one lines the trim cut, the tutor becomes exercises on a +Tutor copy, the README builds the GUI and says what a terminal needs, and Shift-Esc says it needs the kitty keyboard protocol Co-Authored-By: Claude Opus 5.5 --- src/tutor.txt | 292 +++++++++++++++++----------------------------------------- 1 file changed, 83 insertions(+), 209 deletions(-) (limited to 'src/tutor.txt') diff --git a/src/tutor.txt b/src/tutor.txt index a1b3d75d..b47b3488 100644 --- a/src/tutor.txt +++ b/src/tutor.txt @@ -1,64 +1,34 @@ PARDES TUTOR - tmux + vi + acme, from scratch. + tmux + vi + acme, by doing. - 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. + This pane is +Tutor, a copy: edit it freely, and don't Save it + (Save would write a file named +Tutor in the session's directory). + `Del` in its tag closes it; once you have edited it, `Del` refuses + once and the second `Del` discards. `Tutor` or SPC h t opens a + fresh copy. - The lessons follow the guide (docs/typ/guide.typ, the "Guide" - chapter of the pardes book), and each ends by naming its section. + The guide (docs/typ/guide.typ) explains; this is the hands-on part. + Each lesson is a few things to do, then names its guide section. + Words in backticks, like `Save`, are builtins: type one in any tag + and middle-click it. Lines starting with "| " are tags. - 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. + Press j until you reach part 1. ================================================================= = 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 - INSERT Esc back to NORMAL - Shift-Esc out of INSERT and back to the previous pane - 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. + 1. Look at the box left of this pane's tag: blank, so you are in + NORMAL mode. Press i: it shows ^ (INSERT). Type a word, then + Esc: blank again. + 2. Press Esc once more, in NORMAL: the keyboard goes back to the + pane you were in before (not what helix does). Come back with + Esc again. + 3. Press Alt-n: a terminal opens, in NORMAL mode. Press Ctrl-b: its + box shows $ (RAW), and keys go to the shell. At its empty prompt, + Esc brings you back here; the terminal stays $. -> Guide: Modes @@ -67,31 +37,14 @@ = 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. + 1. Right-click (B3) the word mouse in this sentence: the next mouse + is selected. + 2. Middle-click (B2) the word `Help` here: the list of keys opens. + Close it with `Del` in its tag. + 3. Select a word with B1, keep B1 down, click B2: it is cut. Still + holding B1, click B3: it comes back. That pair is a copy. + 4. Put the cursor on `Help` and press Tab: the same as B2. Enter + is B3. -> Guide: The mouse @@ -100,73 +53,37 @@ = PART 3 — TAGS = ================================================================= - Three kinds of tag, every word live. The workspace tag on top: + The workspace tag, a column's, and a file's, a terminal's, a PDF's + and an image's: | 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. + 1. Press : here: the keyboard goes to this pane's tag, on `Save`. + Press A, type a space and Help, press Esc, then middle-click + `Help` there. Press : again to come back. + 2. Click `Collapse` in this tag: the pane folds to its tag. Click + it again. + 3. Drag the box left of the tag down a few rows, then back. -> Guide: Tags ================================================================= -= PART 4 — PANES AND COLUMNS = += PART 4 — WHERE COMMANDS RUN AND PANES GO = ================================================================= - 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. + 1. Type date on a line here and middle-click it: a command pane + shows its output, and the keyboard stays here. + 2. Middle-click `New` in this column's tag: a scratch opens and + takes the keyboard. + 3. Ctrl-w h, j, k, l move the keyboard between panes; Ctrl-o and + Ctrl-i walk back and forward through where you have been. + 4. `Del` the scratch and the command pane, each in its own tag. -> Guide: Where commands run and panes go @@ -175,96 +92,50 @@ = 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. + 1. Right-click :20 here: the cursor goes to line 20 of this pane. + 2. Right-click :/UNSAVED/ to go to the next match of UNSAVED. + 3. Press /, type keys, press Enter: a +Search lists the lines with + keys and the cursor goes to the first. n and N step through. -> Guide: Looking ================================================================= -= PART 6 — COMMANDS AND TERMINALS = += PART 6 — 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. + 1. In the terminal from part 1 (or Alt-n again), type ls and press + Enter in RAW mode. Then Ctrl-b to NORMAL: move over its output + with j and k, select a name with x, yank it with y. + 2. Come back here (Ctrl-w, or click) and press p: the name is + pasted; yank and paste are shared by every pane. + 3. `Del` the terminal: it closes with its shell. - -> Guide: Where commands run and panes go, Terminals + -> Guide: Terminals ================================================================= -= PART 7 — UNSAVED PANES, DIFFS, AND pardes FILE = += PART 7 — UNSAVED PANES = ================================================================= - `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. + 1. Middle-click `New`, type a few hundred characters, then `Del` it: + it refuses once, saying so on the message row. `Del` again + discards it. + 2. To quit pardes, middle-click `Exit` in the workspace tag; it + refuses once over unsaved panes 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 + -> Guide: Unsaved panes ================================================================= = 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. + 1. `Config` (SPC f c) opens your startup file: a builtin a line, + run at start. + 2. In a shell, pardes --detach=work starts a session with no screen; + pardes --attach=work shows it; `Detach` (SPC s D) leaves it + running. -> Guide: Sessions, Config @@ -278,6 +149,10 @@ selection. There is no verb+noun: the motion already selected, so wd is what dw was in vim. + PRACTICE BLOCKS: the "# keys:" line lists keystrokes (esc, enter + and bs are those keys; anything else types each character). Do them + on the "# before" lines and you should get "# after". + ----------------------------------------------------------------- = 9.1 MOTION AND COUNTS = ----------------------------------------------------------------- @@ -390,11 +265,9 @@ typed 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. + LANGUAGE KEYS, once a server is installed (see setup): g d + definition, g r references, SPC l k hover, SPC l r rename, SPC l i + what is running, ] d diagnostics, = format. ----------------------------------------------------------------- = 9.6 SPC — THE LEADER = @@ -429,7 +302,8 @@ typed 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 + n=$(cat $m/pane/new) a pane of your own + echo notes.txt:12 > $m/pane/$n/look a right click in it echo Save > $m/pane/3/ctl a builtin on pane 3 While a program holds a pane's event file open, middle and right @@ -445,10 +319,10 @@ typed ================================================================= 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: back to the previous pane from any mode, - RAW included; Ctrl-b toggles RAW and NORMAL + Esc and Shift-Esc: see the guide's Modes table + (Shift-Esc needs the kitty keyboard protocol or the + GUI; elsewhere it is a plain Esc) + 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 @@ -476,5 +350,5 @@ typed 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. + SPC h t. `Exit` in the top tag quits everything; `Kill` only stops + commands. -- cgit v1.3