path: root/src/tutor.txt

                               PARDES TUTOR
                     tmux + vi + acme, by doing.

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

 Press j until you reach part 1.


=================================================================
=   PART 1 — MODES                                              =
=================================================================

 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


=================================================================
=   PART 2 — THE MOUSE                                          =
=================================================================

 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


=================================================================
=   PART 3 — TAGS                                               =
=================================================================

 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
| New Tty Find Grep Joincol Delcol
| Save Tty Collapse Del
| Tty Save Mode Filter Collapse Del
| Tty PdfSections PdfTint Collapse Del
| Tty Collapse Del

 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 — WHERE COMMANDS RUN AND PANES GO                    =
=================================================================

 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


=================================================================
=   PART 5 — LOOKING                                            =
=================================================================

 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 — TERMINALS                                          =
=================================================================

 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: Terminals


=================================================================
=   PART 7 — UNSAVED PANES                                      =
=================================================================

 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.

 -> Guide: Unsaved panes


=================================================================
=   PART 8 — SESSIONS AND CONFIG                                =
=================================================================

 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


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

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

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

 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
   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
 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 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
            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. `Exit` in the top tag quits everything; `Kill` only stops
 commands.