diff options
Diffstat (limited to 'runtime/doc/usr_02.txt')
| -rw-r--r-- | runtime/doc/usr_02.txt | 702 |
1 files changed, 702 insertions, 0 deletions
diff --git a/runtime/doc/usr_02.txt b/runtime/doc/usr_02.txt new file mode 100644 index 0000000..680a4e6 --- /dev/null +++ b/runtime/doc/usr_02.txt @@ -0,0 +1,702 @@ +*usr_02.txt* For Vim version 9.0. Last change: 2021 Apr 24 + + VIM USER MANUAL - by Bram Moolenaar + + The first steps in Vim + + +This chapter provides just enough information to edit a file with Vim. Not +well or fast, but you can edit. Take some time to practice with these +commands, they form the base for what follows. + +|02.1| Running Vim for the First Time +|02.2| Inserting text +|02.3| Moving around +|02.4| Deleting characters +|02.5| Undo and Redo +|02.6| Other editing commands +|02.7| Getting out +|02.8| Finding help + + Next chapter: |usr_03.txt| Moving around + Previous chapter: |usr_01.txt| About the manuals +Table of contents: |usr_toc.txt| + +============================================================================== +*02.1* Running Vim for the First Time + +To start Vim, enter this command: > + + gvim file.txt + +In UNIX you can type this at any command prompt. If you are running Microsoft +Windows, open a Command Prompt and enter the command. + In either case, Vim starts editing a file called file.txt. Because this +is a new file, you get a blank window. This is what your screen will look +like: + + +---------------------------------------+ + |# | + |~ | + |~ | + |~ | + |~ | + |"file.txt" [New file] | + +---------------------------------------+ + ('#' is the cursor position.) + +The tilde (~) lines indicate lines not in the file. In other words, when Vim +runs out of file to display, it displays tilde lines. At the bottom of the +screen, a message line indicates the file is named file.txt and shows that you +are creating a new file. The message information is temporary and other +information overwrites it. + + +THE VIM COMMAND + +The gvim command causes the editor to create a new window for editing. If you +use this command: > + + vim file.txt + +the editing occurs inside your command window. In other words, if you are +running inside an xterm, the editor uses your xterm window. If you are using +an MS-Windows command prompt window, the editing occurs inside this window. +The text in the window will look the same for both versions, but with gvim you +have extra features, like a menu bar. More about that later. + +============================================================================== +*02.2* Inserting text + +The Vim editor is a modal editor. That means that the editor behaves +differently, depending on which mode you are in. The two basic modes are +called Normal mode and Insert mode. In Normal mode the characters you type +are commands. In Insert mode the characters are inserted as text. + Since you have just started Vim it will be in Normal mode. To start Insert +mode you type the "i" command (i for Insert). Then you can enter +the text. It will be inserted into the file. Do not worry if you make +mistakes; you can correct them later. To enter the following programmer's +limerick, this is what you type: > + + iA very intelligent turtle + Found programming UNIX a hurdle + +After typing "turtle" you press the <Enter> key to start a new line. Finally +you press the <Esc> key to stop Insert mode and go back to Normal mode. You +now have two lines of text in your Vim window: + + +---------------------------------------+ + |A very intelligent turtle | + |Found programming UNIX a hurdle | + |~ | + |~ | + | | + +---------------------------------------+ + + +WHAT IS THE MODE? + +To be able to see what mode you are in, type this command: > + + :set showmode + +You will notice that when typing the colon Vim moves the cursor to the last +line of the window. That's where you type colon commands (commands that start +with a colon). Finish this command by pressing the <Enter> key (all commands +that start with a colon are finished this way). + Now, if you type the "i" command Vim will display --INSERT-- at the bottom +of the window. This indicates you are in Insert mode. + + +---------------------------------------+ + |A very intelligent turtle | + |Found programming UNIX a hurdle | + |~ | + |~ | + |-- INSERT -- | + +---------------------------------------+ + +If you press <Esc> to go back to Normal mode the last line will be made blank. + + +GETTING OUT OF TROUBLE + +One of the problems for Vim novices is mode confusion, which is caused by +forgetting which mode you are in or by accidentally typing a command that +switches modes. To get back to Normal mode, no matter what mode you are in, +press the <Esc> key. Sometimes you have to press it twice. If Vim beeps back +at you, you already are in Normal mode. + +============================================================================== +*02.3* Moving around + +After you return to Normal mode, you can move around by using these keys: + + h left *hjkl* + j down + k up + l right + +At first, it may appear that these commands were chosen at random. After all, +who ever heard of using l for right? But actually, there is a very good +reason for these choices: Moving the cursor is the most common thing you do in +an editor, and these keys are on the home row of your right hand. In other +words, these commands are placed where you can type them the fastest +(especially when you type with ten fingers). + + Note: + You can also move the cursor by using the arrow keys. If you do, + however, you greatly slow down your editing because to press the arrow + keys, you must move your hand from the text keys to the arrow keys. + Considering that you might be doing it hundreds of times an hour, this + can take a significant amount of time. + Also, there are keyboards which do not have arrow keys, or which + locate them in unusual places; therefore, knowing the use of the hjkl + keys helps in those situations. + +One way to remember these commands is that h is on the left, l is on the +right and j points down. In a picture: > + + k + h l + j + +The best way to learn these commands is by using them. Use the "i" command to +insert some more lines of text. Then use the hjkl keys to move around and +insert a word somewhere. Don't forget to press <Esc> to go back to Normal +mode. The |vimtutor| is also a nice way to learn by doing. + +For Japanese users, Hiroshi Iwatani suggested using this: + + Komsomolsk + ^ + | + Huan Ho <--- ---> Los Angeles + (Yellow river) | + v + Java (the island, not the programming language) + +============================================================================== +*02.4* Deleting characters + +To delete a character, move the cursor over it and type "x". (This is a +throwback to the old days of the typewriter, when you deleted things by typing +xxxx over them.) Move the cursor to the beginning of the first line, for +example, and type xxxxxxx (seven x's) to delete "A very ". The result should +look like this: + + +---------------------------------------+ + |intelligent turtle | + |Found programming UNIX a hurdle | + |~ | + |~ | + | | + +---------------------------------------+ + +Now you can insert new text, for example by typing: > + + iA young <Esc> + +This begins an insert (the i), inserts the words "A young", and then exits +insert mode (the final <Esc>). The result: + + +---------------------------------------+ + |A young intelligent turtle | + |Found programming UNIX a hurdle | + |~ | + |~ | + | | + +---------------------------------------+ + + +DELETING A LINE + +To delete a whole line use the "dd" command. The following line will +then move up to fill the gap: + + +---------------------------------------+ + |Found programming UNIX a hurdle | + |~ | + |~ | + |~ | + | | + +---------------------------------------+ + + +DELETING A LINE BREAK + +In Vim you can join two lines together, which means that the line break +between them is deleted. The "J" command does this. + Take these two lines: + + A young intelligent ~ + turtle ~ + +Move the cursor to the first line and press "J": + + A young intelligent turtle ~ + +============================================================================== +*02.5* Undo and Redo + +Suppose you delete too much. Well, you can type it in again, but an easier +way exists. The "u" command undoes the last edit. Take a look at this in +action: After using "dd" to delete the first line, "u" brings it back. + Another one: Move the cursor to the A in the first line: + + A young intelligent turtle ~ + +Now type xxxxxxx to delete "A young". The result is as follows: + + intelligent turtle ~ + +Type "u" to undo the last delete. That delete removed the g, so the undo +restores the character. + + g intelligent turtle ~ + +The next "u" command restores the next-to-last character deleted: + + ng intelligent turtle ~ + +The next "u" command gives you the u, and so on: + + ung intelligent turtle ~ + oung intelligent turtle ~ + young intelligent turtle ~ + young intelligent turtle ~ + A young intelligent turtle ~ + + Note: + If you type "u" twice, and the result is that you get the same text + back, you have Vim configured to work Vi compatible. Look here to fix + this: |not-compatible|. + This text assumes you work "The Vim Way". You might prefer to use + the good old Vi way, but you will have to watch out for small + differences in the text then. + + +REDO + +If you undo too many times, you can press CTRL-R (redo) to reverse the +preceding command. In other words, it undoes the undo. To see this in +action, press CTRL-R twice. The character A and the space after it disappear: + + young intelligent turtle ~ + +There's a special version of the undo command, the "U" (undo line) command. +The undo line command undoes all the changes made on the last line that was +edited. Typing this command twice cancels the preceding "U". + + A very intelligent turtle ~ + xxxx Delete very + + A intelligent turtle ~ + xxxxxx Delete turtle + + A intelligent ~ + Restore line with "U" + A very intelligent turtle ~ + Undo "U" with "u" + A intelligent ~ + +The "U" command is a change by itself, which the "u" command undoes and CTRL-R +redoes. This might be a bit confusing. Don't worry, with "u" and CTRL-R you +can go to any of the situations you had. More about that in section |32.2|. + +============================================================================== +*02.6* Other editing commands + +Vim has a large number of commands to change the text. See |Q_in| and below. +Here are a few often used ones. + + +APPENDING + +The "i" command inserts a character before the character under the cursor. +That works fine; but what happens if you want to add stuff to the end of the +line? For that you need to insert text after the cursor. This is done with +the "a" (append) command. + For example, to change the line + + and that's not saying much for the turtle. ~ +to + and that's not saying much for the turtle!!! ~ + +move the cursor over to the dot at the end of the line. Then type "x" to +delete the period. The cursor is now positioned at the end of the line on the +e in turtle. Now type > + + a!!!<Esc> + +to append three exclamation points after the e in turtle: + + and that's not saying much for the turtle!!! ~ + + +OPENING UP A NEW LINE + +The "o" command creates a new, empty line below the cursor and puts Vim in +Insert mode. Then you can type the text for the new line. + Suppose the cursor is somewhere in the first of these two lines: + + A very intelligent turtle ~ + Found programming UNIX a hurdle ~ + +If you now use the "o" command and type new text: > + + oThat liked using Vim<Esc> + +The result is: + + A very intelligent turtle ~ + That liked using Vim ~ + Found programming UNIX a hurdle ~ + +The "O" command (uppercase) opens a line above the cursor. + + +USING A COUNT + +Suppose you want to move up nine lines. You can type "kkkkkkkkk" or you can +enter the command "9k". In fact, you can precede many commands with a number. +Earlier in this chapter, for instance, you added three exclamation points to +the end of a line by typing "a!!!<Esc>". Another way to do this is to use the +command "3a!<Esc>". The count of 3 tells the command that follows to triple +its effect. Similarly, to delete three characters, use the command "3x". The +count always comes before the command it applies to. + +============================================================================== +*02.7* Getting out + +To exit, use the "ZZ" command. This command writes the file and exits. + + Note: + Unlike many other editors, Vim does not automatically make a backup + file. If you type "ZZ", your changes are committed and there's no + turning back. You can configure the Vim editor to produce backup + files; see |07.4|. + + +DISCARDING CHANGES + +Sometimes you will make a sequence of changes and suddenly realize you were +better off before you started. Not to worry; Vim has a +quit-and-throw-things-away command. It is: > + + :q! + +Don't forget to press <Enter> to finish the command. + +For those of you interested in the details, the three parts of this command +are the colon (:), which enters Command-line mode; the q command, which tells +the editor to quit; and the override command modifier (!). + The override command modifier is needed because Vim is reluctant to throw +away changes. If you were to just type ":q", Vim would display an error +message and refuse to exit: + + E37: No write since last change (use ! to override) ~ + +By specifying the override, you are in effect telling Vim, "I know that what +I'm doing looks stupid, but I really want to do this." + +If you want to continue editing with Vim: The ":e!" command reloads the +original version of the file. + +============================================================================== +*02.8* Finding help + +Everything you always wanted to know can be found in the Vim help files. +Don't be afraid to ask! + +If you know what you are looking for, it is usually easier to search for it +using the help system, instead of using Google. Because the subjects follow +a certain style guide. + +Also the help has the advantage of belonging to your particular Vim version. +You won't see help for commands added later. These would not work for you. + +To get generic help use this command: > + + :help + +You could also use the first function key <F1>. If your keyboard has a <Help> +key it might work as well. + If you don't supply a subject, ":help" displays the general help window. +The creators of Vim did something very clever (or very lazy) with the help +system: They made the help window a normal editing window. You can use all +the normal Vim commands to move through the help information. Therefore h, j, +k, and l move left, down, up and right. + To get out of the help window, use the same command you use to get out of +the editor: "ZZ". This will only close the help window, not exit Vim. + +As you read the help text, you will notice some text enclosed in vertical bars +(for example, |help|). This indicates a hyperlink. If you position the +cursor anywhere between the bars and press CTRL-] (jump to tag), the help +system takes you to the indicated subject. (For reasons not discussed here, +the Vim terminology for a hyperlink is tag. So CTRL-] jumps to the location +of the tag given by the word under the cursor.) + After a few jumps, you might want to go back. CTRL-T (pop tag) takes you +back to the preceding position. CTRL-O (jump to older position) also works +nicely here. + At the top of the help screen, there is the notation *help.txt*. This name +between "*" characters is used by the help system to define a tag (hyperlink +destination). + See |29.1| for details about using tags. + +To get help on a given subject, use the following command: > + + :help {subject} + +To get help on the "x" command, for example, enter the following: > + + :help x + +To find out how to delete text, use this command: > + + :help deleting + +To get a complete index of all Vim commands, use the following command: > + + :help index + +When you need to get help for a control character command (for example, +CTRL-A), you need to spell it with the prefix "CTRL-". > + + :help CTRL-A + +The Vim editor has many different modes. By default, the help system displays +the normal-mode commands. For example, the following command displays help +for the normal-mode CTRL-H command: > + + :help CTRL-H + +To identify other modes, use a mode prefix. If you want the help for the +insert-mode version of a command, use "i_". For CTRL-H this gives you the +following command: > + + :help i_CTRL-H + +When you start the Vim editor, you can use several command-line arguments. +These all begin with a dash (-). To find what the -t argument does, for +example, use the command: > + + :help -t + +The Vim editor has a number of options that enable you to configure and +customize the editor. If you want help for an option, you need to enclose it +in single quotation marks. To find out what the 'number' option does, for +example, use the following command: > + + :help 'number' + +The table with all mode prefixes can be found below: |help-summary|. + +Special keys are enclosed in angle brackets. To find help on the up-arrow key +in Insert mode, for instance, use this command: > + + :help i_<Up> + +If you see an error message that you don't understand, for example: + + E37: No write since last change (use ! to override) ~ + +You can use the error ID at the start to find help about it: > + + :help E37 + + +Summary: *help-summary* > + +1) Use Ctrl-D after typing a topic and let Vim show all available topics. + Or press Tab to complete: > + :help some<Tab> +< More information on how to use the help: > + :help helphelp + +2) Follow the links in bars to related help. You can go from the detailed + help to the user documentation, which describes certain commands more from + a user perspective and less detailed. E.g. after: > + :help pattern.txt +< You can see the user guide topics |03.9| and |usr_27.txt| in the + introduction. + +3) Options are enclosed in single apostrophes. To go to the help topic for the + list option: > + :help 'list' +< If you only know you are looking for a certain option, you can also do: > + :help options.txt +< to open the help page which describes all option handling and then search + using regular expressions, e.g. textwidth. + Certain options have their own namespace, e.g.: > + :help cpo-<letter> +< for the corresponding flag of the 'cpoptions' settings, substitute <letter> + by a specific flag, e.g.: > + :help cpo-; +< And for the 'guioptions' flags: > + :help go-<letter> + +4) Normal mode commands do not have a prefix. To go to the help page for the + "gt" command: > + :help gt + +5) Insert mode commands start with i_. Help for deleting a word: > + :help i_CTRL-W + +6) Visual mode commands start with v_. Help for jumping to the other side of + the Visual area: > + :help v_o + +7) Command line editing and arguments start with c_. Help for using the + command argument %: > + :help c_% + +8) Ex-commands always start with ":", so to go to the ":s" command help: > + :help :s + +9) Commands specifically for debugging start with ">". To go to the help + for the "cont" debug command: > + :help >cont + +10) Key combinations. They usually start with a single letter indicating + the mode for which they can be used. E.g.: > + :help i_CTRL-X +< takes you to the family of CTRL-X commands for insert mode which can be + used to auto-complete different things. Note, that certain keys will + always be written the same, e.g. Control will always be CTRL. + For normal mode commands there is no prefix and the topic is available at + :h CTRL-<Letter>. E.g. > + :help CTRL-W +< In contrast > + :help c_CTRL-R +< will describe what the CTRL-R does when entering commands in the Command + line and > + :help v_CTRL-A +< talks about incrementing numbers in visual mode and > + :help g_CTRL-A +< talks about the "g<C-A>" command (e.g. you have to press "g" then + <CTRL-A>). Here the "g" stands for the normal command "g" which always + expects a second key before doing something similar to the commands + starting with "z". + +11) Regexp items always start with /. So to get help for the "\+" quantifier + in Vim regexes: > + :help /\+ +< If you need to know everything about regular expressions, start reading + at: > + :help pattern.txt + +12) Registers always start with "quote". To find out about the special ":" + register: > + :help quote: + +13) Vim script is available at > + :help eval.txt +< Certain aspects of the language are available at :h expr-X where "X" is a + single letter. E.g. > + :help expr-! +< will take you to the topic describing the "!" (Not) operator for Vim + script. + Also important is > + :help function-list +< to find a short description of all functions available. Help topics for + Vim script functions always include the "()", so: > + :help append() +< talks about the append Vim script function rather than how to append text + in the current buffer. + +14) Mappings are talked about in the help page :h |map.txt|. Use > + :help mapmode-i +< to find out about the |:imap| command. Also use :map-topic + to find out about certain subtopics particular for mappings. e.g: > + :help :map-local +< for buffer-local mappings or > + :help map-bar +< for how the '|' is handled in mappings. + +15) Command definitions are talked about :h command-topic, so use > + :help command-bar +< to find out about the '!' argument for custom commands. + +16) Window management commands always start with CTRL-W, so you find the + corresponding help at :h CTRL-W_letter. E.g. > + :help CTRL-W_p +< for moving the previous accessed window. You can also access > + :help windows.txt +< and read your way through if you are looking for window handling + commands. + +17) Use |:helpgrep| to search in all help pages (and also of any installed + plugins). See |:helpgrep| for how to use it. + To search for a topic: > + :helpgrep topic +< This takes you to the first match. To go to the next one: > + :cnext +< All matches are available in the quickfix window which can be opened + with: > + :copen +< Move around to the match you like and press Enter to jump to that help. + +18) The user manual. This describes help topics for beginners in a rather + friendly way. Start at |usr_toc.txt| to find the table of content (as you + might have guessed): > + :help usr_toc.txt +< Skim over the contents to find interesting topics. The "Digraphs" and + "Entering special characters" items are in chapter 24, so to go to that + particular help page: > + :help usr_24.txt +< Also if you want to access a certain chapter in the help, the chapter + number can be accessed directly like this: > + :help 10.1 +< which goes to chapter 10.1 in |usr_10.txt| and talks about recording + macros. + +19) Highlighting groups. Always start with hl-groupname. E.g. > + :help hl-WarningMsg +< talks about the WarningMsg highlighting group. + +20) Syntax highlighting is namespaced to :syn-topic. E.g. > + :help :syn-conceal +< talks about the conceal argument for the ":syn" command. + +21) Quickfix commands usually start with :c while location list commands + usually start with :l + +22) Autocommand events can be found by their name: > + :help BufWinLeave +< To see all possible events: > + :help autocommand-events + +23) Command-line switches always start with "-". So for the help of the -f + command switch of Vim use: > + :help -f + +24) Optional features always start with "+". To find out about the + conceal feature use: > + :help +conceal + +25) Documentation for included filetype specific functionality is usually + available in the form ft-<filetype>-<functionality>. So > + :help ft-c-syntax +< talks about the C syntax file and the option it provides. Sometimes, + additional sections for omni completion > + :help ft-php-omni +< or filetype plugins > + :help ft-tex-plugin +< are available. + +26) Error and Warning codes can be looked up directly in the help. So > + :help E297 +< takes you exactly to the description of the swap error message and > + :help W10 +< talks about the warning "Changing a readonly file". + Sometimes, however, those error codes are not described, but rather are + listed at the Vim command that usually causes this. So: > + :help E128 +< takes you to the |:function| command + + +============================================================================== + +Next chapter: |usr_03.txt| Moving around + +Copyright: see |manual-copyright| vim:tw=78:ts=8:noet:ft=help:norl: |