Fix placement of auxiliary IM window for Core Text
[MacVim.git] / runtime / doc / usr_03.txt
blob30a6eea7aa69b35a45f4cf445c51fe5b9671bbba
1 *usr_03.txt*    For Vim version 7.2.  Last change: 2006 Jun 21
3                      VIM USER MANUAL - by Bram Moolenaar
5                              Moving around
8 Before you can insert or delete text the cursor has to be moved to the right
9 place.  Vim has a large number of commands to position the cursor.  This
10 chapter shows you how to use the most important ones.  You can find a list of
11 these commands below |Q_lr|.
13 |03.1|  Word movement
14 |03.2|  Moving to the start or end of a line
15 |03.3|  Moving to a character
16 |03.4|  Matching a parenthesis
17 |03.5|  Moving to a specific line
18 |03.6|  Telling where you are
19 |03.7|  Scrolling around
20 |03.8|  Simple searches
21 |03.9|  Simple search patterns
22 |03.10| Using marks
24      Next chapter: |usr_04.txt|  Making small changes
25  Previous chapter: |usr_02.txt|  The first steps in Vim
26 Table of contents: |usr_toc.txt|
28 ==============================================================================
29 *03.1*  Word movement
31 To move the cursor forward one word, use the "w" command.  Like most Vim
32 commands, you can use a numeric prefix to move past multiple words.  For
33 example, "3w" moves three words.  This figure shows how it works:
35         This is a line with example text ~
36           --->-->->----------------->
37            w  w  w    3w
39 Notice that "w" moves to the start of the next word if it already is at the
40 start of a word.
41    The "b" command moves backward to the start of the previous word:
43         This is a line with example text ~
44         <----<--<-<---------<---
45            b   b b    2b      b
47 There is also the "e" command that moves to the next end of a word and "ge",
48 which moves to the previous end of a word:
50         This is a line with example text ~
51            <-   <--- ----->   ---->
52            ge    ge     e       e
54 If you are at the last word of a line, the "w" command will take you to the
55 first word in the next line.  Thus you can use this to move through a
56 paragraph, much faster than using "l".  "b" does the same in the other
57 direction.
59 A word ends at a non-word character, such as a ".", "-" or ")".  To change
60 what Vim considers to be a word, see the 'iskeyword' option.
61    It is also possible to move by white-space separated WORDs.  This is not a
62 word in the normal sense, that's why the uppercase is used.  The commands for
63 moving by WORDs are also uppercase, as this figure shows:
65                ge      b          w                             e
66                <-     <-         --->                          --->
67         This is-a line, with special/separated/words (and some more). ~
68            <----- <-----         -------------------->         ----->
69              gE      B                   W                       E
71 With this mix of lowercase and uppercase commands, you can quickly move
72 forward and backward through a paragraph.
74 ==============================================================================
75 *03.2*  Moving to the start or end of a line
77 The "$" command moves the cursor to the end of a line.  If your keyboard has
78 an <End> key it will do the same thing.
80 The "^" command moves to the first non-blank character of the line.  The "0"
81 command (zero) moves to the very first character of the line.  The <Home> key
82 does the same thing.  In a picture:
84                   ^
85              <------------
86         .....This is a line with example text ~
87         <-----------------   --------------->
88                 0                  $
90 (the "....." indicates blanks here)
92    The "$" command takes a count, like most movement commands.  But moving to
93 the end of the line several times doesn't make sense.  Therefore it causes the
94 editor to move to the end of another line.  For example, "1$" moves you to
95 the end of the first line (the one you're on), "2$" to the end of the next
96 line, and so on.
97    The "0" command doesn't take a count argument, because the "0" would be
98 part of the count.  Unexpectedly, using a count with "^" doesn't have any
99 effect.
101 ==============================================================================
102 *03.3*  Moving to a character
104 One of the most useful movement commands is the single-character search
105 command.  The command "fx" searches forward in the line for the single
106 character x.  Hint: "f" stands for "Find".
107    For example, you are at the beginning of the following line.  Suppose you
108 want to go to the h of human.  Just execute the command "fh" and the cursor
109 will be positioned over the h:
111         To err is human.  To really foul up you need a computer. ~
112         ---------->--------------->
113             fh           fy
115 This also shows that the command "fy" moves to the end of the word really.
116    You can specify a count; therefore, you can go to the "l" of "foul" with
117 "3fl":
119         To err is human.  To really foul up you need a computer. ~
120                   --------------------->
121                            3fl
123 The "F" command searches to the left:
125         To err is human.  To really foul up you need a computer. ~
126                   <---------------------
127                             Fh
129 The "tx" command works like the "fx" command, except it stops one character
130 before the searched character.  Hint: "t" stands for "To".  The backward
131 version of this command is "Tx".
133         To err is human.  To really foul up you need a computer. ~
134                    <------------  ------------->
135                         Th              tn
137 These four commands can be repeated with ";".  "," repeats in the other
138 direction.  The cursor is never moved to another line.  Not even when the
139 sentence continues.
141 Sometimes you will start a search, only to realize that you have typed the
142 wrong command.  You type "f" to search backward, for example, only to realize
143 that you really meant "F".  To abort a search, press <Esc>.  So "f<Esc>" is an
144 aborted forward search and doesn't do anything.  Note: <Esc> cancels most
145 operations, not just searches.
147 ==============================================================================
148 *03.4*  Matching a parenthesis
150 When writing a program you often end up with nested () constructs.  Then the
151 "%" command is very handy: It moves to the matching paren.  If the cursor is
152 on a "(" it will move to the matching ")".  If it's on a ")" it will move to
153 the matching "(".
155                             %
156                          <----->
157                 if (a == (b * c) / d) ~
158                    <---------------->
159                             %
161 This also works for [] and {} pairs.  (This can be defined with the
162 'matchpairs' option.)
164 When the cursor is not on a useful character, "%" will search forward to find
165 one.  Thus if the cursor is at the start of the line of the previous example,
166 "%" will search forward and find the first "(".  Then it moves to its match:
168                 if (a == (b * c) / d) ~
169                 ---+---------------->
170                            %
172 ==============================================================================
173 *03.5*  Moving to a specific line
175 If you are a C or C++ programmer, you are familiar with error messages such as
176 the following:
178         prog.c:33: j   undeclared (first use in this function) ~
180 This tells you that you might want to fix something on line 33.  So how do you
181 find line 33?  One way is to do "9999k" to go to the top of the file and "32j"
182 to go down thirty two lines.  It is not a good way, but it works.  A much
183 better way of doing things is to use the "G" command.  With a count, this
184 command positions you at the given line number.  For example, "33G" puts you
185 on line 33.  (For a better way of going through a compiler's error list, see
186 |usr_30.txt|, for information on the :make command.)
187    With no argument, "G" positions you at the end of the file.  A quick way to
188 go to the start of a file use "gg".  "1G" will do the same, but is a tiny bit
189 more typing.
191             |   first line of a file   ^
192             |   text text text text    |
193             |   text text text text    |  gg
194         7G  |   text text text text    |
195             |   text text text text
196             |   text text text text
197             V   text text text text    |
198                 text text text text    |  G
199                 text text text text    |
200                 last line of a file    V
202 Another way to move to a line is using the "%" command with a count.  For
203 example "50%" moves you to halfway the file.  "90%" goes to near the end.
205 The previous assumes that you want to move to a line in the file, no matter if
206 it's currently visible or not.  What if you want to move to one of the lines
207 you can see?  This figure shows the three commands you can use:
209                         +---------------------------+
210                 H -->   | text sample text          |
211                         | sample text               |
212                         | text sample text          |
213                         | sample text               |
214                 M -->   | text sample text          |
215                         | sample text               |
216                         | text sample text          |
217                         | sample text               |
218                 L -->   | text sample text          |
219                         +---------------------------+
221 Hints: "H" stands for Home, "M" for Middle and "L" for Last.
223 ==============================================================================
224 *03.6*  Telling where you are
226 To see where you are in a file, there are three ways:
228 1.  Use the CTRL-G command.  You get a message like this (assuming the 'ruler'
229     option is off):
231         "usr_03.txt" line 233 of 650 --35%-- col 45-52 ~
233     This shows the name of the file you are editing, the line number where the
234     cursor is, the total number of lines, the percentage of the way through
235     the file and the column of the cursor.
236        Sometimes you will see a split column number.  For example, "col 2-9".
237     This indicates that the cursor is positioned on the second character, but
238     because character one is a tab, occupying eight spaces worth of columns,
239     the screen column is 9.
241 2.  Set the 'number' option.  This will display a line number in front of
242     every line: >
244         :set number
246     To switch this off again: >
248         :set nonumber
250     Since 'number' is a boolean option, prepending "no" to its name has the
251     effect of switching it off.  A boolean option has only these two values,
252     it is either on or off.
253        Vim has many options.  Besides the boolean ones there are options with
254     a numerical value and string options.  You will see examples of this where
255     they are used.
257 3.  Set the 'ruler' option.  This will display the cursor position in the
258     lower right corner of the Vim window: >
260         :set ruler
262 Using the 'ruler' option has the advantage that it doesn't take much room,
263 thus there is more space for your text.
265 ==============================================================================
266 *03.7*  Scrolling around
268 The CTRL-U command scrolls down half a screen of text.  Think of looking
269 through a viewing window at the text and moving this window up by half the
270 height of the window.  Thus the window moves up over the text, which is
271 backward in the file.  Don't worry if you have a little trouble remembering
272 which end is up.  Most users have the same problem.
273    The CTRL-D command moves the viewing window down half a screen in the file,
274 thus scrolls the text up half a screen.
276                                        +----------------+
277                                        | some text      |
278                                        | some text      |
279                                        | some text      |
280         +---------------+              | some text      |
281         | some text     |  CTRL-U  --> |                |
282         |               |              | 123456         |
283         | 123456        |              +----------------+
284         | 7890          |
285         |               |              +----------------+
286         | example       |  CTRL-D -->  | 7890           |
287         +---------------+              |                |
288                                        | example        |
289                                        | example        |
290                                        | example        |
291                                        | example        |
292                                        +----------------+
294 To scroll one line at a time use CTRL-E (scroll up) and CTRL-Y (scroll down).
295 Think of CTRL-E to give you one line Extra.  (If you use MS-Windows compatible
296 key mappings CTRL-Y will redo a change instead of scroll.)
298 To scroll forward by a whole screen (except for two lines) use CTRL-F.  The
299 other way is backward, CTRL-B is the command to use.  Fortunately CTRL-F is
300 Forward and CTRL-B is Backward, that's easy to remember.
302 A common issue is that after moving down many lines with "j" your cursor is at
303 the bottom of the screen.  You would like to see the context of the line with
304 the cursor.  That's done with the "zz" command.
306         +------------------+             +------------------+
307         | some text        |             | some text        |
308         | some text        |             | some text        |
309         | some text        |             | some text        |
310         | some text        |   zz  -->   | line with cursor |
311         | some text        |             | some text        |
312         | some text        |             | some text        |
313         | line with cursor |             | some text        |
314         +------------------+             +------------------+
316 The "zt" command puts the cursor line at the top, "zb" at the bottom.  There
317 are a few more scrolling commands, see |Q_sc|.  To always keep a few lines of
318 context around the cursor, use the 'scrolloff' option.
320 ==============================================================================
321 *03.8*  Simple searches
323 To search for a string, use the "/string" command.  To find the word include,
324 for example, use the command: >
326         /include
328 You will notice that when you type the "/" the cursor jumps to the last line
329 of the Vim window, like with colon commands.  That is where you type the word.
330 You can press the backspace key (backarrow or <BS>) to make corrections.  Use
331 the <Left> and <Right> cursor keys when necessary.
332    Pressing <Enter> executes the command.
334         Note:
335         The characters .*[]^%/\?~$ have special meanings.  If you want to use
336         them in a search you must put a \ in front of them.  See below.
338 To find the next occurrence of the same string use the "n" command.  Use this
339 to find the first #include after the cursor: >
341         /#include
343 And then type "n" several times.  You will move to each #include in the text.
344 You can also use a count if you know which match you want.  Thus "3n" finds
345 the third match.  Using a count with "/" doesn't work.
347 The "?" command works like "/" but searches backwards: >
349         ?word
351 The "N" command repeats the last search the opposite direction.  Thus using
352 "N" after a "/" command search backwards, using "N" after "?" searches
353 forward.
356 IGNORING CASE
358 Normally you have to type exactly what you want to find.  If you don't care
359 about upper or lowercase in a word, set the 'ignorecase' option: >
361         :set ignorecase
363 If you now search for "word", it will also match "Word" and "WORD".  To match
364 case again: >
366         :set noignorecase
369 HISTORY
371 Suppose you do three searches: >
373         /one
374         /two
375         /three
377 Now let's start searching by typing a simple "/" without pressing <Enter>.  If
378 you press <Up> (the cursor key), Vim puts "/three" on the command line.
379 Pressing <Enter> at this point searches for three.  If you do not press
380 <Enter>, but press <Up> instead, Vim changes the prompt to "/two".  Another
381 press of <Up> moves you to "/one".
382    You can also use the <Down> cursor key to move through the history of
383 search commands in the other direction.
385 If you know what a previously used pattern starts with, and you want to use it
386 again, type that character before pressing <Up>.  With the previous example,
387 you can type "/o<Up>" and Vim will put "/one" on the command line.
389 The commands starting with ":" also have a history.  That allows you to recall
390 a previous command and execute it again.  These two histories are separate.
393 SEARCHING FOR A WORD IN THE TEXT
395 Suppose you see the word "TheLongFunctionName" in the text and you want to
396 find the next occurrence of it.  You could type "/TheLongFunctionName", but
397 that's a lot of typing.  And when you make a mistake Vim won't find it.
398    There is an easier way: Position the cursor on the word and use the "*"
399 command.  Vim will grab the word under the cursor and use it as the search
400 string.
401    The "#" command does the same in the other direction.  You can prepend a
402 count: "3*" searches for the third occurrence of the word under the cursor.
405 SEARCHING FOR WHOLE WORDS
407 If you type "/the" it will also match "there".  To only find words that end
408 in "the" use: >
410         /the\>
412 The "\>" item is a special marker that only matches at the end of a word.
413 Similarly "\<" only matches at the begin of a word.  Thus to search for the
414 word "the" only: >
416         /\<the\>
418 This does not match "there" or "soothe".  Notice that the "*" and "#" commands
419 use these start-of-word and end-of-word markers to only find whole words (you
420 can use "g*" and "g#" to match partial words).
423 HIGHLIGHTING MATCHES
425 While editing a program you see a variable called "nr".  You want to check
426 where it's used.  You could move the cursor to "nr" and use the "*" command
427 and press "n" to go along all the matches.
428    There is another way.  Type this command: >
430         :set hlsearch
432 If you now search for "nr", Vim will highlight all matches.  That is a very
433 good way to see where the variable is used, without the need to type commands.
434    To switch this off: >
436         :set nohlsearch
438 Then you need to switch it on again if you want to use it for the next search
439 command.  If you only want to remove the highlighting, use this command: >
441         :nohlsearch
443 This doesn't reset the option.  Instead, it disables the highlighting.  As
444 soon as you execute a search command, the highlighting will be used again.
445 Also for the "n" and "N" commands.
448 TUNING SEARCHES
450 There are a few options that change how searching works.  These are the
451 essential ones:
453         :set incsearch
455 This makes Vim display the match for the string while you are still typing it.
456 Use this to check if the right match will be found.  Then press <Enter> to
457 really jump to that location.  Or type more to change the search string.
459         :set nowrapscan
461 This stops the search at the end of the file.  Or, when you are searching
462 backwards, at the start of the file.  The 'wrapscan' option is on by default,
463 thus searching wraps around the end of the file.
466 INTERMEZZO
468 If you like one of the options mentioned before, and set it each time you use
469 Vim, you can put the command in your Vim startup file.
470    Edit the file, as mentioned at |not-compatible|.  Or use this command to
471 find out where it is: >
473         :scriptnames
475 Edit the file, for example with: >
477         :edit ~/.vimrc
479 Then add a line with the command to set the option, just like you typed it in
480 Vim.  Example: >
482         Go:set hlsearch<Esc>
484 "G" moves to the end of the file.  "o" starts a new line, where you type the
485 ":set" command.  You end insert mode with <Esc>.  Then write the file: >
487         ZZ
489 If you now start Vim again, the 'hlsearch' option will already be set.
491 ==============================================================================
492 *03.9*  Simple search patterns
494 The Vim editor uses regular expressions to specify what to search for.
495 Regular expressions are an extremely powerful and compact way to specify a
496 search pattern.  Unfortunately, this power comes at a price, because regular
497 expressions are a bit tricky to specify.
498    In this section we mention only a few essential ones.  More about search
499 patterns and commands in chapter 27 |usr_27.txt|.  You can find the full
500 explanation here: |pattern|.
503 BEGINNING AND END OF A LINE
505 The ^ character matches the beginning of a line.  On an English-US keyboard
506 you find it above the 6.  The pattern "include" matches the word include
507 anywhere on the line.  But the pattern "^include" matches the word include
508 only if it is at the beginning of a line.
509    The $ character matches the end of a line.  Therefore, "was$" matches the
510 word was only if it is at the end of a line.
512 Let's mark the places where "the" matches in this example line with "x"s:
514         the solder holding one of the chips melted and the ~
515         xxx                       xxx                  xxx
517 Using "/the$" we find this match:
519         the solder holding one of the chips melted and the ~
520                                                        xxx
522 And with "/^the" we find this one:
523         the solder holding one of the chips melted and the ~
524         xxx
526 You can try searching with "/^the$", it will only match a single line
527 consisting of "the".  White space does matter here, thus if a line contains a
528 space after the word, like "the ", the pattern will not match.
531 MATCHING ANY SINGLE CHARACTER
533 The . (dot) character matches any existing character.  For example, the
534 pattern "c.m" matches a string whose first character is a c, whose second
535 character is anything, and whose the third character is m.  Example:
537         We use a computer that became the cummin winter. ~
538                  xxx             xxx      xxx
541 MATCHING SPECIAL CHARACTERS
543 If you really want to match a dot, you must avoid its special meaning by
544 putting a backslash before it.
545    If you search for "ter.", you will find these matches:
547         We use a computer that became the cummin winter. ~
548                       xxxx                          xxxx
550 Searching for "ter\." only finds the second match.
552 ==============================================================================
553 *03.10* Using marks
555 When you make a jump to a position with the "G" command, Vim remembers the
556 position from before this jump.  This position is called a mark.  To go back
557 where you came from, use this command: >
559         ``
561 This ` is a backtick or open single-quote character.
562    If you use the same command a second time you will jump back again.  That's
563 because the ` command is a jump itself, and the position from before this jump
564 is remembered.
566 Generally, every time you do a command that can move the cursor further than
567 within the same line, this is called a jump.  This includes the search
568 commands "/" and "n" (it doesn't matter how far away the match is).  But not
569 the character searches with "fx" and "tx" or the word movements "w" and "e".
570    Also, "j" and "k" are not considered to be a jump.  Even when you use a
571 count to make them move the cursor quite a long way away.
573 The `` command jumps back and forth, between two points.  The CTRL-O command
574 jumps to older positions (Hint: O for older).  CTRL-I then jumps back to newer
575 positions (Hint: I is just next to O on the keyboard).  Consider this sequence
576 of commands: >
578         33G
579         /^The
580         CTRL-O
582 You first jump to line 33, then search for a line that starts with "The".
583 Then with CTRL-O you jump back to line 33.  Another CTRL-O takes you back to
584 where you started.  If you now use CTRL-I you jump to line 33 again.  And
585 to the match for "The" with another CTRL-I.
588              |  example text   ^             |
589         33G  |  example text   |  CTRL-O     | CTRL-I
590              |  example text   |             |
591              V  line 33 text   ^             V
592              |  example text   |             |
593        /^The |  example text   |  CTRL-O     | CTRL-I
594              V  There you are  |             V
595                 example text
597         Note:
598         CTRL-I is the same as <Tab>.
600 The ":jumps" command gives a list of positions you jumped to.  The entry which
601 you used last is marked with a ">".
604 NAMED MARKS                                                     *bookmark*
606 Vim enables you to place your own marks in the text.  The command "ma" marks
607 the place under the cursor as mark a.  You can place 26 marks (a through z) in
608 your text.  You can't see them, it's just a position that Vim remembers.
609    To go to a mark, use the command `{mark}, where {mark} is the mark letter.
610 Thus to move to the a mark:
612         `a
614 The command 'mark (single quotation mark, or apostrophe) moves you to the
615 beginning of the line containing the mark.  This differs from the `mark
616 command, which moves you to marked column.
618 The marks can be very useful when working on two related parts in a file.
619 Suppose you have some text near the start of the file you need to look at,
620 while working on some text near the end of the file.
621    Move to the text at the start and place the s (start) mark there: >
623         ms
625 Then move to the text you want to work on and put the e (end) mark there: >
627         me
629 Now you can move around, and when you want to look at the start of the file,
630 you use this to jump there: >
632         's
634 Then you can use '' to jump back to where you were, or 'e to jump to the text
635 you were working on at the end.
636    There is nothing special about using s for start and e for end, they are
637 just easy to remember.
639 You can use this command to get a list of marks: >
641         :marks
643 You will notice a few special marks.  These include:
645         '       The cursor position before doing a jump
646         "       The cursor position when last editing the file
647         [       Start of the last change
648         ]       End of the last change
650 ==============================================================================
652 Next chapter: |usr_04.txt|  Making small changes
654 Copyright: see |manual-copyright|  vim:tw=78:ts=8:ft=help:norl: