path: root/src/tutor.txt

                               PARDES TUTOR

 This pane is +Tutor, a copy: edit it freely; there is no need to
 Save it (a bare Save asks for a path to write a copy to).
 `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.
 `Exec` (B2) runs the builtin a word names, or else runs it as a
 shell line; `Look` (B3) opens what the text names, or else finds
 it. Type a builtin in any tag and `Exec` it. Lines starting with
 "| " are tags.

 Press j until you reach part 1.


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

 1. The box left of this pane's tag is 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, and pardes types
    ls at its first prompt. 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. `Look` (B3) the word mouse in this sentence: the next mouse is
    selected.
 2. `Exec` (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: `Exec`, as B2. Enter
    is `Look`, as 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 Tab: `Help`
    runs and its list takes the keyboard. Esc brings you 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 `Exec` it: a command pane
    shows its output, and the keyboard stays here.
 2. `Exec` `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.
    Ctrl-i needs the kitty keyboard protocol or the GUI; elsewhere it
    is Tab, so use SPC j i (and SPC j o), or the mouse's side buttons.
 4. `Del` the scratch and the command pane, each in its own tag.

 -> Guide: Where commands run and panes go


=================================================================
=   PART 5 — LOOK                                               =
=================================================================

 1. `Look` :20 here: the cursor goes to line 20 of this pane.
 2. Drag across :/^=.*UNSAVED/ with B3 held: `Look` takes exactly
    what you swept, a regex here, and goes to Part 7's heading.
 3. Press /, type keys, press Enter: a +Search lists the lines with
    keys. n moves into it and walks its rows; Enter on a row goes
    to that line here.

 -> Guide: Look


=================================================================
=   PART 6 — TERMINALS                                          =
=================================================================

 1. In the terminal from part 1 (or Alt-n again), its ls has listed
    the directory. Press Ctrl-b to NORMAL, put the cursor on a name
    with j, k and w, select it with m i W, and 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. `Exec` `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, press SPC q or `Exec` `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

 3l moves three: a number typed FIRST is a count. The motions,
 f/F/t/T and Alt-., gg/gj/gk, x, o/O, > <, p/P, R, Ctrl-a/Ctrl-x,
 C ( ), q and . take one; any other key swallows it (3d deletes
 once, 3i types once). 0 is always line start; Ctrl-d/u/f ignore
 counts.

# 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 text `Look` would open, 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                                           =
-----------------------------------------------------------------

 SPC f s is `Save`: nearly every builtin has a key path as well as
 a name. What you have typed shows on the message row; Esc, or a key
 that leads nowhere, abandons it.

   SPC ?        `Help`: every builtin and its keys
   SPC d        `Del`       SPC q      `Exit`
   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
 -> Every helix key: https://docs.helix-editor.com/keymap.html


=================================================================
=   PART 10 — SCRIPTING                                         =
=================================================================

 Every session is a virtual filesystem, served over 9P: a program that
 opens files IS an extension.

   9ns --mntgen          mount every session (9ns is cloud9's)
   m=$PARDES_MOUNT                   the session, under 9ns
   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 `Look` in it
   echo Save > $m/pane/3/ctl         a builtin on pane 3

 While a program holds a pane's event file open, each `Exec` and
 `Look` in that pane comes to it instead of acting, and writing one
 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 in NORMAL goes back a pane (the guide's Modes table)
            Ctrl-b toggles RAW and NORMAL

 MOUSE      L select/focus   M `Exec`   R `Look`
            1-2 cut   1-3 paste   both in turn: copy
            2-1 `Exec` the middle word with the left selection
            keyboard: Enter = `Look`, Tab = `Exec`

 PANES      Ctrl-w h/j/k/l  focus a neighbour (NORMAL mode)
            Ctrl-o / Ctrl-i jump history back / forward
                (SPC j o / SPC j i where Ctrl-i is Tab)
            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 ? is `Help`)

 vs HELIX   selection is LINE-first (x), v for characters; / is a
            substring search; n/N walk what `Look` would open.
 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: `Exec` `Tutor` in the top tag, or
 SPC h t. `Exit` in the top tag quits everything; `Kill` only stops
 commands.