path: root/src/tutor.txt

                               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
   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.

 -> 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/<pid or name>
   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: back to the previous pane from any mode,
                RAW included; 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.