Extend tutor file (#2133)

* Adds tutorial sections for multiple areas including:
- Changing selections to uppercase / lowercase
- yanking and pasting
- macros
- selecting to chars with t and f

PS: I got kind of carried away and put off commiting for a while,
    will commit to commit more often in the future.

* Changed section titles to all uppercase

* Added recap and section about jumplist

* Added sections for searching in file, joining lines and indenting lines.

* Removed some trailing whitespace

* Evened out the space between sections to all be 5 lines

* Add section on opening lines (o) and recap

* Changed the amount of lines between sections

This is so that - on a 24 line terminal -
only one section is visible at a time and
page up/page down goes straight to the next
section keeping the header at the top.

* Punctuation error

Co-authored-by: Omnikar <omkar.subramaniam@icloud.com>

* Punctuation error

Co-authored-by: Omnikar <omkar.subramaniam@icloud.com>

* Spelling error

Co-authored-by: Omnikar <omkar.subramaniam@icloud.com>

* Remove unnecessary word

Co-authored-by: Omnikar <omkar.subramaniam@icloud.com>

* Reword note about searches

Co-authored-by: Omnikar <omkar.subramaniam@icloud.com>

* Change word

Co-authored-by: Omnikar <omkar.subramaniam@icloud.com>

* Update tutor file

* Made some small changes suggested by Omnikar

* Added better demo for macros.

* Small changes

- Add newlines at the end
- Make "MACROS" section fit into 22 lines
- Correct mistake of saying helix copied to clipboard in "COPYING AND PASTING TEXT"

* Reformatted notes in copying/pasting section to fit in screen

* Add a note about n and N and their difference to Vim.

* Combine f and t commands into one section.

* Removed t/T section which was merged into the f/F section.

* Merge sections on manipulating case into one.

* Gave section's numbers

* Convert 'press' to 'type' in some places

* Added examples of how prompt lines should look.

* Reformatted notes in copy/pasting section.

* More rewording to more comfortably fit sections on screen.

* Grammatical error.

* Missing periods.

* Missing capital + small reformat

* Fix mis-numbered section

* Reworded to use these conventions when referring to inputs:
- "Press" for single keypresses
- "Type" for multiple keypresses / modifiers
- "Use" when referencing two inputs as a pair.

* till not 'til

* Say 'press' instead of 'type' when referring to symbols

* 'outdent' not 'unindent'

* Typo and grammar.

* Replace all 'press's with 'type's (apart from places it would make no sense in).

* Improve examples for joining and indenting lines.

* Section alignment.

Co-authored-by: Omnikar <omkar.subramaniam@icloud.com>

1 files changed, 348 insertions, 59 deletions

diff --git a/runtime/tutor.txt b/runtime/tutor.txt
index b6f600d0..ae14eb78 100644
--- a/runtime/tutor.txt
+++ b/runtime/tutor.txt
@@ -12,7 +12,7 @@ _________________________________________________________________
  you might be used to in that it is modal, meaning that it has
  different modes for editing text. The primary modes you will
  use are Normal mode and Insert mode. While in Normal mode, the
- keys you press won't actually type text. Instead, they will
+ keys you type won't actually type text. Instead, they will
  perform various actions with the text. This allows for more
  efficient editing. This tutor will teach you how you can make
  use of Helix's modal editing features. To begin, ensure your
@@ -21,7 +21,7 @@ _________________________________________________________________
 
 
 =================================================================
-=                     BASIC CURSOR MOVEMENT                     =
+=                  1.1 BASIC CURSOR MOVEMENT                    =
 =================================================================
 
           ↑
@@ -43,18 +43,18 @@ _________________________________________________________________
 
 
 =================================================================
-=                        EXITING HELIX                          =
+=                      1.2 EXITING HELIX                        =
 =================================================================
 
- 1. Press the : key to enter command mode. Your cursor will
+ 1. Type : to enter command mode. Your cursor will
     move to the bottom of the screen.
- 2. Type q or quit and press <ENTER> to exit Helix.
+ 2. Type q or quit and type <ENTER> to exit Helix.
 
  Note: The quit command will fail if there are unsaved changes.
-       To force quit and DISCARD these changes, use q! or quit!.
+       To force quit and DISCARD these changes, type q! or quit!.
        You will learn how to save files later.
 
- To exit command mode without entering a command, press <ESC>.
+ To exit command mode without entering a command, type <ESC>.
 
  Now, move on to the next lesson.
 
@@ -65,13 +65,13 @@ _________________________________________________________________
 
 
 =================================================================
-=                           DELETION                            =
+=                         1.3 DELETION                          =
 =================================================================
 
- Press the d key to delete the character under the cursor.
+ Type the d key to delete the character under the cursor.
 
  1. Move the cursor to the line below marked -->.
- 2. Move the cursor to each extra character, and press d to
+ 2. Move the cursor to each extra character, and type d to
     delete it.
 
  --> Thhiss senttencee haass exxtra charracterss.
@@ -87,16 +87,16 @@ _________________________________________________________________
 
 
 =================================================================
-=                          INSERT MODE                          =
+=                       1.4 INSERT MODE                         =
 =================================================================
 
- Press the i key to enter Insert mode.
+ Type the i key to enter Insert mode.
 
  1. Move the cursor to the line below marked -->.
- 2. Move to a place in the line which is missing text and press
-    i to enter Insert mode. Keys you press will now type text.
+ 2. Move to a place in the line which is missing text and type
+    i to enter Insert mode. Keys you type will now type text.
  3. Enter the missing text.
- 4. Press <ESC> to exit Insert mode and return to Normal mode.
+ 4. type <ESC> to exit Insert mode and return to Normal mode.
  5. Repeat until the line matches the line below it.
 
  --> Th stce misg so.
@@ -106,13 +106,13 @@ _________________________________________________________________
        you may use the arrow keys instead of exiting and
        reentering Insert mode.
  Note: The status bar will display your current mode.
-       Notice that when you press i, 'NOR' changes to 'INS'.
+       Notice that when you type i, 'NOR' changes to 'INS'.
 
 =================================================================
-=                      MORE ON INSERT MODE                      =
+=                   1.5 MORE ON INSERT MODE                     =
 =================================================================
 
- As you saw, you can press i to enter Insert mode at the current
+ As you saw, you can type i to enter Insert mode at the current
  position of the cursor. There are a few other ways you can
  enter Insert mode at different locations.
 
@@ -123,7 +123,7 @@ _________________________________________________________________
    A - Insert at the end of the line.
 
  1. Move to anywhere in the line below marked -->.
- 2. Press A (<SHIFT> + a), your cursor will move to the end of
+ 2. Type A (<SHIFT> + a), your cursor will move to the end of
     the line and you will be able to type.
  3. Type the text necessary to match the line below.
 
@@ -131,19 +131,19 @@ _________________________________________________________________
      This sentence is missing some text.
 
 =================================================================
-=                         SAVING A FILE                         =
+=                      1.6 SAVING A FILE                        =
 =================================================================
 
- Use :w/:write to save a file.
+ Type :w/:write to save a file.
 
  1. Exit Helix using :q! as explained before, or open a new
     terminal.
  2. Open a file in Helix by running: hx FILENAME
  3. Make some edits to the file.
- 4. Press the : key to enter command mode.
- 5. Type w or write, and press <ENTER> to save the file.
+ 4. Type : to enter command mode.
+ 5. Type w or write, and type <ENTER> to save the file.
 
- You can also use wq or write-quit to save and exit.
+ You can also type wq or write-quit to save and exit.
 
  Note: You can optionally enter a filepath after the w/write
        command in order to save to that path.
@@ -153,21 +153,21 @@ _________________________________________________________________
 
 
 =================================================================
-=                             RECAP                             =
+=                        CHAPTER 1 RECAP                        =
 =================================================================
 
  * Use the h,j,k,l keys to move the cursor.
 
- * Press : to enter command mode.
+ * Type : to enter command mode.
    * The q/quit and q!/quit! commands will exit Helix. The
      former fails when there are unsaved changes. The latter
      discards them.
    * The w/write command will save the file.
    * The wq/write-quit command will do both.
 
- * Press d to delete the character at the cursor.
+ * Type d to delete the character at the cursor.
 
- * Press i to enter Insert mode and type text. Press <ESC> to
+ * Type i to enter Insert mode and type text. Type <ESC> to
    return to Normal mode.
 
 
@@ -175,10 +175,10 @@ _________________________________________________________________
 
 
 =================================================================
-=                    MOTIONS AND SELECTIONS                     =
+=                  2.1 MOTIONS AND SELECTIONS                   =
 =================================================================
 
- Press w to select forward until the next word.
+ Type w to select forward until the next word.
 
  The d key doesn't actually delete the character at the cursor,
  it deletes all selected text. Your cursor is like a
@@ -186,8 +186,8 @@ _________________________________________________________________
 
  1. Move the cursor to the line below marked -->.
  2. Move to the beginning of a word that needs to be deleted.
- 3. Press w to select until the beginning of the next word.
- 4. Press d to delete the selection.
+ 3. Type w to select until the beginning of the next word.
+ 4. Type d to delete the selection.
  5. Repeat for all extra words in the line.
 
  --> This sentence pencil has vacuum extra words in the it.
@@ -197,10 +197,10 @@ _________________________________________________________________
 
 
 =================================================================
-=                        MORE ON MOTIONS                        =
+=                     2.2 MORE ON MOTIONS                       =
 =================================================================
 
- As you saw, pressing w moves the cursor forward until the start
+ As you saw, typing w moves the cursor forward until the start
  of the next word, selecting the text traversed. This is useful
  for moving around text and for selecting text to operate on.
 
@@ -219,18 +219,18 @@ _________________________________________________________________
 
 
 =================================================================
-=                      THE CHANGE COMMAND                       =
+=                    2.3 THE CHANGE COMMAND                     =
 =================================================================
 
- Press c to change the current selection.
+ Type c to change the current selection.
 
  The change command deletes the current selection and enters
  Insert mode, so it is a very common shorthand for di.
 
  1. Move the cursor to the line below marked -->.
- 2. Move to the start of an incorrect word and press w to
+ 2. Move to the start of an incorrect word and type w to
     select it.
- 3. Press c to delete the word and enter Insert mode.
+ 3. Type c to delete the word and enter Insert mode.
  4. Type the correct word.
  5. Repeat until the line matches the line below it.
 
@@ -241,7 +241,7 @@ _________________________________________________________________
 
 
 =================================================================
-=                      COUNTS WITH MOTIONS                      =
+=                   2.4 COUNTS WITH MOTIONS                     =
 =================================================================
 
  Type a number before a motion to repeat it that many times.
@@ -263,15 +263,15 @@ _________________________________________________________________
 
 
 =================================================================
-=                        SELECTING LINES                        =
+=                     2.5 SELECTING LINES                       =
 =================================================================
 
- Press x to select a whole line. Press again to select the next.
+ Type x to select a whole line. Type x again to select the next.
 
  1. Move the cursor to the second line below marked -->.
- 2. Press x to select the line, and d to delete it.
+ 2. Type x to select the line, and d to delete it.
  3. Move to the fourth line.
- 4. Press x twice or type 2x to select 2 lines, and d to delete.
+ 4. Type x twice or type 2x to select 2 lines, and d to delete.
 
  --> 1) Roses are red,
  --> 2) Mud is fun,
@@ -285,13 +285,13 @@ _________________________________________________________________
 
 
 =================================================================
-=                            UNDOING                            =
+=                         2.6 UNDOING                           =
 =================================================================
 
  Type u to undo. Type U to redo.
 
  1. Move the cursor to the line below marked -->.
- 2. Move to the first error, and press d to delete it.
+ 2. Move to the first error, and type d to delete it.
  3. Type u to undo your deletion.
  4. Fix all the errors on the line.
  5. Type u several times to undo your fixes.
@@ -307,7 +307,7 @@ _________________________________________________________________
 
 
 =================================================================
-=                             RECAP                             =
+=                        CHAPTER 2 RECAP                        =
 =================================================================
 
  * Type w to select forward until the next word.
@@ -329,14 +329,14 @@ _________________________________________________________________
 
 
 =================================================================
-=                       MULTIPLE CURSORS                        =
+=                     3.1 MULTIPLE CURSORS                      =
 =================================================================
 
  Type C to duplicate the cursor to the next line.
 
  1. Move the cursor to the first line below marked -->.
  2. Type C to duplicate the cursor to the next line. Keys you
-    press will now affect both cursors.
+    type will now affect both cursors.
  3. Use Insert mode to correct the lines. The two cursors will
     fix both lines simultaneously.
  4. Type , to remove the second cursor.
@@ -346,22 +346,22 @@ _________________________________________________________________
 
      Fix these two lines at the same time.
 
-
+ Note: Type alt-C to do the same above the cursor.
 
 
 
 =================================================================
-=                      THE SELECT COMMAND                       =
+=                    3.2 THE SELECT COMMAND                     =
 =================================================================
 
  Type s to select matches in the selection.
 
  1. Move the cursor to the line below marked -->.
- 2. Press x to select the line.
- 3. Press s. A prompt will appear.
- 4. Type 'apples' and press <ENTER>. Both occurrences of
+ 2. Type x to select the line.
+ 3. Type s. A prompt will appear.
+ 4. Type 'apples' and type <ENTER>. Both occurrences of
     'apples' in the line will be selected.
- 5. You can now press c and change 'apples' to something else,
+ 5. You can now type c and change 'apples' to something else,
     like 'oranges'.
  6. Type , to remove the second cursor.
 
@@ -373,16 +373,16 @@ _________________________________________________________________
 
 
 =================================================================
-=                      SELECTING VIA REGEX                      =
+=                    3.3 SELECTING VIA REGEX                    =
 =================================================================
 
  The select command selects regular expressions, not just exact
  matches, allowing you to target more complex patterns.
 
  1. Move the cursor to the line below marked -->.
- 2. Select the line with x and then press s.
+ 2. Select the line with x and then type s.
  3. Enter '  +' to select any amount of consecutive spaces >1.
- 4. Press c and change the matches to single spaces.
+ 4. Type c and change the matches to single spaces.
 
  --> This  sentence has   some      extra spaces.
 
@@ -395,7 +395,7 @@ _________________________________________________________________
 
 
 =================================================================
-=                     COLLAPSING SELECTIONS                     =
+=                   3.4 COLLAPSING SELECTIONS                   =
 =================================================================
 
  Type ; to collapse selections to single cursors.
@@ -404,7 +404,6 @@ _________________________________________________________________
  cursor(s). This can be done using the ; key.
 
  1. Move the cursor to the line below marked -->.
-
  2. Use the motions you have learned to move around the line,
     and try using ; to deselect the text after it is selected
     by the motions.
@@ -416,6 +415,296 @@ _________________________________________________________________
 
 
 
+
+=================================================================
+=                 3.5 SELECTING TO A CHARACTER                  =
+=================================================================
+
+ Type f<ch> to select up to and including (find) a character.
+ Type t<ch> to do the same, but not including (till) a character.
+ Type uppercase F/T to do the same backwards.
+
+ 1. Move the cursor to the line below marked -->. Place the
+    cursor on the first dash.
+ 2. Type f[ to select to the square bracket.
+ 3. Type d to delete your selection.
+ 4. Go to the end of the line and repeat with F].
+ 5. Move to the second line marked -->, just after the arrow.
+ 6. Use t and T to delete the dashes around the sentence.
+
+ --> -----[Free this sentence of its brackets!]-----
+ --> ------Free this sentence of its dashes!------
+
+ Note: Unlike Vim, Helix doesn't limit these commands to the 
+       current line. It searches for the character in the file.
+
+=================================================================
+=                        CHAPTER 3 RECAP                        =
+=================================================================
+
+ * Type C to copy the selection on the line below and Alt-C for
+   above.
+
+ * Type s to select all instances of a regex pattern inside
+   the current selection.
+
+ * Type semicolon ( ; ) to collapse selection.
+
+ * Type f / F to extend selection up to & including a character.
+
+ * Type t / T to extend selection until a character.
+
+
+
+
+
+
+
+=================================================================
+=                 4.1 COPYING AND PASTING TEXT                  =
+=================================================================
+
+ Type y to yank (copy) the selection.
+ Type p to paste the yanked selection after the cursor.
+ Type P to paste the yanked text before the cursor.
+
+ 1. Move the cursor to the line below marked -->.
+    Make sure your cursor is on the "b" of banana.
+ 2. Type w to select "banana" and y to yank it.
+ 3. Move to the space between "2" and "3" and type p to paste.
+ 4. Repeat between "3" and "4".
+
+ --> 1 banana 2 3 4
+     1 banana 2 banana 3 banana 4
+
+ Note: Whenever you delete or change text, Helix will copy the
+       altered text. Use alt-d/c instead to avoid this.
+ Note: Helix doesn't share the system clipboard by default. Type
+       space-y/p to yank/paste on your computer's main clipboard.
+
+=================================================================
+=                     4.2 CHANGING CASE                         =
+=================================================================
+
+ Type ~ to switch the case of all selected letters.
+ Type ` to set all selected letters to lowercase.
+ Type Alt-` to set all selected letters to uppercase.
+
+ 1. Move the cursor to the first line below marked -->.
+ 2. Select each wrongly capitalised or lowercase letter
+    and type ~ over them.
+ 3. Move to the second line marked -->.
+ 4. Type x to select the line.
+ 5. Type ` to change the line to lowercase.
+ 6. Move to the third line marked -->.
+ 7. Type x to select the line.
+ 8. Type Alt-` to change the line to uppercase.
+
+ --> thIs sENtencE hAs MIS-cApitalIsed leTTerS.
+ --> this SENTENCE SHOULD all be in LOWERCASE.
+ --> THIS sentence should ALL BE IN uppercase!
+
+=================================================================
+=                          4.3 MACROS                           =
+=================================================================
+
+ Macros are a way to record a set of actions you want to repeat.
+
+ Type Q to start recording a macro, you should see a popup at
+ the bottom of your screen. Type Q again to stop recording.
+ Type q to repeat your recorded macro.
+
+ 1. Move the cursor to the first line below marked -->.
+    Ensure your cursor is on the > of the arrow.
+ 2. Type Q to start recording.
+ 3. Edit the line to look like the bottom one.
+ 4. Exit insert and Type Q again to stop recording.
+ 5. Move to the line below and put your cursor on the > again.
+ 6. Type q to repeat the macro.
+
+ --> ... sentence doesn't have it's first and last ... .
+ --> ... sentence doesn't have it's first and last ... .
+     This sentence doesn't have it's first and last word.
+
+=================================================================
+=                        CHAPTER 4 RECAP                        =
+=================================================================
+
+ * Type y to yank (copy) text and p to paste.
+   * Type space-Y and space-P to yank/paste on the system
+     clipboard.
+
+ * Type ~ to alternate case of selected letters.
+   * Use ` and alt-` to set the case of selected layers to
+     upper and lower respectively.
+
+ * Type Q to record and stop recording a macro.
+   * Type q to repeat the recorded macro.
+
+
+
+
+
+
+
+
+=================================================================
+=                    5.1 USING THE JUMPLIST                     =
+=================================================================
+
+ Helix can keep track of "jumps" which are big movements, like
+ jumping to the definition of a function in code. It stores
+ these in what's called the jumplist.
+
+ Type C-s (ctrl-s) to manually save your current position to
+ the jumplist.
+
+ Type C-i and C-o to move forward and backwards in the jumplist
+ respectively.
+
+ 1. Type C-s somewhere.
+ 2. Move far away in the file.
+ 3. Type C-o (just once!) to come back to where you saved.
+
+
+
+
+
+=================================================================
+=                     5.2 SEARCHING IN FILE                     =
+=================================================================
+
+ Type / to search forward in file, enter to confirm search.
+ Type n to go to the next search match.
+ Type N to go to the previous search match.
+
+ 1. Type / and type in a common word, like 'banana'.
+ 2. Type enter to confirm the search.
+ 3. Use n and N to cycle through the matches.
+
+ Like the select command, searching also uses regex.
+
+ Note: To search backwards, type ? (shift-/).
+
+ Note: Unlike Vim, N doesn't change the search direction.
+       N always goes backwards and n always goes forwards.
+
+
+
+
+=================================================================
+=                        CHAPTER 5 RECAP                        =
+=================================================================
+
+ * Type C-s to save position to the jumplist.
+   * Type C-i and C-o to go forward and backward in the jumplist.
+
+ * Type / to search forward in file, and ? to search backwards.
+   * Use n and N to cycle through search matches.
+
+
+
+
+
+
+
+
+
+
+
+
+
+=================================================================
+=                       6.1 JOINING LINES                       =
+=================================================================
+
+ Type J to join together lines in selection.
+
+ 1. Move the cursor to the line below marked -->.
+ 2. Type J thrice or 3J to join the sentence to one line.
+
+ --> This line sentence
+is spilling over
+onto other
+lines.
+
+ Note: J works on all lines in selection, so typing xxx or 3x to
+       select the lines and then a single J will work the same.
+
+
+
+
+
+
+=================================================================
+=                      6.2 INDENTING LINES                      =
+=================================================================
+
+ Type > to indent a line and < to outdent it.
+
+ 1. Move the cursor to the line below marked -->.
+ 2. Move down to the second line and type > to indent it.
+ 3. Move to the third line and type < to unindent it.
+
+ --> These lines
+    are indented
+         very poorly.
+
+     These lines
+     are indented
+     much better.
+
+
+
+
+
+=================================================================
+=                      6.3 OPENING LINES                        =
+=================================================================
+
+ Type o to add a newline and insert below the cursor.
+ Type O to add a newline and insert above the cursor.
+
+ 1. Move the cursor to the line below marked -->.
+ 2. Type o to open a line below and type your answer.
+
+ --> What is the best editor?
+
+
+
+
+
+
+
+
+
+
+
+=================================================================
+=                        CHAPTER 6 RECAP                        =
+=================================================================
+
+ * Type J to join lines within selection.
+
+ * Type > and < to indent and outdent selected lines.
+
+ * Use o and O to open lines.
+
+
+
+
+
+
+
+
+
+
+
+
+
 =================================================================
  This tutorial is still a work-in-progress.
  More sections are planned.
+
+
+