Fix typo in debug message string
[MacVim.git] / runtime / doc / usr_24.txt
blob37592a098d5d2c1ed04b43d4c85ca6f3170713ac
1 *usr_24.txt*    For Vim version 7.2.  Last change: 2006 Jul 23
3                      VIM USER MANUAL - by Bram Moolenaar
5                              Inserting quickly
8 When entering text, Vim offers various ways to reduce the number of keystrokes
9 and avoid typing mistakes.  Use Insert mode completion to repeat previously
10 typed words.  Abbreviate long words to short ones.  Type characters that
11 aren't on your keyboard.
13 |24.1|  Making corrections
14 |24.2|  Showing matches
15 |24.3|  Completion
16 |24.4|  Repeating an insert
17 |24.5|  Copying from another line
18 |24.6|  Inserting a register
19 |24.7|  Abbreviations
20 |24.8|  Entering special characters
21 |24.9|  Digraphs
22 |24.10| Normal mode commands
24      Next chapter: |usr_25.txt|  Editing formatted text
25  Previous chapter: |usr_23.txt|  Editing other files
26 Table of contents: |usr_toc.txt|
28 ==============================================================================
29 *24.1*  Making corrections
31 The <BS> key was already mentioned.  It deletes the character just before the
32 cursor.  The <Del> key does the same for the character under (after) the
33 cursor.
34    When you typed a whole word wrong, use CTRL-W:
36         The horse had fallen to the sky ~
37                                        CTRL-W
38         The horse had fallen to the ~
40 If you really messed up a line and want to start over, use CTRL-U to delete
41 it.  This keeps the text after the cursor and the indent.  Only the text from
42 the first non-blank to the cursor is deleted.  With the cursor on the "f" of
43 "fallen" in the next line pressing CTRL-U does this:
45         The horse had fallen to the ~
46                       CTRL-U
47         fallen to the ~
49 When you spot a mistake a few words back, you need to move the cursor there to
50 correct it.  For example, you typed this:
52         The horse had follen to the ground ~
54 You need to change "follen" to "fallen".  With the cursor at the end, you
55 would type this to correct it: >
57                                         <Esc>4blraA
59 <       get out of Insert mode          <Esc>
60         four words back                      4b
61         move on top of the "o"                 l
62         replace with "a"                        ra
63         restart Insert mode                       A
65 Another way to do this: >
67                 <C-Left><C-Left><C-Left><C-Left><Right><Del>a<End>
69 <       four words back              <C-Left><C-Left><C-Left><C-Left>
70         move on top of the "o"                  <Right>
71         delete the "o"                                 <Del>
72         insert an "a"                                       a
73         go to end of the line                                <End>
75 This uses special keys to move around, while remaining in Insert mode.  This
76 resembles what you would do in a modeless editor.  It's easier to remember,
77 but takes more time (you have to move your hand from the letters to the cursor
78 keys, and the <End> key is hard to press without looking at the keyboard).
79    These special keys are most useful when writing a mapping that doesn't
80 leave Insert mode.  The extra typing doesn't matter then.
81    An overview of the keys you can use in Insert mode:
83         <C-Home>        to start of the file
84         <PageUp>        a whole screenful up
85         <Home>          to start of line
86         <S-Left>        one word left
87         <C-Left>        one word left
88         <S-Right>       one word right
89         <C-Right>       one word right
90         <End>           to end of the line
91         <PageDown>      a whole screenful down
92         <C-End>         to end of the file
94 There are a few more, see |ins-special-special|.
96 ==============================================================================
97 *24.2*  Showing matches
99 When you type a ) it would be nice to see with which ( it matches.  To make
100 Vim do that use this command: >
102         :set showmatch
104 When you now type a text like "(example)", as soon as you type the ) Vim will
105 briefly move the cursor to the matching (, keep it there for half a second,
106 and move back to where you were typing.
107    In case there is no matching (, Vim will beep.  Then you know that you
108 might have forgotten the ( somewhere, or typed a ) too many.
109    The match will also be shown for [] and {} pairs.  You don't have to wait
110 with typing the next character, as soon as Vim sees it the cursor will move
111 back and inserting continues as before.
112    You can change the time Vim waits with the 'matchtime' option.  For
113 example, to make Vim wait one and a half second: >
115         :set matchtime=15
117 The time is specified in tenths of a second.
119 ==============================================================================
120 *24.3*  Completion
122 Vim can automatically complete words on insertion.  You type the first part of
123 a word, press CTRL-P, and Vim guesses the rest.
124    Suppose, for example, that you are creating a C program and want to type in
125 the following:
127         total = ch_array[0] + ch_array[1] + ch_array[2]; ~
129 You start by entering the following:
131         total = ch_array[0] + ch_ ~
133 At this point, you tell Vim to complete the word using the command CTRL-P.
134 Vim searches for a word that starts with what's in front of the cursor.  In
135 this case, it is "ch_", which matches with the word ch_array.  So typing
136 CTRL-P gives you the following:
138         total = ch_array[0] + ch_array ~
140 After a little more typing, you get this (ending in a space):
142         total = ch_array[0] + ch_array[1] +  ~
144 If you now type CTRL-P Vim will search again for a word that completes the
145 word before the cursor.  Since there is nothing in front of the cursor, it
146 finds the first word backwards, which is "ch_array".  Typing CTRL-P again
147 gives you the next word that matches, in this case "total".  A third CTRL-P
148 searches further back.  If there is nothing else, it causes the editor to run
149 out of words, so it returns to the original text, which is nothing.  A fourth
150 CTRL-P causes the editor to start over again with "ch_array".
152 To search forward, use CTRL-N.  Since the search wraps around the end of the
153 file, CTRL-N and CTRL-P will find the same matches, but in a different
154 sequence.  Hint: CTRL-N is Next-match and CTRL-P is Previous-match.
156 The Vim editor goes through a lot of effort to find words to complete.  By
157 default, it searches the following places:
159         1. Current file
160         2. Files in other windows
161         3. Other loaded files (hidden buffers)
162         4. Files which are not loaded (inactive buffers)
163         5. Tag files
164         6. All files #included by the current file
167 OPTIONS
169 You can customize the search order with the 'complete' option.
171 The 'ignorecase' option is used.  When it is set, case differences are ignored
172 when searching for matches.
174 A special option for completion is 'infercase'.  This is useful to find
175 matches while ignoring case ('ignorecase' must be set) but still using the
176 case of the word typed so far.  Thus if you type "For" and Vim finds a match
177 "fortunately", it will result in "Fortunately".
180 COMPLETING SPECIFIC ITEMS
182 If you know what you are looking for, you can use these commands to complete
183 with a certain type of item:
185         CTRL-X CTRL-F           file names
186         CTRL-X CTRL-L           whole lines
187         CTRL-X CTRL-D           macro definitions (also in included files)
188         CTRL-X CTRL-I           current and included files
189         CTRL-X CTRL-K           words from a dictionary
190         CTRL-X CTRL-T           words from a thesaurus
191         CTRL-X CTRL-]           tags
192         CTRL-X CTRL-V           Vim command line
194 After each of them CTRL-N can be used to find the next match, CTRL-P to find
195 the previous match.
196    More information for each of these commands here: |ins-completion|.
199 COMPLETING FILE NAMES
201 Let's take CTRL-X CTRL-F as an example.  This will find file names.  It scans
202 the current directory for files and displays each one that matches the word in
203 front of the cursor.
204    Suppose, for example, that you have the following files in the current
205 directory:
207         main.c  sub_count.c  sub_done.c  sub_exit.c
209 Now enter Insert mode and start typing:
211         The exit code is in the file sub ~
213 At this point, you enter the command CTRL-X CTRL-F.  Vim now completes the
214 current word "sub" by looking at the files in the current directory.  The
215 first match is sub_count.c.  This is not the one you want, so you match the
216 next file by typing CTRL-N.  This match is sub_done.c.  Typing CTRL-N again
217 takes you to sub_exit.c.  The results:
219         The exit code is in the file sub_exit.c ~
221 If the file name starts with / (Unix) or C:\ (MS-Windows) you can find all
222 files in the file system.  For example, type "/u" and CTRL-X CTRL-F.  This
223 will match "/usr" (this is on Unix):
225         the file is found in /usr/ ~
227 If you now press CTRL-N you go back to "/u".  Instead, to accept the "/usr/"
228 and go one directory level deeper, use CTRL-X CTRL-F again:
230         the file is found in /usr/X11R6/ ~
232 The results depend on what is found in your file system, of course.  The
233 matches are sorted alphabetically.
236 COMPLETING IN SOURCE CODE
238 Source code files are well structured.  That makes it possible to do
239 completion in an intelligent way.  In Vim this is called Omni completion.  In
240 some other editors it's called intellisense, but that is a trademark.
242 The key to Omni completion is CTRL-X CTRL-O.  Obviously the O stands for Omni
243 here, so that you can remember it easier.  Let's use an example for editing C
244 source:
246         { ~
247             struct foo *p; ~
248             p-> ~
250 The cursor is after "p->".  Now type CTRL-X CTRL-O.  Vim will offer you a list
251 of alternatives, which are the items that "struct foo" contains.  That is
252 quite different from using CTRL-P, which would complete any word, while only
253 members of "struct foo" are valid here.
255 For Omni completion to work you may need to do some setup.  At least make sure
256 filetype plugins are enabled.  Your vimrc file should contain a line like
257 this: >
258         filetype plugin on
259 Or: >
260         filetype plugin indent on
262 For C code you need to create a tags file and set the 'tags' option.  That is
263 explained |ft-c-omni|.  For other filetypes you may need to do something
264 similar, look below |compl-omni-filetypes|.  It only works for specific
265 filetypes.  Check the value of the 'omnifunc' option to find out if it would
266 work.
268 ==============================================================================
269 *24.4*  Repeating an insert
271 If you press CTRL-A, the editor inserts the text you typed the last time you
272 were in Insert mode.
273    Assume, for example, that you have a file that begins with the following:
275         "file.h" ~
276         /* Main program begins */ ~
278 You edit this file by inserting "#include " at the beginning of the first
279 line:
281         #include "file.h" ~
282         /* Main program begins */ ~
284 You go down to the beginning of the next line using the commands "j^".  You
285 now start to insert a new "#include" line.  So you type: >
287         i CTRL-A
289 The result is as follows:
291         #include "file.h" ~
292         #include /* Main program begins */ ~
294 The "#include " was inserted because CTRL-A inserts the text of the previous
295 insert.  Now you type  "main.h"<Enter>  to finish the line:
298         #include "file.h" ~
299         #include "main.h" ~
300         /* Main program begins */ ~
302 The CTRL-@ command does a CTRL-A and then exits Insert mode.  That's a quick
303 way of doing exactly the same insertion again.
305 ==============================================================================
306 *24.5*  Copying from another line
308 The CTRL-Y command inserts the character above the cursor.  This is useful
309 when you are duplicating a previous line.  For example, you have this line of
310 C code:
312         b_array[i]->s_next = a_array[i]->s_next; ~
314 Now you need to type the same line, but with "s_prev" instead of "s_next".
315 Start the new line, and press CTRL-Y 14 times, until you are at the "n" of
316 "next":
318         b_array[i]->s_next = a_array[i]->s_next; ~
319         b_array[i]->s_ ~
321 Now you type "prev":
323         b_array[i]->s_next = a_array[i]->s_next; ~
324         b_array[i]->s_prev ~
326 Continue pressing CTRL-Y until the following "next":
328         b_array[i]->s_next = a_array[i]->s_next; ~
329         b_array[i]->s_prev = a_array[i]->s_ ~
331 Now type "prev;" to finish it off.
333 The CTRL-E command acts like CTRL-Y except it inserts the character below the
334 cursor.
336 ==============================================================================
337 *24.6*  Inserting a register
339 The command CTRL-R {register} inserts the contents of the register.  This is
340 useful to avoid having to type a long word.  For example, you need to type
341 this:
343         r = VeryLongFunction(a) + VeryLongFunction(b) + VeryLongFunction(c) ~
345 The function name is defined in a different file.  Edit that file and move the
346 cursor on top of the function name there, and yank it into register v: >
348         "vyiw
350 "v is the register specification, "yiw" is yank-inner-word.  Now edit the file
351 where the new line is to be inserted, and type the first letters:
353         r = ~
355 Now use CTRL-R v to insert the function name:
357         r = VeryLongFunction ~
359 You continue to type the characters in between the function name, and use
360 CTRL-R v two times more.
361    You could have done the same with completion.  Using a register is useful
362 when there are many words that start with the same characters.
364 If the register contains characters such as <BS> or other special characters,
365 they are interpreted as if they had been typed from the keyboard.  If you do
366 not want this to happen (you really want the <BS> to be inserted in the text),
367 use the command CTRL-R CTRL-R {register}.
369 ==============================================================================
370 *24.7*  Abbreviations
372 An abbreviation is a short word that takes the place of a long one.  For
373 example, "ad" stands for "advertisement".  Vim enables you to type an
374 abbreviation and then will automatically expand it for you.
375    To tell Vim to expand "ad" into "advertisement" every time you insert it,
376 use the following command: >
378         :iabbrev ad advertisement
380 Now, when you type "ad", the whole word "advertisement" will be inserted into
381 the text.  This is triggered by typing a character that can't be part of a
382 word, for example a space:
384         What Is Entered         What You See
385         I saw the a             I saw the a ~
386         I saw the ad            I saw the ad ~
387         I saw the ad<Space>     I saw the advertisement<Space> ~
389 The expansion doesn't happen when typing just "ad".  That allows you to type a
390 word like "add", which will not get expanded.  Only whole words are checked
391 for abbreviations.
394 ABBREVIATING SEVERAL WORDS
396 It is possible to define an abbreviation that results in multiple words.  For
397 example, to define "JB" as "Jack Benny", use the following command: >
399         :iabbrev JB Jack Benny
401 As a programmer, I use two rather unusual abbreviations: >
403         :iabbrev #b /****************************************
404         :iabbrev #e <Space>****************************************/
406 These are used for creating boxed comments.  The comment starts with #b, which
407 draws the top line.  I then type the comment text and use #e to draw the
408 bottom line.
409    Notice that the #e abbreviation begins with a space.  In other words, the
410 first two characters are space-star.  Usually Vim ignores spaces between the
411 abbreviation and the expansion.  To avoid that problem, I spell space as seven
412 characters: <, S, p, a, c, e, >.
414         Note:
415         ":iabbrev" is a long word to type.  ":iab" works just as well.
416         That's abbreviating the abbreviate command!
419 FIXING TYPING MISTAKES
421 It's very common to make the same typing mistake every time.  For example,
422 typing "teh" instead of "the".  You can fix this with an abbreviation: >
424         :abbreviate teh the
426 You can add a whole list of these.  Add one each time you discover a common
427 mistake.
430 LISTING ABBREVIATIONS
432 The ":abbreviate" command lists the abbreviations:
434         :abbreviate
435         i  #e             ****************************************/
436         i  #b            /****************************************
437         i  JB            Jack Benny
438         i  ad            advertisement
439         !  teh           the
441 The "i" in the first column indicates Insert mode.  These abbreviations are
442 only active in Insert mode.  Other possible characters are:
444         c       Command-line mode                       :cabbrev
445         !       both Insert and Command-line mode       :abbreviate
447 Since abbreviations are not often useful in Command-line mode, you will mostly
448 use the ":iabbrev" command.  That avoids, for example, that "ad" gets expanded
449 when typing a command like: >
451         :edit ad
454 DELETING ABBREVIATIONS
456 To get rid of an abbreviation, use the ":unabbreviate" command.  Suppose you
457 have the following abbreviation: >
459         :abbreviate @f fresh
461 You can remove it with this command: >
463         :unabbreviate @f
465 While you type this, you will notice that @f is expanded to "fresh".  Don't
466 worry about this, Vim understands it anyway (except when you have an
467 abbreviation for "fresh", but that's very unlikely).
468    To remove all the abbreviations: >
470         :abclear
472 ":unabbreviate" and ":abclear" also come in the variants for Insert mode
473 (":iunabbreviate and ":iabclear") and Command-line mode (":cunabbreviate" and
474 ":cabclear").
477 REMAPPING ABBREVIATIONS
479 There is one thing to watch out for when defining an abbreviation: The
480 resulting string should not be mapped.  For example: >
482         :abbreviate @a adder
483         :imap dd disk-door
485 When you now type @a, you will get "adisk-doorer".  That's not what you want.
486 To avoid this, use the ":noreabbrev" command.  It does the same as
487 ":abbreviate", but avoids that the resulting string is used for mappings: >
489         :noreabbrev @a adder
491 Fortunately, it's unlikely that the result of an abbreviation is mapped.
493 ==============================================================================
494 *24.8*  Entering special characters
496 The CTRL-V command is used to insert the next character literally.  In other
497 words, any special meaning the character has, it will be ignored.  For
498 example: >
500         CTRL-V <Esc>
502 Inserts an escape character.  Thus you don't leave Insert mode.  (Don't type
503 the space after CTRL-V, it's only to make this easier to read).
505         Note:
506         On MS-Windows CTRL-V is used to paste text.  Use CTRL-Q instead of
507         CTRL-V.  On Unix, on the other hand, CTRL-Q does not work on some
508         terminals, because it has a special meaning.
510 You can also use the command CTRL-V {digits} to insert a character with the
511 decimal number {digits}.  For example, the character number 127 is the <Del>
512 character (but not necessarily the <Del> key!).  To insert <Del> type: >
514         CTRL-V 127
516 You can enter characters up to 255 this way.  When you type fewer than two
517 digits, a non-digit will terminate the command.  To avoid the need of typing a
518 non-digit, prepend one or two zeros to make three digits.
519    All the next commands insert a <Tab> and then a dot:
521         CTRL-V 9.
522         CTRL-V 09.
523         CTRL-V 009.
525 To enter a character in hexadecimal, use an "x" after the CTRL-V: >
527         CTRL-V x7f
529 This also goes up to character 255 (CTRL-V xff).  You can use "o" to type a
530 character as an octal number and two more methods allow you to type up to
531 a 16 bit and a 32 bit number (e.g., for a Unicode character): >
533         CTRL-V o123
534         CTRL-V u1234
535         CTRL-V U12345678
537 ==============================================================================
538 *24.9*  Digraphs
540 Some characters are not on the keyboard.  For example, the copyright character
541 (©).  To type these characters in Vim, you use digraphs, where two characters
542 represent one.  To enter a ©, for example, you press three keys: >
544         CTRL-K Co
546 To find out what digraphs are available, use the following command: >
548         :digraphs
550 Vim will display the digraph table.  Here are three lines of it:
552   AC ~_ 159  NS |  160  !I ¡  161  Ct ¢  162  Pd £  163  Cu ¤  164  Ye ¥  165 ~
553   BB ¦  166  SE §  167  ': ¨  168  Co ©  169  -a ª  170  << «  171  NO ¬  172 ~
554   -- ­  173  Rg ®  174  'm ¯  175  DG °  176  +- ±  177  2S ²  178  3S ³  179 ~
556 This shows, for example, that the digraph you get by typing CTRL-K Pd is the
557 character (£).  This is character number 163 (decimal).
558    Pd is short for Pound.  Most digraphs are selected to give you a hint about
559 the character they will produce.  If you look through the list you will
560 understand the logic.
561    You can exchange the first and second character, if there is no digraph for
562 that combination.  Thus CTRL-K dP also works.  Since there is no digraph for
563 "dP" Vim will also search for a "Pd" digraph.
565         Note:
566         The digraphs depend on the character set that Vim assumes you are
567         using.  On MS-DOS they are different from MS-Windows.  Always use
568         ":digraphs" to find out which digraphs are currently available.
570 You can define your own digraphs.  Example: >
572         :digraph a" ä
574 This defines that CTRL-K a" inserts an ä character.  You can also specify the
575 character with a decimal number.  This defines the same digraph: >
577         :digraph a" 228
579 More information about digraphs here: |digraphs|
580    Another way to insert special characters is with a keymap.  More about that
581 here: |45.5|
583 ==============================================================================
584 *24.10* Normal mode commands
586 Insert mode offers a limited number of commands.  In Normal mode you have many
587 more.  When you want to use one, you usually leave Insert mode with <Esc>,
588 execute the Normal mode command, and re-enter Insert mode with "i" or "a".
589    There is a quicker way.  With CTRL-O {command} you can execute any Normal
590 mode command from Insert mode.  For example, to delete from the cursor to the
591 end of the line: >
593         CTRL-O D
595 You can execute only one Normal mode command this way.  But you can specify a
596 register or a count.  A more complicated example: >
598         CTRL-O "g3dw
600 This deletes up to the third word into register g.
602 ==============================================================================
604 Next chapter: |usr_25.txt|  Editing formatted text
606 Copyright: see |manual-copyright|  vim:tw=78:ts=8:ft=help:norl: