Mercurial > vim
annotate runtime/doc/usr_25.txt @ 7726:f6311c321411 v7.4.1161
commit https://github.com/vim/vim/commit/2faa29f896252073b53f387406109e331fbbe5f8
Author: Bram Moolenaar <Bram@vim.org>
Date: Sat Jan 23 23:02:34 2016 +0100
patch 7.4.1161
Problem: ":argadd" without argument is supposed to add the current buffer
name to the arglist.
Solution: Make it work as documented. (Coot, closes https://github.com/vim/vim/issues/577)
author | Christian Brabandt <cb@256bit.org> |
---|---|
date | Sat, 23 Jan 2016 23:15:05 +0100 |
parents | 4abac79c0b7a |
children | aba2d0a01290 |
rev | line source |
---|---|
6336 | 1 *usr_25.txt* For Vim version 7.4. Last change: 2014 Oct 29 |
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 | |
5400 | 89 "v" to start Visual mode, "4j" to move to the end of the paragraph and then |
7 | 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 | |
1256 | 122 together. A common mistake is to have a line with a space or tab. That's a |
7 | 123 blank line, but not an empty line. |
124 | |
1121 | 125 Vim is able to format more than just plain text. See |fo-table| for how to |
7 | 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 | |
1256 | 250 when pressing a <Tab> you still get 8 spaces worth of indent. To change this, |
7 | 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 | |
2033
de5a43c5eedc
Update documentation files.
Bram Moolenaar <bram@zimbu.org>
parents:
1702
diff
changeset
|
307 scroll the text. The cursor will stay in the same place, but it's moved back |
7 | 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 | |
6336 | 405 TURNING A PARAGRAPH INTO ONE LINE *edit-paragraph-join* |
7 | 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 | |
2033
de5a43c5eedc
Update documentation files.
Bram Moolenaar <bram@zimbu.org>
parents:
1702
diff
changeset
|
550 blanks added to make the text after it keep its place. In this case a |
7 | 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: |