From 9a39a10ddd5d8cf87e4ecedd54c4f4e06735ba33 Mon Sep 17 00:00:00 2001 From: Omnikar Date: Thu, 12 Aug 2021 21:13:17 -0400 Subject: [PATCH] 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 --- runtime/tutor.txt | 233 ++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 233 insertions(+) create mode 100644 runtime/tutor.txt diff --git a/runtime/tutor.txt b/runtime/tutor.txt new file mode 100644 index 000000000000..07b888848cb9 --- /dev/null +++ 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 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 . + + 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 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 ( + 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 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 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.