236
|
1 *usr_25.txt* For Vim version 7.0aa. Last change: 2005 Apr 01
|
7
|
2
|
|
3 VIM USER MANUAL - by Bram Moolenaar
|
|
4
|
|
5 Editing formatted text
|
|
6
|
|
7
|
|
8 Text hardly ever comes in one sentence per line. This chapter is about
|
|
9 breaking sentences to make them fit on a page and other formatting.
|
|
10 Vim also has useful features for editing single-line paragraphs and tables.
|
|
11
|
|
12 |25.1| Breaking lines
|
|
13 |25.2| Aligning text
|
|
14 |25.3| Indents and tabs
|
|
15 |25.4| Dealing with long lines
|
|
16 |25.5| Editing tables
|
|
17
|
|
18 Next chapter: |usr_26.txt| Repeating
|
|
19 Previous chapter: |usr_24.txt| Inserting quickly
|
|
20 Table of contents: |usr_toc.txt|
|
|
21
|
|
22 ==============================================================================
|
|
23 *25.1* Breaking lines
|
|
24
|
|
25 Vim has a number of functions that make dealing with text easier. By default,
|
|
26 the editor does not perform automatic line breaks. In other words, you have
|
|
27 to press <Enter> yourself. This is useful when you are writing programs where
|
|
28 you want to decide where the line ends. It is not so good when you are
|
|
29 creating documentation and want the text to be at most 70 character wide.
|
|
30 If you set the 'textwidth' option, Vim automatically inserts line breaks.
|
|
31 Suppose, for example, that you want a very narrow column of only 30
|
|
32 characters. You need to execute the following command: >
|
|
33
|
|
34 :set textwidth=30
|
|
35
|
|
36 Now you start typing (ruler added):
|
|
37
|
|
38 1 2 3
|
|
39 12345678901234567890123456789012345
|
|
40 I taught programming for a whi ~
|
|
41
|
|
42 If you type "l" next, this makes the line longer than the 30-character limit.
|
|
43 When Vim sees this, it inserts a line break and you get the following:
|
|
44
|
|
45 1 2 3
|
|
46 12345678901234567890123456789012345
|
|
47 I taught programming for a ~
|
|
48 whil ~
|
|
49
|
|
50 Continuing on, you can type in the rest of the paragraph:
|
|
51
|
|
52 1 2 3
|
|
53 12345678901234567890123456789012345
|
|
54 I taught programming for a ~
|
|
55 while. One time, I was stopped ~
|
|
56 by the Fort Worth police, ~
|
|
57 because my homework was too ~
|
|
58 hard. True story. ~
|
|
59
|
|
60 You do not have to type newlines; Vim puts them in automatically.
|
|
61
|
|
62 Note:
|
|
63 The 'wrap' option makes Vim display lines with a line break, but this
|
|
64 doesn't insert a line break in the file.
|
|
65
|
|
66
|
|
67 REFORMATTING
|
|
68
|
|
69 The Vim editor is not a word processor. In a word processor, if you delete
|
|
70 something at the beginning of the paragraph, the line breaks are reworked. In
|
|
71 Vim they are not; so if you delete the word "programming" from the first line,
|
|
72 all you get is a short line:
|
|
73
|
|
74 1 2 3
|
|
75 12345678901234567890123456789012345
|
|
76 I taught for a ~
|
|
77 while. One time, I was stopped ~
|
|
78 by the Fort Worth police, ~
|
|
79 because my homework was too ~
|
|
80 hard. True story. ~
|
|
81
|
|
82 This does not look good. To get the paragraph into shape you use the "gq"
|
|
83 operator.
|
|
84 Let's first use this with a Visual selection. Starting from the first
|
|
85 line, type: >
|
|
86
|
|
87 v4jgq
|
|
88
|
|
89 "v" to start Visual mode, "4j' to move to the end of the paragraph and then
|
|
90 the "gq" operator. The result is:
|
|
91
|
|
92 1 2 3
|
|
93 12345678901234567890123456789012345
|
|
94 I taught for a while. One ~
|
|
95 time, I was stopped by the ~
|
|
96 Fort Worth police, because my ~
|
|
97 homework was too hard. True ~
|
|
98 story. ~
|
|
99
|
|
100 Note: there is a way to do automatic formatting for specific types of text
|
|
101 layouts, see |auto-format|.
|
|
102
|
|
103 Since "gq" is an operator, you can use one of the three ways to select the
|
|
104 text it works on: With Visual mode, with a movement and with a text object.
|
|
105 The example above could also be done with "gq4j". That's less typing, but
|
|
106 you have to know the line count. A more useful motion command is "}". This
|
|
107 moves to the end of a paragraph. Thus "gq}" formats from the cursor to the
|
|
108 end of the current paragraph.
|
|
109 A very useful text object to use with "gq" is the paragraph. Try this: >
|
|
110
|
|
111 gqap
|
|
112
|
|
113 "ap" stands for "a-paragraph". This formats the text of one paragraph
|
|
114 (separated by empty lines). Also the part before the cursor.
|
|
115 If you have your paragraphs separated by empty lines, you can format the
|
|
116 whole file by typing this: >
|
|
117
|
|
118 gggqG
|
|
119
|
|
120 "gg" to move to the first line, "gqG" to format until the last line.
|
|
121 Warning: If your paragraphs are not properly separated, they will be joined
|
|
122 together. A common mistake is to have a line with a space or Tab. That's a
|
|
123 blank line, but not an empty line.
|
|
124
|
|
125 Vim is able format more than just plain text. See |fo-table| for how to
|
|
126 change this. See the 'joinspaces' option to change the number of spaces used
|
|
127 after a full stop.
|
|
128 It is possible to use an external program for formatting. This is useful
|
|
129 if your text can't be properly formatted with Vim's builtin command. See the
|
|
130 'formatprg' option.
|
|
131
|
|
132 ==============================================================================
|
|
133 *25.2* Aligning text
|
|
134
|
|
135 To center a range of lines, use the following command: >
|
|
136
|
|
137 :{range}center [width]
|
|
138
|
|
139 {range} is the usual command-line range. [width] is an optional line width to
|
|
140 use for centering. If [width] is not specified, it defaults to the value of
|
|
141 'textwidth'. (If 'textwidth' is 0, the default is 80.)
|
|
142 For example: >
|
|
143
|
|
144 :1,5center 40
|
|
145
|
|
146 results in the following:
|
|
147
|
|
148 I taught for a while. One ~
|
|
149 time, I was stopped by the ~
|
|
150 Fort Worth police, because my ~
|
|
151 homework was too hard. True ~
|
|
152 story. ~
|
|
153
|
|
154
|
|
155 RIGHT ALIGNMENT
|
|
156
|
|
157 Similarly, the ":right" command right-justifies the text: >
|
|
158
|
|
159 :1,5right 37
|
|
160
|
|
161 gives this result:
|
|
162
|
|
163 I taught for a while. One ~
|
|
164 time, I was stopped by the ~
|
|
165 Fort Worth police, because my ~
|
|
166 homework was too hard. True ~
|
|
167 story. ~
|
|
168
|
|
169 LEFT ALIGNMENT
|
|
170
|
|
171 Finally there is this command: >
|
|
172
|
|
173 :{range}left [margin]
|
|
174
|
|
175 Unlike ":center" and ":right", however, the argument to ":left" is not the
|
|
176 length of the line. Instead it is the left margin. If it is omitted, the
|
|
177 text will be put against the left side of the screen (using a zero margin
|
|
178 would do the same). If it is 5, the text will be indented 5 spaces. For
|
|
179 example, use these commands: >
|
|
180
|
|
181 :1left 5
|
|
182 :2,5left
|
|
183
|
|
184 This results in the following:
|
|
185
|
|
186 I taught for a while. One ~
|
|
187 time, I was stopped by the ~
|
|
188 Fort Worth police, because my ~
|
|
189 homework was too hard. True ~
|
|
190 story. ~
|
|
191
|
|
192
|
|
193 JUSTIFYING TEXT
|
|
194
|
|
195 Vim has no built-in way of justifying text. However, there is a neat macro
|
|
196 package that does the job. To use this package, execute the following
|
|
197 command: >
|
|
198
|
|
199 :runtime macros/justify.vim
|
|
200
|
236
|
201 This Vim script file defines a new visual command "_j". To justify a block of
|
7
|
202 text, highlight the text in Visual mode and then execute "_j".
|
|
203 Look in the file for more explanations. To go there, do "gf" on this name:
|
|
204 $VIMRUNTIME/macros/justify.vim.
|
|
205
|
|
206 An alternative is to filter the text through an external program. Example: >
|
|
207
|
|
208 :%!fmt
|
|
209
|
|
210 ==============================================================================
|
|
211 *25.3* Indents and tabs
|
|
212
|
|
213 Indents can be used to make text stand out from the rest. The example texts
|
|
214 in this manual, for example, are indented by eight spaces or a tab. You would
|
|
215 normally enter this by typing a tab at the start of each line. Take this
|
|
216 text:
|
|
217 the first line ~
|
|
218 the second line ~
|
|
219
|
|
220 This is entered by typing a tab, some text, <Enter>, tab and more text.
|
|
221 The 'autoindent' option inserts indents automatically: >
|
|
222
|
|
223 :set autoindent
|
|
224
|
|
225 When a new line is started it gets the same indent as the previous line. In
|
|
226 the above example, the tab after the <Enter> is not needed anymore.
|
|
227
|
|
228
|
|
229 INCREASING INDENT
|
|
230
|
|
231 To increase the amount of indent in a line, use the ">" operator. Often this
|
|
232 is used as ">>", which adds indent to the current line.
|
|
233 The amount of indent added is specified with the 'shiftwidth' option. The
|
|
234 default value is 8. To make ">>" insert four spaces worth of indent, for
|
|
235 example, type this: >
|
|
236
|
|
237 :set shiftwidth=4
|
|
238
|
|
239 When used on the second line of the example text, this is what you get:
|
|
240
|
|
241 the first line ~
|
|
242 the second line ~
|
|
243
|
|
244 "4>>" will increase the indent of four lines.
|
|
245
|
|
246
|
|
247 TABSTOP
|
|
248
|
|
249 If you want to make indents a multiple of 4, you set 'shiftwidth' to 4. But
|
|
250 when pressing a Tab you still get 8 spaces worth of indent. To change this,
|
|
251 set the 'softtabstop' option: >
|
|
252
|
|
253 :set softtabstop=4
|
|
254
|
|
255 This will make the <Tab> key insert 4 spaces worth of indent. If there are
|
|
256 already four spaces, a <Tab> character is used (saving seven characters in the
|
|
257 file). (If you always want spaces and no tab characters, set the 'expandtab'
|
|
258 option.)
|
|
259
|
|
260 Note:
|
|
261 You could set the 'tabstop' option to 4. However, if you edit the
|
|
262 file another time, with 'tabstop' set to the default value of 8, it
|
|
263 will look wrong. In other programs and when printing the indent will
|
|
264 also be wrong. Therefore it is recommended to keep 'tabstop' at eight
|
|
265 all the time. That's the standard value everywhere.
|
|
266
|
|
267
|
|
268 CHANGING TABS
|
|
269
|
|
270 You edit a file which was written with a tabstop of 3. In Vim it looks ugly,
|
|
271 because it uses the normal tabstop value of 8. You can fix this by setting
|
|
272 'tabstop' to 3. But you have to do this every time you edit this file.
|
|
273 Vim can change the use of tabstops in your file. First, set 'tabstop' to
|
|
274 make the indents look good, then use the ":retab" command: >
|
|
275
|
|
276 :set tabstop=3
|
|
277 :retab 8
|
|
278
|
|
279 The ":retab" command will change 'tabstop' to 8, while changing the text such
|
|
280 that it looks the same. It changes spans of white space into tabs and spaces
|
|
281 for this. You can now write the file. Next time you edit it the indents will
|
|
282 be right without setting an option.
|
|
283 Warning: When using ":retab" on a program, it may change white space inside
|
|
284 a string constant. Therefore it's a good habit to use "\t" instead of a
|
|
285 real tab.
|
|
286
|
|
287 ==============================================================================
|
|
288 *25.4* Dealing with long lines
|
|
289
|
|
290 Sometimes you will be editing a file that is wider than the number of columns
|
|
291 in the window. When that occurs, Vim wraps the lines so that everything fits
|
|
292 on the screen.
|
|
293 If you switch the 'wrap' option off, each line in the file shows up as one
|
|
294 line on the screen. Then the ends of the long lines disappear off the screen
|
|
295 to the right.
|
|
296 When you move the cursor to a character that can't be seen, Vim will scroll
|
|
297 the text to show it. This is like moving a viewport over the text in the
|
|
298 horizontal direction.
|
|
299 By default, Vim does not display a horizontal scrollbar in the GUI. If you
|
|
300 want to enable one, use the following command: >
|
|
301
|
|
302 :set guioptions+=b
|
|
303
|
|
304 One horizontal scrollbar will appear at the bottom of the Vim window.
|
|
305
|
|
306 If you don't have a scrollbar or don't want to use it, use these commands to
|
|
307 scroll the text. The cursor will stay in the same place, but it's move back
|
|
308 into the visible text if necessary.
|
|
309
|
|
310 zh scroll right
|
|
311 4zh scroll four characters right
|
|
312 zH scroll half a window width right
|
|
313 ze scroll right to put the cursor at the end
|
|
314 zl scroll left
|
|
315 4zl scroll four characters left
|
|
316 zL scroll half a window width left
|
|
317 zs scroll left to put the cursor at the start
|
|
318
|
|
319 Let's attempt to show this with one line of text. The cursor is on the "w" of
|
|
320 "which". The "current window" above the line indicates the text that is
|
|
321 currently visible. The "window"s below the text indicate the text that is
|
|
322 visible after the command left of it.
|
|
323
|
|
324 |<-- current window -->|
|
|
325 some long text, part of which is visible in the window ~
|
|
326 ze |<-- window -->|
|
|
327 zH |<-- window -->|
|
|
328 4zh |<-- window -->|
|
|
329 zh |<-- window -->|
|
|
330 zl |<-- window -->|
|
|
331 4zl |<-- window -->|
|
|
332 zL |<-- window -->|
|
|
333 zs |<-- window -->|
|
|
334
|
|
335
|
|
336 MOVING WITH WRAP OFF
|
|
337
|
|
338 When 'wrap' is off and the text has scrolled horizontally, you can use the
|
|
339 following commands to move the cursor to a character you can see. Thus text
|
|
340 left and right of the window is ignored. These never cause the text to
|
|
341 scroll:
|
|
342
|
|
343 g0 to first visible character in this line
|
|
344 g^ to first non-blank visible character in this line
|
|
345 gm to middle of this line
|
|
346 g$ to last visible character in this line
|
|
347
|
|
348 |<-- window -->|
|
|
349 some long text, part of which is visible ~
|
|
350 g0 g^ gm g$
|
|
351
|
|
352
|
|
353 BREAKING AT WORDS *edit-no-break*
|
|
354
|
|
355 When preparing text for use by another program, you might have to make
|
|
356 paragraphs without a line break. A disadvantage of using 'nowrap' is that you
|
|
357 can't see the whole sentence you are working on. When 'wrap' is on, words are
|
|
358 broken halfway, which makes them hard to read.
|
|
359 A good solution for editing this kind of paragraph is setting the
|
|
360 'linebreak' option. Vim then breaks lines at an appropriate place when
|
|
361 displaying the line. The text in the file remains unchanged.
|
|
362 Without 'linebreak' text might look like this:
|
|
363
|
|
364 +---------------------------------+
|
|
365 |letter generation program for a b|
|
|
366 |ank. They wanted to send out a s|
|
|
367 |pecial, personalized letter to th|
|
|
368 |eir richest 1000 customers. Unfo|
|
|
369 |rtunately for the programmer, he |
|
|
370 +---------------------------------+
|
|
371 After: >
|
|
372
|
|
373 :set linebreak
|
|
374
|
|
375 it looks like this:
|
|
376
|
|
377 +---------------------------------+
|
|
378 |letter generation program for a |
|
|
379 |bank. They wanted to send out a |
|
|
380 |special, personalized letter to |
|
|
381 |their richest 1000 customers. |
|
|
382 |Unfortunately for the programmer,|
|
|
383 +---------------------------------+
|
|
384
|
|
385 Related options:
|
|
386 'breakat' specifies the characters where a break can be inserted.
|
|
387 'showbreak' specifies a string to show at the start of broken line.
|
|
388 Set 'textwidth' to zero to avoid a paragraph to be split.
|
|
389
|
|
390
|
|
391 MOVING BY VISIBLE LINES
|
|
392
|
|
393 The "j" and "k" commands move to the next and previous lines. When used on
|
|
394 a long line, this means moving a lot of screen lines at once.
|
|
395 To move only one screen line, use the "gj" and "gk" commands. When a line
|
|
396 doesn't wrap they do the same as "j" and "k". When the line does wrap, they
|
|
397 move to a character displayed one line below or above.
|
|
398 You might like to use these mappings, which bind these movement commands to
|
|
399 the cursor keys: >
|
|
400
|
|
401 :map <Up> gk
|
|
402 :map <Down> gj
|
|
403
|
|
404
|
|
405 TURNING A PARAGRAPH INTO ONE LINE
|
|
406
|
|
407 If you want to import text into a program like MS-Word, each paragraph should
|
|
408 be a single line. If your paragraphs are currently separated with empty
|
|
409 lines, this is how you turn each paragraph into a single line: >
|
|
410
|
|
411 :g/./,/^$/join
|
|
412
|
|
413 That looks complicated. Let's break it up in pieces:
|
|
414
|
|
415 :g/./ A ":global" command that finds all lines that contain
|
|
416 at least one character.
|
|
417 ,/^$/ A range, starting from the current line (the non-empty
|
|
418 line) until an empty line.
|
|
419 join The ":join" command joins the range of lines together
|
|
420 into one line.
|
|
421
|
|
422 Starting with this text, containing eight lines broken at column 30:
|
|
423
|
|
424 +----------------------------------+
|
|
425 |A letter generation program |
|
|
426 |for a bank. They wanted to |
|
|
427 |send out a special, |
|
|
428 |personalized letter. |
|
|
429 | |
|
|
430 |To their richest 1000 |
|
|
431 |customers. Unfortunately for |
|
|
432 |the programmer, |
|
|
433 +----------------------------------+
|
|
434
|
|
435 You end up with two lines:
|
|
436
|
|
437 +----------------------------------+
|
|
438 |A letter generation program for a |
|
|
439 |bank. They wanted to send out a s|
|
|
440 |pecial, personalized letter. |
|
|
441 |To their richest 1000 customers. |
|
|
442 |Unfortunately for the programmer, |
|
|
443 +----------------------------------+
|
|
444
|
|
445 Note that this doesn't work when the separating line is blank but not empty;
|
|
446 when it contains spaces and/or tabs. This command does work with blank lines:
|
|
447 >
|
|
448 :g/\S/,/^\s*$/join
|
|
449
|
|
450 This still requires a blank or empty line at the end of the file for the last
|
|
451 paragraph to be joined.
|
|
452
|
|
453 ==============================================================================
|
|
454 *25.5* Editing tables
|
|
455
|
|
456 Suppose you are editing a table with four columns:
|
|
457
|
|
458 nice table test 1 test 2 test 3 ~
|
|
459 input A 0.534 ~
|
|
460 input B 0.913 ~
|
|
461
|
|
462 You need to enter numbers in the third column. You could move to the second
|
|
463 line, use "A", enter a lot of spaces and type the text.
|
|
464 For this kind of editing there is a special option: >
|
|
465
|
|
466 set virtualedit=all
|
|
467
|
|
468 Now you can move the cursor to positions where there isn't any text. This is
|
|
469 called "virtual space". Editing a table is a lot easier this way.
|
|
470 Move the cursor by searching for the header of the last column: >
|
|
471
|
|
472 /test 3
|
|
473
|
|
474 Now press "j" and you are right where you can enter the value for "input A".
|
|
475 Typing "0.693" results in:
|
|
476
|
|
477 nice table test 1 test 2 test 3 ~
|
|
478 input A 0.534 0.693 ~
|
|
479 input B 0.913 ~
|
|
480
|
|
481 Vim has automatically filled the gap in front of the new text for you. Now,
|
|
482 to enter the next field in this column use "Bj". "B" moves back to the start
|
|
483 of a white space separated word. Then "j" moves to the place where the next
|
|
484 field can be entered.
|
|
485
|
|
486 Note:
|
|
487 You can move the cursor anywhere in the display, also beyond the end
|
|
488 of a line. But Vim will not insert spaces there, until you insert a
|
|
489 character in that position.
|
|
490
|
|
491
|
|
492 COPYING A COLUMN
|
|
493
|
|
494 You want to add a column, which should be a copy of the third column and
|
|
495 placed before the "test 1" column. Do this in seven steps:
|
|
496 1. Move the cursor to the left upper corner of this column, e.g., with
|
|
497 "/test 3".
|
|
498 2. Press CTRL-V to start blockwise Visual mode.
|
|
499 3. Move the cursor down two lines with "2j". You are now in "virtual space":
|
|
500 the "input B" line of the "test 3" column.
|
|
501 4. Move the cursor right, to include the whole column in the selection, plus
|
|
502 the space that you want between the columns. "9l" should do it.
|
|
503 5. Yank the selected rectangle with "y".
|
|
504 6. Move the cursor to "test 1", where the new column must be placed.
|
|
505 7. Press "P".
|
|
506
|
|
507 The result should be:
|
|
508
|
|
509 nice table test 3 test 1 test 2 test 3 ~
|
|
510 input A 0.693 0.534 0.693 ~
|
|
511 input B 0.913 ~
|
|
512
|
|
513 Notice that the whole "test 1" column was shifted right, also the line where
|
|
514 the "test 3" column didn't have text.
|
|
515
|
|
516 Go back to non-virtual cursor movements with: >
|
|
517
|
|
518 :set virtualedit=
|
|
519
|
|
520
|
|
521 VIRTUAL REPLACE MODE
|
|
522
|
|
523 The disadvantage of using 'virtualedit' is that it "feels" different. You
|
|
524 can't recognize tabs or spaces beyond the end of line when moving the cursor
|
|
525 around. Another method can be used: Virtual Replace mode.
|
|
526 Suppose you have a line in a table that contains both tabs and other
|
|
527 characters. Use "rx" on the first tab:
|
|
528
|
|
529 inp 0.693 0.534 0.693 ~
|
|
530
|
|
531 |
|
|
532 rx |
|
|
533 V
|
|
534
|
|
535 inpx0.693 0.534 0.693 ~
|
|
536
|
|
537 The layout is messed up. To avoid that, use the "gr" command:
|
|
538
|
|
539 inp 0.693 0.534 0.693 ~
|
|
540
|
|
541 |
|
|
542 grx |
|
|
543 V
|
|
544
|
|
545 inpx 0.693 0.534 0.693 ~
|
|
546
|
|
547 What happens is that the "gr" command makes sure the new character takes the
|
|
548 right amount of screen space. Extra spaces or tabs are inserted to fill the
|
|
549 gap. Thus what actually happens is that a tab is replaced by "x" and then
|
|
550 blanks added to make the text after it keep it's place. In this case a
|
|
551 tab is inserted.
|
|
552 When you need to replace more than one character, you use the "R" command
|
|
553 to go to Replace mode (see |04.9|). This messes up the layout and replaces
|
|
554 the wrong characters:
|
|
555
|
|
556 inp 0 0.534 0.693 ~
|
|
557
|
|
558 |
|
|
559 R0.786 |
|
|
560 V
|
|
561
|
|
562 inp 0.78634 0.693 ~
|
|
563
|
|
564 The "gR" command uses Virtual Replace mode. This preserves the layout:
|
|
565
|
|
566 inp 0 0.534 0.693 ~
|
|
567
|
|
568 |
|
|
569 gR0.786 |
|
|
570 V
|
|
571
|
|
572 inp 0.786 0.534 0.693 ~
|
|
573
|
|
574 ==============================================================================
|
|
575
|
|
576 Next chapter: |usr_26.txt| Repeating
|
|
577
|
|
578 Copyright: see |manual-copyright| vim:tw=78:ts=8:ft=help:norl:
|