Merged from the latest developing branch.
[MacVim.git] / runtime / doc / usr_10.txt
blobc1334a54311d4aea196c21a64feff5201fca0e9b
1 *usr_10.txt*    For Vim version 7.2.  Last change: 2006 Nov 05
3                      VIM USER MANUAL - by Bram Moolenaar
5                              Making big changes
8 In chapter 4 several ways to make small changes were explained.  This chapter
9 goes into making changes that are repeated or can affect a large amount of
10 text.  The Visual mode allows doing various things with blocks of text.  Use
11 an external program to do really complicated things.
13 |10.1|  Record and playback commands
14 |10.2|  Substitution
15 |10.3|  Command ranges
16 |10.4|  The global command
17 |10.5|  Visual block mode
18 |10.6|  Reading and writing part of a file
19 |10.7|  Formatting text
20 |10.8|  Changing case
21 |10.9|  Using an external program
23      Next chapter: |usr_11.txt|  Recovering from a crash
24  Previous chapter: |usr_09.txt|  Using the GUI
25 Table of contents: |usr_toc.txt|
27 ==============================================================================
28 *10.1*  Record and playback commands
30 The "." command repeats the preceding change.  But what if you want to do
31 something more complex than a single change?  That's where command recording
32 comes in.  There are three steps:
34 1. The "q{register}" command starts recording keystrokes into the register
35    named {register}.  The register name must be between a and z.
36 2. Type your commands.
37 3. To finish recording, press q (without any extra character).
39 You can now execute the macro by typing the command "@{register}".
41 Take a look at how to use these commands in practice.  You have a list of
42 filenames that look like this:
44         stdio.h ~
45         fcntl.h ~
46         unistd.h ~
47         stdlib.h ~
49 And what you want is the following:
51         #include "stdio.h" ~
52         #include "fcntl.h" ~
53         #include "unistd.h" ~
54         #include "stdlib.h" ~
56 You start by moving to the first character of the first line.  Next you
57 execute the following commands:
59         qa                      Start recording a macro in register a.
60         ^                       Move to the beginning of the line.
61         i#include "<Esc>        Insert the string #include " at the beginning
62                                 of the line.
63         $                       Move to the end of the line.
64         a"<Esc>                 Append the character double quotation mark (")
65                                 to the end of the line.
66         j                       Go to the next line.
67         q                       Stop recording the macro.
69 Now that you have done the work once, you can repeat the change by typing the
70 command "@a" three times.
71    The "@a" command can be preceded by a count, which will cause the macro to
72 be executed that number of times.  In this case you would type: >
74         3@a
77 MOVE AND EXECUTE
79 You might have the lines you want to change in various places.  Just move the
80 cursor to each location and use the "@a" command.  If you have done that once,
81 you can do it again with "@@".  That's a bit easier to type.  If you now
82 execute register b with "@b", the next "@@" will use register b.
83    If you compare the playback method with using ".", there are several
84 differences.  First of all, "." can only repeat one change.  As seen in the
85 example above, "@a" can do several changes, and move around as well.
86 Secondly, "." can only remember the last change.  Executing a register allows
87 you to make any changes and then still use "@a" to replay the recorded
88 commands.  Finally, you can use 26 different registers.  Thus you can remember
89 26 different command sequences to execute.
92 USING REGISTERS
94 The registers used for recording are the same ones you used for yank and
95 delete commands.  This allows you to mix recording with other commands to
96 manipulate the registers.
97    Suppose you have recorded a few commands in register n.  When you execute
98 this with "@n" you notice you did something wrong.  You could try recording
99 again, but perhaps you will make another mistake.  Instead, use this trick:
101         G                       Go to the end of the file.
102         o<Esc>                  Create an empty line.
103         "np                     Put the text from the n register.  You now see
104                                 the commands you typed as text in the file.
105         {edits}                 Change the commands that were wrong.  This is
106                                 just like editing text.
107         0                       Go to the start of the line.
108         "ny$                    Yank the corrected commands into the n
109                                 register.
110         dd                      Delete the scratch line.
112 Now you can execute the corrected commands with "@n".  (If your recorded
113 commands include line breaks, adjust the last two items in the example to
114 include all the lines.)
117 APPENDING TO A REGISTER
119 So far we have used a lowercase letter for the register name.  To append to a
120 register, use an uppercase letter.
121    Suppose you have recorded a command to change a word to register c.  It
122 works properly, but you would like to add a search for the next word to
123 change.  This can be done with: >
125         qC/word<Enter>q
127 You start with "qC", which records to the c register and appends.  Thus
128 writing to an uppercase register name means to append to the register with
129 the same letter, but lowercase.
131 This works both with recording and with yank and delete commands.  For
132 example, you want to collect a sequence of lines into the a register.  Yank
133 the first line with: >
135         "aY
137 Now move to the second line, and type: >
139         "AY
141 Repeat this command for all lines.  The a register now contains all those
142 lines, in the order you yanked them.
144 ==============================================================================
145 *10.2*  Substitution                                            *find-replace*
147 The ":substitute" command enables you to perform string replacements on a
148 whole range of lines.  The general form of this command is as follows: >
150         :[range]substitute/from/to/[flags]
152 This command changes the "from" string to the "to" string in the lines
153 specified with [range].  For example, you can change "Professor" to "Teacher"
154 in all lines with the following command: >
156         :%substitute/Professor/Teacher/
158         Note:
159         The ":substitute" command is almost never spelled out completely.
160         Most of the time, people use the abbreviated version ":s".  From here
161         on the abbreviation will be used.
163 The "%" before the command specifies the command works on all lines.  Without
164 a range, ":s" only works on the current line.  More about ranges in the next
165 section |10.3|.
167 By default, the ":substitute" command changes only the first occurrence on
168 each line.  For example, the preceding command changes the line:
170         Professor Smith criticized Professor Johnson today. ~
174         Teacher Smith criticized Professor Johnson today. ~
176 To change every occurrence on the line, you need to add the g (global) flag.
177 The command: >
179         :%s/Professor/Teacher/g
181 results in (starting with the original line):
183         Teacher Smith criticized Teacher Johnson today. ~
185 Other flags include p (print), which causes the ":substitute" command to print
186 out the last line it changes.  The c (confirm) flag tells ":substitute" to ask
187 you for confirmation before it performs each substitution.  Enter the
188 following: >
190         :%s/Professor/Teacher/c
192 Vim finds the first occurrence of "Professor" and displays the text it is
193 about to change.  You get the following prompt: >
195         replace with Teacher (y/n/a/q/l/^E/^Y)?
197 At this point, you must enter one of the following answers:
199         y               Yes; make this change.
200         n               No; skip this match.
201         a               All; make this change and all remaining ones without
202                         further confirmation.
203         q               Quit; don't make any more changes.
204         l               Last; make this change and then quit.
205         CTRL-E          Scroll the text one line up.
206         CTRL-Y          Scroll the text one line down.
209 The "from" part of the substitute command is actually a pattern.  The same
210 kind as used for the search command.  For example, this command only
211 substitutes "the" when it appears at the start of a line: >
213         :s/^the/these/
215 If you are substituting with a "from" or "to" part that includes a slash, you
216 need to put a backslash before it.  A simpler way is to use another character
217 instead of the slash.  A plus, for example: >
219         :s+one/two+one or two+
221 ==============================================================================
222 *10.3*  Command ranges
224 The ":substitute" command, and many other : commands, can be applied to a
225 selection of lines.  This is called a range.
226    The simple form of a range is {number},{number}.  For example: >
228         :1,5s/this/that/g
230 Executes the substitute command on the lines 1 to 5.  Line 5 is included.
231 The range is always placed before the command.
233 A single number can be used to address one specific line: >
235         :54s/President/Fool/
237 Some commands work on the whole file when you do not specify a range.  To make
238 them work on the current line the "." address is used.  The ":write" command
239 works like that.  Without a range, it writes the whole file.  To make it write
240 only the current line into a file: >
242         :.write otherfile
244 The first line always has number one.  How about the last line?  The "$"
245 character is used for this.  For example, to substitute in the lines from the
246 cursor to the end: >
248         :.,$s/yes/no/
250 The "%" range that we used before, is actually a short way to say "1,$", from
251 the first to the last line.
254 USING A PATTERN IN A RANGE
256 Suppose you are editing a chapter in a book, and want to replace all
257 occurrences of "grey" with "gray".  But only in this chapter, not in the next
258 one.  You know that only chapter boundaries have the word "Chapter" in the
259 first column.  This command will work then: >
261         :?^Chapter?,/^Chapter/s=grey=gray=g
263 You can see a search pattern is used twice.  The first "?^Chapter?" finds the
264 line above the current position that matches this pattern.  Thus the ?pattern?
265 range is used to search backwards.  Similarly, "/^Chapter/" is used to search
266 forward for the start of the next chapter.
267    To avoid confusion with the slashes, the "=" character was used in the
268 substitute command here.  A slash or another character would have worked as
269 well.
272 ADD AND SUBTRACT
274 There is a slight error in the above command: If the title of the next chapter
275 had included "grey" it would be replaced as well.  Maybe that's what you
276 wanted, but what if you didn't?  Then you can specify an offset.
277    To search for a pattern and then use the line above it: >
279         /Chapter/-1
281 You can use any number instead of the 1.  To address the second line below the
282 match: >
284         /Chapter/+2
286 The offsets can also be used with the other items in a range.  Look at this
287 one: >
289         :.+3,$-5
291 This specifies the range that starts three lines below the cursor and ends
292 five lines before the last line in the file.
295 USING MARKS
297 Instead of figuring out the line numbers of certain positions, remembering them
298 and typing them in a range, you can use marks.
299    Place the marks as mentioned in chapter 3.  For example, use "mt" to mark
300 the top of an area and "mb" to mark the bottom.  Then you can use this range
301 to specify the lines between the marks (including the lines with the marks): >
303         :'t,'b
306 VISUAL MODE AND RANGES
308 You can select text with Visual mode.  If you then press ":" to start a colon
309 command, you will see this: >
311         :'<,'>
313 Now you can type the command and it will be applied to the range of lines that
314 was visually selected.
316         Note:
317         When using Visual mode to select part of a line, or using CTRL-V to
318         select a block of text, the colon commands will still apply to whole
319         lines.  This might change in a future version of Vim.
321 The '< and '> are actually marks, placed at the start and end of the Visual
322 selection.  The marks remain at their position until another Visual selection
323 is made.  Thus you can use the "'<" command to jump to position where the
324 Visual area started.  And you can mix the marks with other items: >
326         :'>,$
328 This addresses the lines from the end of the Visual area to the end of the
329 file.
332 A NUMBER OF LINES
334 When you know how many lines you want to change, you can type the number and
335 then ":".  For example, when you type "5:", you will get: >
337         :.,.+4
339 Now you can type the command you want to use.  It will use the range "."
340 (current line) until ".+4" (four lines down).  Thus it spans five lines.
342 ==============================================================================
343 *10.4*  The global command
345 The ":global" command is one of the more powerful features of Vim.  It allows
346 you to find a match for a pattern and execute a command there.  The general
347 form is: >
349         :[range]global/{pattern}/{command}
351 This is similar to the ":substitute" command.  But, instead of replacing the
352 matched text with other text, the command {command} is executed.
354         Note:
355         The command executed for ":global" must be one that starts with a
356         colon.  Normal mode commands can not be used directly.  The |:normal|
357         command can do this for you.
359 Suppose you want to change "foobar" to "barfoo", but only in C++ style
360 comments.  These comments start with "//".  Use this command: >
362         :g+//+s/foobar/barfoo/g
364 This starts with ":g".  That is short for ":global", just like ":s" is short
365 for ":substitute".  Then the pattern, enclosed in plus characters.  Since the
366 pattern we are looking for contains a slash, this uses the plus character to
367 separate the pattern.  Next comes the substitute command that changes "foobar"
368 into "barfoo".
369    The default range for the global command is the whole file.  Thus no range
370 was specified in this example.  This is different from ":substitute", which
371 works on one line without a range.
372    The command isn't perfect, since it also matches lines where "//" appears
373 halfway a line, and the substitution will also take place before the "//".
375 Just like with ":substitute", any pattern can be used.  When you learn more
376 complicated patterns later, you can use them here.
378 ==============================================================================
379 *10.5*  Visual block mode
381 With CTRL-V you can start selection of a rectangular area of text.  There are
382 a few commands that do something special with the text block.
384 There is something special about using the "$" command in Visual block mode.
385 When the last motion command used was "$", all lines in the Visual selection
386 will extend until the end of the line, also when the line with the cursor is
387 shorter.  This remains effective until you use a motion command that moves the
388 cursor horizontally.  Thus using "j" keeps it, "h" stops it.
391 INSERTING TEXT
393 The command  "I{string}<Esc>" inserts the text {string} in each line, just
394 left of the visual block.  You start by pressing CTRL-V to enter visual block
395 mode.  Now you move the cursor to define your block.  Next you type I to enter
396 Insert mode, followed by the text to insert.  As you type, the text appears on
397 the first line only.
398    After you press <Esc> to end the insert, the text will magically be
399 inserted in the rest of the lines contained in the visual selection.  Example:
401         include one ~
402         include two ~
403         include three ~
404         include four ~
406 Move the cursor to the "o" of "one" and press CTRL-V.  Move it down with "3j"
407 to "four".  You now have a block selection that spans four lines.  Now type: >
409         Imain.<Esc>
411 The result:
413         include main.one ~
414         include main.two ~
415         include main.three ~
416         include main.four ~
418 If the block spans short lines that do not extend into the block, the text is
419 not inserted in that line.  For example, make a Visual block selection that
420 includes the word "long" in the first and last line of this text, and thus has
421 no text selected in the second line:
423         This is a long line ~
424         short ~
425         Any other long line ~
427                   ^^^^ selected block
429 Now use the command "Ivery <Esc>".  The result is:
431         This is a very long line ~
432         short ~
433         Any other very long line ~
435 In the short line no text was inserted.
437 If the string you insert contains a newline, the "I" acts just like a Normal
438 insert command and affects only the first line of the block.
440 The "A" command works the same way, except that it appends after the right
441 side of the block.  And it does insert text in a short line.  Thus you can
442 make a choice whether you do or don't want to append text to a short line.
443    There is one special case for "A": Select a Visual block and then use "$"
444 to make the block extend to the end of each line.  Using "A" now will append
445 the text to the end of each line.
446    Using the same example from above, and then typing "$A XXX<Esc>, you get
447 this result:
449         This is a long line XXX ~
450         short XXX ~
451         Any other long line XXX ~
453 This really requires using the "$" command.  Vim remembers that it was used.
454 Making the same selection by moving the cursor to the end of the longest line
455 with other movement commands will not have the same result.
458 CHANGING TEXT
460 The Visual block "c" command deletes the block and then throws you into Insert
461 mode to enable you to type in a string.  The string will be inserted in each
462 line in the block.
463    Starting with the same selection of the "long" words as above, then typing
464 "c_LONG_<Esc>", you get this:
466         This is a _LONG_ line ~
467         short ~
468         Any other _LONG_ line ~
470 Just like with "I" the short line is not changed.  Also, you can't enter a
471 newline in the new text.
473 The "C" command deletes text from the left edge of the block to the end of
474 line.  It then puts you in Insert mode so that you can type in a string,
475 which is added to the end of each line.
476    Starting with the same text again, and typing "Cnew text<Esc>" you get:
478         This is a new text ~
479         short ~
480         Any other new text ~
482 Notice that, even though only the "long" word was selected, the text after it
483 is deleted as well.  Thus only the location of the left edge of the visual
484 block really matters.
485    Again, short lines that do not reach into the block are excluded.
487 Other commands that change the characters in the block:
489         ~       swap case       (a -> A and A -> a)
490         U       make uppercase  (a -> A and A -> A)
491         u       make lowercase  (a -> a and A -> a)
494 FILLING WITH A CHARACTER
496 To fill the whole block with one character, use the "r" command.  Again,
497 starting with the same example text from above, and then typing "rx":
499         This is a xxxx line ~
500         short ~
501         Any other xxxx line ~
504         Note:
505         If you want to include characters beyond the end of the line in the
506         block, check out the 'virtualedit' feature in chapter 25.
509 SHIFTING
511 The command ">" shifts the selected text to the right one shift amount,
512 inserting whitespace.  The starting point for this shift is the left edge of
513 the visual block.
514    With the same example again, ">" gives this result:
516         This is a         long line ~
517         short ~
518         Any other         long line ~
520 The shift amount is specified with the 'shiftwidth' option.  To change it to
521 use 4 spaces: >
523         :set shiftwidth=4
525 The "<" command removes one shift amount of whitespace at the left
526 edge of the block.  This command is limited by the amount of text that is
527 there; so if there is less than a shift amount of whitespace available, it
528 removes what it can.
531 JOINING LINES
533 The "J" command joins all selected lines together into one line.  Thus it
534 removes the line breaks.  Actually, the line break, leading white space and
535 trailing white space is replaced by one space.  Two spaces are used after a
536 line ending (that can be changed with the 'joinspaces' option).
537    Let's use the example that we got so familiar with now.  The result of
538 using the "J" command:
540         This is a long line short Any other long line ~
542 The "J" command doesn't require a blockwise selection.  It works with "v" and
543 "V" selection in exactly the same way.
545 If you don't want the white space to be changed, use the "gJ" command.
547 ==============================================================================
548 *10.6*  Reading and writing part of a file
550 When you are writing an e-mail message, you may want to include another file.
551 This can be done with the ":read {filename}" command.  The text of the file is
552 put below the cursor line.
553    Starting with this text:
555         Hi John, ~
556         Here is the diff that fixes the bug: ~
557         Bye, Pierre. ~
559 Move the cursor to the second line and type: >
561         :read patch
563 The file named "patch" will be inserted, with this result:
565         Hi John, ~
566         Here is the diff that fixes the bug: ~
567         2c2 ~
568         <       for (i = 0; i <= length; ++i) ~
569         --- ~
570         >       for (i = 0; i < length; ++i) ~
571         Bye, Pierre. ~
573 The ":read" command accepts a range.  The file will be put below the last line
574 number of this range.  Thus ":$r patch" appends the file "patch" at the end of
575 the file.
576    What if you want to read the file above the first line?  This can be done
577 with the line number zero.  This line doesn't really exist, you will get an
578 error message when using it with most commands.  But this command is allowed:
580         :0read patch
582 The file "patch" will be put above the first line of the file.
585 WRITING A RANGE OF LINES
587 To write a range of lines to a file, the ":write" command can be used.
588 Without a range it writes the whole file.  With a range only the specified
589 lines are written: >
591         :.,$write tempo
593 This writes the lines from the cursor until the end of the file into the file
594 "tempo".  If this file already exists you will get an error message.  Vim
595 protects you from accidentally overwriting an existing file.  If you know what
596 you are doing and want to overwrite the file, append !: >
598         :.,$write! tempo
600 CAREFUL: The ! must follow the ":write" command immediately, without white
601 space.  Otherwise it becomes a filter command, which is explained later in
602 this chapter.
605 APPENDING TO A FILE
607 In the first section of this chapter was explained how to collect a number of
608 lines into a register.  The same can be done to collect lines in a file.
609 Write the first line with this command: >
611         :.write collection
613 Now move the cursor to the second line you want to collect, and type this: >
615         :.write >>collection
617 The ">>" tells Vim the "collection" file is not to be written as a new file,
618 but the line must be appended at the end.   You can repeat this as many times
619 as you like.
621 ==============================================================================
622 *10.7*  Formatting text
624 When you are typing plain text, it's nice if the length of each line is
625 automatically trimmed to fit in the window.  To make this happen while
626 inserting text, set the 'textwidth' option: >
628         :set textwidth=72
630 You might remember that in the example vimrc file this command was used for
631 every text file.  Thus if you are using that vimrc file, you were already
632 using it.  To check the current value of 'textwidth': >
634         :set textwidth
636 Now lines will be broken to take only up to 72 characters.  But when you
637 insert text halfway a line, or when you delete a few words, the lines will get
638 too long or too short.  Vim doesn't automatically reformat the text.
639    To tell Vim to format the current paragraph: >
641         gqap
643 This starts with the "gq" command, which is an operator.  Following is "ap",
644 the text object that stands for "a paragraph".  A paragraph is separated from
645 the next paragraph by an empty line.
647         Note:
648         A blank line, which contains white space, does NOT separate
649         paragraphs.  This is hard to notice!
651 Instead of "ap" you could use any motion or text object.  If your paragraphs
652 are properly separated, you can use this command to format the whole file: >
654         gggqG
656 "gg" takes you to the first line, "gq" is the format operator and "G" the
657 motion that jumps to the last line.
659 In case your paragraphs aren't clearly defined, you can format just the lines
660 you manually select.  Move the cursor to the first line you want to format.
661 Start with the command "gqj".  This formats the current line and the one below
662 it.  If the first line was short, words from the next line will be appended.
663 If it was too long, words will be moved to the next line.  The cursor moves to
664 the second line.  Now you can use "." to repeat the command.  Keep doing this
665 until you are at the end of the text you want to format.
667 ==============================================================================
668 *10.8*  Changing case
670 You have text with section headers in lowercase.  You want to make the word
671 "section" all uppercase.  Do this with the "gU" operator.  Start with the
672 cursor in the first column: >
674                              gUw
675 <       section header      ---->      SECTION header
677 The "gu" operator does exactly the opposite: >
679                              guw
680 <       SECTION header      ---->      section header
682 You can also use "g~" to swap case.  All these are operators, thus they work
683 with any motion command, with text objects and in Visual mode.
684    To make an operator work on lines you double it.  The delete operator is
685 "d", thus to delete a line you use "dd".  Similarly, "gugu" makes a whole line
686 lowercase.  This can be shortened to "guu".  "gUgU" is shortened to "gUU" and
687 "g~g~" to "g~~".  Example: >
689                                 g~~ 
690 <       Some GIRLS have Fun    ---->   sOME girls HAVE fUN ~
692 ==============================================================================
693 *10.9*  Using an external program
695 Vim has a very powerful set of commands, it can do anything.  But there may
696 still be something that an external command can do better or faster.
697    The command "!{motion}{program}" takes a block of text and filters it
698 through an external program.  In other words, it runs the system command
699 represented by {program}, giving it the block of text represented by {motion}
700 as input.  The output of this command then replaces the selected block.
701    Because this summarizes badly if you are unfamiliar with UNIX filters, take
702 a look at an example.  The sort command sorts a file.  If you execute the
703 following command, the unsorted file input.txt will be sorted and written to
704 output.txt.  (This works on both UNIX and Microsoft Windows.) >
706         sort <input.txt >output.txt
708 Now do the same thing in Vim.  You want to sort lines 1 through 5 of a file.
709 You start by putting the cursor on line 1.  Next you execute the following
710 command: >
712         !5G
714 The "!" tells Vim that you are performing a filter operation.  The Vim editor
715 expects a motion command to follow, indicating which part of the file to
716 filter.  The "5G" command tells Vim to go to line 5, so it now knows that it
717 is to filter lines 1 (the current line) through 5.
718    In anticipation of the filtering, the cursor drops to the bottom of the
719 screen and a ! prompt displays.  You can now type in the name of the filter
720 program, in this case "sort".  Therefore, your full command is as follows: >
722         !5Gsort<Enter>
724 The result is that the sort program is run on the first 5 lines.  The output
725 of the program replaces these lines.
727         line 55                       line 11
728         line 33                       line 22
729         line 11         -->           line 33
730         line 22                       line 44
731         line 44                       line 55
732         last line                     last line
734 The "!!" command filters the current line through a filter.  In Unix the "date"
735 command prints the current time and date.  "!!date<Enter>" replaces the current
736 line with the output of "date".  This is useful to add a timestamp to a file.
739 WHEN IT DOESN'T WORK
741 Starting a shell, sending it text and capturing the output requires that Vim
742 knows how the shell works exactly.  When you have problems with filtering,
743 check the values of these options:
745         'shell'         specifies the program that Vim uses to execute
746                         external programs.
747         'shellcmdflag'  argument to pass a command to the shell
748         'shellquote'    quote to be used around the command
749         'shellxquote'   quote to be used around the command and redirection
750         'shelltype'     kind of shell (only for the Amiga)
751         'shellslash'    use forward slashes in the command (only for
752                         MS-Windows and alikes)
753         'shellredir'    string used to write the command output into a file
755 On Unix this is hardly ever a problem, because there are two kinds of shells:
756 "sh" like and "csh" like.  Vim checks the 'shell' option and sets related
757 options automatically, depending on whether it sees "csh" somewhere in
758 'shell'.
759    On MS-Windows, however, there are many different shells and you might have
760 to tune the options to make filtering work.  Check the help for the options
761 for more information.
764 READING COMMAND OUTPUT
766 To read the contents of the current directory into the file, use this:
768 on Unix: >
769         :read !ls
770 on MS-Windows: >
771         :read !dir
773 The output of the "ls" or "dir" command is captured and inserted in the text,
774 below the cursor.  This is similar to reading a file, except that the "!" is
775 used to tell Vim that a command follows.
776    The command may have arguments.  And a range can be used to tell where Vim
777 should put the lines: >
779         :0read !date -u
781 This inserts the current time and date in UTC format at the top of the file.
782 (Well, if you have a date command that accepts the "-u" argument.)  Note the
783 difference with using "!!date": that replaced a line, while ":read !date" will
784 insert a line.
787 WRITING TEXT TO A COMMAND
789 The Unix command "wc" counts words.  To count the words in the current file: >
791         :write !wc
793 This is the same write command as before, but instead of a file name the "!"
794 character is used and the name of an external command.  The written text will
795 be passed to the specified command as its standard input.  The output could
796 look like this:
798        4      47     249 ~
800 The "wc" command isn't verbose.  This means you have 4 lines, 47 words and 249
801 characters.
803 Watch out for this mistake: >
805         :write! wc
807 This will write the file "wc" in the current directory, with force.  White
808 space is important here!
811 REDRAWING THE SCREEN
813 If the external command produced an error message, the display may have been
814 messed up.  Vim is very efficient and only redraws those parts of the screen
815 that it knows need redrawing.  But it can't know about what another program
816 has written.  To tell Vim to redraw the screen: >
818         CTRL-L
820 ==============================================================================
822 Next chapter: |usr_11.txt|  Recovering from a crash
824 Copyright: see |manual-copyright|  vim:tw=78:ts=8:ft=help:norl: