From 46bd48f7e902250dbccdea71ec6eb3888588133f Mon Sep 17 00:00:00 2001 From: Rory Nesbitt Date: Sun, 30 Jan 2022 12:53:01 +0000 Subject: [PATCH] docs(tutor): modify for Neovim rather than Vim (#17092) --- runtime/tutor/en/vim-01-beginner.tutor | 165 +++++++++++--------- runtime/tutor/en/vim-01-beginner.tutor.json | 50 +++--- 2 files changed, 117 insertions(+), 98 deletions(-) diff --git a/runtime/tutor/en/vim-01-beginner.tutor b/runtime/tutor/en/vim-01-beginner.tutor index 7c0c357e80..e256711e70 100644 --- a/runtime/tutor/en/vim-01-beginner.tutor +++ b/runtime/tutor/en/vim-01-beginner.tutor @@ -1,15 +1,14 @@ -# Welcome to the VIM Tutor +# Welcome to the Neovim Tutorial -Vim is a very powerful editor that has many commands, too many to explain in -a tutor such as this. This tutor is designed to describe enough of the -commands that you will be able to easily use Vim as an all-purpose editor. -It is IMPORTANT to remember that this tutor is set up to teach by use. That +Neovim is a very powerful editor that has many commands, too many to explain in +a tutorial such as this. This tutorial is designed to describe enough of the +commands that you will be able to easily use Neovim as an all-purpose editor. +It is IMPORTANT to remember that this tutorial is set up to teach by use. That means that you need to do the exercises to learn them properly. If you only read the text, you will soon forget what is most important! -For now, make sure that your Shift-Lock key is NOT depressed and press the -`j`{normal} key enough times to move the cursor so that Lesson 0 completely -fills the screen. +For now, make sure that your Caps-Lock is off and press the `j`{normal} key enough +times to move the cursor so that Lesson 0 completely fills the screen. # Lesson 0 @@ -20,12 +19,13 @@ pressing []() and then [u](u) will undo the latest change. This tutorial is interactive, and there are a few things you should know. - Type []() on links [like this](holy-grail ) to open the linked help section. - Or simply type [K](K) on any word to find its documentation! +- You can close this help window with `:q`{vim} - Sometimes you will be required to modify text like this here Once you have done the changes correctly, the ✗ sign at the left will change -to ✓. I imagine you can already see how neat Vim can be. ;) +to ✓. I imagine you can already see how neat Neovim can be. Other times, you'll be prompted to run a command (I'll explain this later): ~~~ cmd :help @@ -43,9 +43,9 @@ Now, move to the next lesson (use the `j`{normal} key to scroll down). ** To move the cursor, press the `h`, `j`, `k`, `l` keys as indicated. ** - ↑ - k Hint: The `h`{normal} key is at the left and moves left. - ← h l → The `l`{normal} key is at the right and moves right. + ↑ + k Hint: The `h`{normal} key is at the left and moves left. + ← h l → The `l`{normal} key is at the right and moves right. j The `j`{normal} key looks like a down arrow. ↓ @@ -60,11 +60,11 @@ NOTE: If you are ever unsure about something you typed, press to place you in Normal mode. Then retype the command you wanted. NOTE: The cursor keys should also work. But using hjkl you will be able to - move around much faster, once you get used to it. Really! + move around much faster, once you get used to it. -# Lesson 1.2: EXITING VIM +# Lesson 1.2: EXITING NEOVIM -!! NOTE: Before executing any of the steps below, read this entire lesson !! +!! NOTE: Before executing any of the steps below, read the entire lesson !! 1. Press the key (to make sure you are in Normal mode). @@ -72,10 +72,10 @@ NOTE: The cursor keys should also work. But using hjkl you will be able to `:q!`{vim} ``{normal}. - This exits the editor, DISCARDING any changes you have made. + This quits the editor, DISCARDING any changes you have made. - 3. Open vim and get back here by executing the command that got you into - this tutor. That might be: + 3. Open Neovim and get back here by executing the command that got you into + this tutorial. That might be: :Tutor @@ -104,9 +104,9 @@ The ccow jumpedd ovverr thhe mooon. 5. Now that the line is correct, go on to Lesson 1.4. -NOTE: As you go through this tutor, do not try to memorize everything, - your Vim vocabulary will expand with usage. Consider returning to - this tutor periodically for a refresher. +NOTE: As you go through this tutorial, do not try to memorize everything, + your Neovim vocabulary will expand with usage. Consider returning to + this tutorial periodically for a refresher. # Lesson 1.4: TEXT EDITING: INSERTION @@ -151,11 +151,11 @@ There is also some text missing here. # Lesson 1.6: EDITING A FILE -** Use `:wq`{vim} to save a file and exit. ** +** Use `:wq`{vim} to write a file and quit. ** -!! NOTE: Before executing any of the steps below, read this entire lesson !! +!! NOTE: Before executing any of the steps below, read the entire lesson !! - 1. Exit this tutor as you did in Lesson 1.2: `:q!`{vim} + 1. Exit this tutorial as you did in Lesson 1.2: `:q!`{vim} Or, if you have access to another terminal, do the following there. 2. At the shell prompt type this command: @@ -167,28 +167,28 @@ There is also some text missing here. 3. Insert and delete text as you learned in the previous lessons. - 4. Save the file with changes and exit Vim with: + 4. Save the file with changes and exit Neovim with: ~~~ cmd :wq ~~~ Note you'll need to press `` to execute the command. - 5. If you have quit vimtutor in step 1 restart the vimtutor and move down + 5. If you have quit this tutorial in step 1, restart and move down to the following summary. - 6. After reading the above steps and understanding them: do it. + 6. After reading and understanding the above steps: do them. # Lesson 1 SUMMARY 1. The cursor is moved using either the arrow keys or the hjkl keys. h (left) j (down) k (up) l (right) - 2. To start Vim from the shell prompt type: + 2. To start Neovim from the shell prompt type: ~~~ sh $ nvim FILENAME ~~~ - 3. To exit Vim type: ``{normal} `:q!`{vim} ``{normal} to trash all changes. - OR type: ``{normal} `:wq`{vim} ``{normal} to save the changes. + 3. To exit Neovim type: ``{normal} `:q!`{vim} ``{normal} to trash all changes. + OR type: ``{normal} `:wq`{vim} ``{normal} to save the changes. 4. To delete the character at the cursor type: `x`{normal} @@ -297,8 +297,11 @@ Due to the frequency of whole line deletion, the designers of Vi decided it would be easier to simply type two d's to delete a line. 1. Move the cursor to the second line in the phrase below. + 2. Type [dd](dd) to delete the line. + 3. Now move to the fourth line. + 4. Type `2dd`{normal} to delete two lines. 1) Roses are red, @@ -314,11 +317,17 @@ it would be easier to simply type two d's to delete a line. ** Press `u`{normal} to undo the last commands, `U`{normal} to fix a whole line. ** 1. Move the cursor to the line below marked ✗ and place it on the first error. + 2. Type `x`{normal} to delete the first unwanted character. + 3. Now type `u`{normal} to undo the last command executed. + 4. This time fix all the errors on the line using the `x`{normal} command. + 5. Now type a capital `U`{normal} to return the line to its original state. + 6. Now type `u`{normal} a few times to undo the `U`{normal} and preceding commands. + 7. Now type ``{normal} (Control + R) a few times to redo the commands. Fiix the errors oon thhis line and reeplace them witth undo. @@ -328,8 +337,11 @@ Fiix the errors oon thhis line and reeplace them witth undo. # Lesson 2 SUMMARY 1. To delete from the cursor up to the next word type: `dw`{normal} + 2. To delete from the cursor to the end of a line type: `d$`{normal} + 3. To delete a whole line type: `dd`{normal} + 4. To repeat a motion prepend it with a number: `2w`{normal} 5. The format for a change command is: @@ -356,7 +368,7 @@ Fiix the errors oon thhis line and reeplace them witth undo. 1. Move the cursor to the first ✓ line below. - 2. Type `dd`{normal} to delete the line and store it in a Vim register. + 2. Type `dd`{normal} to delete the line and store it in a Neovim register. 3. Move the cursor to the c) line, ABOVE where the deleted line should go. @@ -369,6 +381,8 @@ b) Violets are blue, c) Intelligence is learned, a) Roses are red, +NOTE: You can also put the text before the cursor with `P`{normal} (capital P) + # Lesson 3.2: THE REPLACE COMMAND ** Type `rx`{normal} to replace the character at the cursor with x. ** @@ -386,7 +400,7 @@ When this line was typed in, someone pressed some wrong keys! 5. Now move on to Lesson 3.3. -NOTE: Remember that you should be learning by doing, not memorization. +NOTE: Remember that you should be learning by doing, not memorizing. # Lesson 3.3: THE CHANGE OPERATOR @@ -439,7 +453,7 @@ NOTE: You can use the Backspace key to correct mistakes while typing. 3. The [change operator](c) allows you to change from the cursor to where the motion takes you. Type `ce`{normal} to change from the cursor to the - end of the word, `c$`{normal} to change to the end of a line. + end of the word, `c$`{normal} to change to the end of a line, etc. 4. The format for change is: @@ -452,7 +466,7 @@ Now go on to the next lesson. ** Type ``{normal} to show your location in a file and the file status. Type `G`{normal} to move to a line in the file. ** -NOTE: Read this entire lesson before executing any of the steps!! +NOTE: Read the entire lesson before executing any of these steps!! 1. Hold down the ``{normal} key and press `g`{normal}. We call this ``{normal}. A message will appear at the bottom of the page with the filename and @@ -535,8 +549,8 @@ Usually thee best time to see thee flowers is in thee spring. ~~~ cmd :#,#s/old/new/g ~~~ - where #,# are the line numbers of the range of lines where the - substitution is to be done. + where # are the line numbers of the range of lines where the + substitution is to be done (i.e., `1,3` means from line 1 to line 3, inclusive). Type ~~~ cmd @@ -551,6 +565,9 @@ Usually thee best time to see thee flowers is in thee spring. to find every occurrence in the whole file, with a prompt whether to substitute or not. +NOTE: You can also select the lines you want to substitute first using visual-mode. + This will be explained more in a future lesson. + # Lesson 4 SUMMARY 1. ``{normal} displays your location and the file status. @@ -603,11 +620,10 @@ Usually thee best time to see thee flowers is in thee spring. This will show you a listing of your directory, just as if you were at the shell prompt. -NOTE: It is possible to execute any external command this way, also with - arguments. +NOTE: It is possible to execute any external command this way, and you + can include arguments. -NOTE: All `:`{vim} commands must be finished by hitting ``{normal}. - From here on we will not always mention it. +NOTE: All `:`{vim} commands are executed when you press ``{normal}. # Lesson 5.2: MORE ON WRITING FILES @@ -624,11 +640,11 @@ NOTE: All `:`{vim} commands must be finished by hitting ``{normal}. ~~~ (where TEST is the filename you chose.) - 4. This saves the whole file (the Vim Tutor) under the name TEST. + 4. This saves the current file under the name TEST. To verify this, type `:!ls`{vim} again to see your directory. -NOTE: If you were to exit Vim and start it again with `nvim TEST`, the file - would be an exact copy of the tutor when you saved it. +NOTE: If you were to exit Neovim and start it again with `nvim TEST`, the file + would be an exact copy of the tutorial when you saved it. 5. Now remove the file by typing: ~~~ cmd @@ -659,7 +675,7 @@ NOTE: If you were to exit Vim and start it again with `nvim TEST`, the file before you press ``{normal}. - 5. Vim will write the selected lines to the file TEST. Use `:!ls`{vim} to see it. + 5. Neovim will write the selected lines to the file TEST. Use `:!ls`{vim} to see it. Do not remove it yet! We will use it in the next lesson. NOTE: Pressing [v](v) starts [Visual selection](visual-mode). You can move the cursor around to @@ -668,7 +684,7 @@ NOTE: Pressing [v](v) starts [Visual selection](visual-mode). You can move the c # Lesson 5.4: RETRIEVING AND MERGING FILES -** To insert the contents of a file, type `:r FILENAME`{vim}. ** +** To retrieve the contents of a file, type `:r FILENAME`{vim}. ** 1. Place the cursor just above this line. @@ -683,7 +699,7 @@ NOTE: After executing Step 2 you will see text from Lesson 5.3. Then move The file you retrieve is placed below the cursor line. 3. To verify that a file was retrieved, cursor back and notice that there - are now two copies of Lesson 5.3, the original and the file version. + are now two copies of Lesson 5.3, the original and the retrieved version. NOTE: You can also read the output of an external command. For example, @@ -699,7 +715,7 @@ NOTE: You can also read the output of an external command. For example, `:!ls`{vim} - shows a directory listing `:!rm FILENAME`{vim} - removes file FILENAME - 2. [:w](:w) FILENAME writes the current Vim file to disk with + 2. [:w](:w) FILENAME writes the current Neovim file to disk with name FILENAME. 3. [v](v) motion :w FILENAME saves the Visually selected lines in file @@ -768,11 +784,11 @@ Adding 123 to xxx gives you xxx. Adding 123 to 456 gives you 579. NOTE: Replace mode is like Insert mode, but every typed character - deletes an existing character. + replaces an existing character. # Lesson 6.4: COPY AND PASTE TEXT -** Use the `y`{normal} operator to copy text and `p`{normal} to paste it. ** +** Use the `y`{normal} operator to copy text and `p`{normal} to put it. ** 1. Go to the line marked with ✓ below and place the cursor after "a)". @@ -796,9 +812,13 @@ b) NOTE: you can use `y`{normal} as an operator: `yw`{normal} yanks one word. +NOTE: you can use `P`{normal} to put before the cursor, rather than after. + # Lesson 6.5: SET OPTION -** Set an option so a search or substitute ignores case. ** +** Set an option so search and substitute commands ignore case. ** + +There are many settings in Neovim that you can configure to suit your needs. 1. Search for 'ignore' by entering: `/ignore` Repeat several times by pressing `n`{normal}. @@ -820,7 +840,7 @@ NOTE: you can use `y`{normal} as an operator: `yw`{normal} yanks one word. ~~~ cmd :set noic ~~~ - 7. To toggle the value of a setting, prepend it with "inv": + 7. To invert the value of a setting, prepend it with "inv": ~~~ cmd :set invic ~~~ @@ -858,19 +878,18 @@ NOTE: If you want to ignore case for just one search command, use [\c](/\c) ~~~ cmd :set noic ~~~ - 8. Prepend "inv" to toggle an option: + 8. Prepend "inv" to invert an option: ~~~ cmd :set invic ~~~ # Lesson 7.1: GETTING HELP -** Use the on-line help system. ** +** Use the online help system. ** -Vim has a comprehensive on-line help system. +Neovim has a comprehensive online help system. To get started, try one of these three: - - press the ``{normal} key (if you have one) - press the ``{normal} key (if you have one) - type `:help`{vim} @@ -879,7 +898,7 @@ Type ``{normal} to jump from one window to another. Type `:q`{vim} to close the help window. You can find help on just about any subject, by giving an argument to the -":help" command. Try these (don't forget pressing ): +":help" command. Try these (don't forget to press ): ~~~ cmd :help w :help c_CTRL-D @@ -888,12 +907,12 @@ You can find help on just about any subject, by giving an argument to the ~~~ # Lesson 7.2: CREATE A STARTUP SCRIPT -** Enable Vim features. ** +** Enable Neovim features. ** -Vim has many more features than Vi, but most of them are disabled by -default. To start using more features you have to create a "vimrc" file. +Neovim is a very configurable editor. You can customise it any way you like. +To start using more features create an "init.vim" file. - 1. Start editing the "vimrc" file. + 1. Start editing the "init.vim" file. `:call mkdir(stdpath('config'),'p')`{vim} `:exe 'edit' stdpath('config').'/init.vim'`{vim} @@ -902,24 +921,24 @@ default. To start using more features you have to create a "vimrc" file. `:w`{vim} - You can add all your preferred settings to this "vimrc" file. - For more information type `:help vimrc-intro`{vim}. + You can add all your preferred settings to this "init.vim" file. + For more information type `:help init.vim`{vim}. # Lesson 7.3: COMPLETION ** Command line completion with ``{normal} and ``{normal}. ** - 1. Look what files exist in the directory: `:!ls`{vim} + 1. List the contents of the current directory: `:!ls`{vim} 2. Type the start of a command: `:e`{vim} - 3. Press ``{normal} and Vim will show a list of commands beginning with "e". + 3. Press ``{normal} and Neovim will show a list of commands beginning with "e". - 4. Press ``{normal} and Vim will complete the command name to ":edit". + 4. Press ``{normal} and Neovim will complete the command name to ":edit". 5. Now add a space and the start of an existing file name: `:edit FIL`{vim} - 6. Press ``{normal}. Vim will complete the name ("FIL" -> "FILE", if it is unique). + 6. Press ``{normal}. Neovim will complete the name ("FIL" -> "FILE", if it is unique). NOTE: Completion works for many commands. It is especially useful for `:help`{vim}. @@ -934,19 +953,18 @@ NOTE: Completion works for many commands. It is especially useful for `:help`{vi 4. Type `:q`{vim} to close the help window - 5. Create a vimrc startup script to keep your preferred settings. + 5. Create an init.vim startup script to keep your preferred settings. 6. While in command mode, press ``{normal} to see possible completions. Press ``{normal} to use one completion. # CONCLUSION -This was intended to give a brief overview of the Vim editor, just enough to -allow you to use the editor fairly easily. It is far from complete as Vim has +This was intended to give a brief overview of the Neovim editor, just enough to +allow you to use it fairly easily. It is far from complete as Neovim has many many more commands. Consult the help often. - -There are many resources online to learn more about vim. Here's a bunch of -them: +There are also countless great tutorials and videos to be found online. +Here's a bunch of them: - *Learn Vim Progressively*: http://yannesposito.com/Scratch/en/blog/Learn-Vim-Progressively/ @@ -964,7 +982,7 @@ them: https://github.com/mhinz/vim-galore If you prefer a book, *Practical Vim* by Drew Neil is recommended often -(the sequel, *Modern Vim*, includes material specific to nvim). +(the sequel, *Modern Vim*, includes material specific to Neovim). This tutorial was written by Michael C. Pierce and Robert K. Ware, Colorado School of Mines using ideas supplied by Charles Smith, Colorado State @@ -972,5 +990,6 @@ University. E-mail: bware@mines.colorado.edu. Modified for Vim by Bram Moolenaar. Modified for vim-tutor-mode by Felipe Morales. +Modified for Neovim by Rory Nesbitt. // vim: nowrap diff --git a/runtime/tutor/en/vim-01-beginner.tutor.json b/runtime/tutor/en/vim-01-beginner.tutor.json index e71ead976d..5dccb824e0 100644 --- a/runtime/tutor/en/vim-01-beginner.tutor.json +++ b/runtime/tutor/en/vim-01-beginner.tutor.json @@ -12,34 +12,34 @@ "232": "Somebody typed the end of this line twice.", "271": -1, "290": "This line of words is cleaned up.", - "304": -1, - "305": -1, - "306": -1, "307": -1, "308": -1, "309": -1, "310": -1, - "324": "Fix the errors on this line and replace them with undo.", - "367": -1, - "368": -1, - "369": -1, - "370": -1, - "384": "When this line was typed in, someone pressed some wrong keys!", - "385": "When this line was typed in, someone pressed some wrong keys!", - "405": "This line has a few words that need changing using the change operator.", - "406": "This line has a few words that need changing using the change operator.", - "426": "The end of this line needs to be corrected using the `c$` command.", - "427": "The end of this line needs to be corrected using the `c$` command.", - "490": -1, - "509": -1, - "532": "Usually the best time to see the flowers is in the spring.", - "725": -1, - "730": -1, - "746": "This line will allow you to practice appending text to a line.", - "747": "This line will allow you to practice appending text to a line.", - "767": "Adding 123 to 456 gives you 579.", - "768": "Adding 123 to 456 gives you 579.", - "794": "a) This is the first item.", - "795": "b) This is the second item." + "311": -1, + "312": -1, + "313": -1, + "333": "Fix the errors on this line and replace them with undo.", + "379": -1, + "380": -1, + "381": -1, + "382": -1, + "398": "When this line was typed in, someone pressed some wrong keys!", + "399": "When this line was typed in, someone pressed some wrong keys!", + "419": "This line has a few words that need changing using the change operator.", + "420": "This line has a few words that need changing using the change operator.", + "440": "The end of this line needs to be corrected using the `c$` command.", + "441": "The end of this line needs to be corrected using the `c$` command.", + "504": -1, + "523": -1, + "546": "Usually the best time to see the flowers is in the spring.", + "741": -1, + "746": -1, + "762": "This line will allow you to practice appending text to a line.", + "763": "This line will allow you to practice appending text to a line.", + "783": "Adding 123 to 456 gives you 579.", + "784": "Adding 123 to 456 gives you 579.", + "810": "a) This is the first item.", + "811": "b) This is the second item." } }