Tutorial for Helix akin to `vimtutor` (#537)

* Create `docs/tutor.txt` * Create `EXITING HELIX` and `DELETION` sections * Create Insert mode, saving, and recap sections * Create `MOTIONS AND SELECTIONS` section * Add additional notes to `SAVING A FILE` section * Remove extra blank lines in `SAVING A FILE` section * Move `tutor.txt` to `runtime/` * Add WIP message to end of tutorial
3 years ago · 9a39a10ddd
parent 8364ceca81
commit 9a39a10ddd
1 changed files with 233 additions and 0 deletions
--- a/runtime/tutor.txt
+++ b/runtime/tutor.txt
@ -0,0 +1,233 @@
+                  _   _                 __    __
+                 | | | |         _      \ \  / /
+                 | |_| |   ___  | | (_)  \ \/ /
+                 |  _  |  / _ \ | |  _    )  (
+                 | | | | |  __/ | | | |  / /\ \
+                 |_| |_|  \___| |_| |_| /_/  \_\
+
+                 A post-modern modal text editor.
+_________________________________________________________________
+
+ Welcome to the Helix editor! Helix is different from editors
+ 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
+ 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
+ caps-lock key is not pressed and hold the j key until you reach
+ the first lesson.
+
+
+
+=================================================================
+=                     BASIC CURSOR MOVEMENT                     =
+=================================================================
+
+          ↑
+          k       * h is on the left
+      ← h   l →   * l is on the right
+          j       * j looks like a down arrow
+          ↓
+
+ The cursor can be moved using the h, j, k, l keys, as shown
+ above. The cursor/arrow keys will also work, but it is faster
+ to use the hjkl keys as they are closer to the other keys you
+ will be using. Try moving around to get a feel for hjkl.
+ Once you're ready, hold j to continue to the next lesson.
+
+
+
+
+
+
+
+
+=================================================================
+=                        EXITING HELIX                          =
+=================================================================
+
+ 1. Press the : key 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.
+
+ Note: The quit command will fail if there are unsaved changes.
+       To force quit and DISCARD these changes, use q! or quit!.
+       You will learn how to save files later.
+
+ To exit command mode without entering a command, press <ESC>.
+
+ Now, move on to the next lesson.
+
+
+
+
+
+
+
+
+=================================================================
+=                           DELETION                            =
+=================================================================
+
+ Press 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
+    delete it.
+
+ --> Thhiss senttencee haass exxtra charracterss.
+
+ Once the sentence is correct, move on to the next lesson.
+
+
+
+
+
+
+
+
+
+
+=================================================================
+=                          INSERT MODE                          =
+=================================================================
+
+ Press 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.
+ 3. Enter the missing text.
+ 4. Press <ESC> to exit Insert mode and return to Normal mode.
+ 5. Repeat until the line matches the line below it.
+
+ --> Th stce misg so.
+     This sentence is missing some text.
+
+ Note: If you want to move the cursor while in Insert mode,
+       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'.
+
+
+=================================================================
+=                      MORE ON INSERT MODE                      =
+=================================================================
+
+ As you saw, you can press 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.
+
+ Common examples of insertion commands include:
+   i - Insert before the selection.
+   a - Insert after the selection. (a means "append")
+   I - Insert at the start of the line.
+   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
+    the line and you will be able to type.
+ 3. Type the text necessary to match the line below.
+
+ --> This sentence is miss
+     This sentence is missing some text.
+
+
+=================================================================
+=                         SAVING A FILE                         =
+=================================================================
+
+ Use :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.
+
+ You can also use 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.
+ Note: If there are any unsaved changes to a file, a plus [+]
+       will appear next to the file name in the status bar.
+
+
+
+
+=================================================================
+=                             RECAP                             =
+=================================================================
+
+ * Use the h,j,k,l keys to move the cursor.
+
+ * Press : 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.
+
+ * Press i to enter Insert mode and type text. Press <ESC> to
+   return to Normal mode.
+
+
+
+
+
+
+=================================================================
+=                    MOTIONS AND SELECTIONS                     =
+=================================================================
+
+ Press 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
+ single-character selection.
+
+ 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.
+ 5. Repeat for all extra words in the line.
+
+ --> This sentence pencil has vacuum extra words in the it.
+
+
+
+
+
+
+=================================================================
+=                        MORE ON MOTIONS                        =
+=================================================================
+
+ As you saw, pressing 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.
+
+ Some common motions include:
+   w - Move forward to before the beginning of the next word.
+   e - Move forward to the end of the current word.
+   b - Move backward to the beginning of the current word.
+
+ The w,e,b motions also have counterparts - W,E,B - which
+ traverse WORDS instead of words. WORDS are only separated by
+ whitespace, whereas words can be separated by other characters
+ in addition to whitespace.
+
+ All of these motions select the text they traverse.
+
+
+
+
+=================================================================
+ This tutorial is still a work-in-progress.
+ More sections are planned.