| *usr_25.txt* For Vim version 7.4. Last change: 2014 Oct 29 |
| |
| VIM USER MANUAL - by Bram Moolenaar |
| |
| Editing formatted text |
| |
| |
| Text hardly ever comes in one sentence per line. This chapter is about |
| breaking sentences to make them fit on a page and other formatting. |
| Vim also has useful features for editing single-line paragraphs and tables. |
| |
| |25.1| Breaking lines |
| |25.2| Aligning text |
| |25.3| Indents and tabs |
| |25.4| Dealing with long lines |
| |25.5| Editing tables |
| |
| Next chapter: |usr_26.txt| Repeating |
| Previous chapter: |usr_24.txt| Inserting quickly |
| Table of contents: |usr_toc.txt| |
| |
| ============================================================================== |
| *25.1* Breaking lines |
| |
| Vim has a number of functions that make dealing with text easier. By default, |
| the editor does not perform automatic line breaks. In other words, you have |
| to press <Enter> yourself. This is useful when you are writing programs where |
| you want to decide where the line ends. It is not so good when you are |
| creating documentation and want the text to be at most 70 character wide. |
| If you set the 'textwidth' option, Vim automatically inserts line breaks. |
| Suppose, for example, that you want a very narrow column of only 30 |
| characters. You need to execute the following command: > |
| |
| :set textwidth=30 |
| |
| Now you start typing (ruler added): |
| |
| 1 2 3 |
| 12345678901234567890123456789012345 |
| I taught programming for a whi ~ |
| |
| If you type "l" next, this makes the line longer than the 30-character limit. |
| When Vim sees this, it inserts a line break and you get the following: |
| |
| 1 2 3 |
| 12345678901234567890123456789012345 |
| I taught programming for a ~ |
| whil ~ |
| |
| Continuing on, you can type in the rest of the paragraph: |
| |
| 1 2 3 |
| 12345678901234567890123456789012345 |
| I taught programming for a ~ |
| while. One time, I was stopped ~ |
| by the Fort Worth police, ~ |
| because my homework was too ~ |
| hard. True story. ~ |
| |
| You do not have to type newlines; Vim puts them in automatically. |
| |
| Note: |
| The 'wrap' option makes Vim display lines with a line break, but this |
| doesn't insert a line break in the file. |
| |
| |
| REFORMATTING |
| |
| The Vim editor is not a word processor. In a word processor, if you delete |
| something at the beginning of the paragraph, the line breaks are reworked. In |
| Vim they are not; so if you delete the word "programming" from the first line, |
| all you get is a short line: |
| |
| 1 2 3 |
| 12345678901234567890123456789012345 |
| I taught for a ~ |
| while. One time, I was stopped ~ |
| by the Fort Worth police, ~ |
| because my homework was too ~ |
| hard. True story. ~ |
| |
| This does not look good. To get the paragraph into shape you use the "gq" |
| operator. |
| Let's first use this with a Visual selection. Starting from the first |
| line, type: > |
| |
| v4jgq |
| |
| "v" to start Visual mode, "4j" to move to the end of the paragraph and then |
| the "gq" operator. The result is: |
| |
| 1 2 3 |
| 12345678901234567890123456789012345 |
| I taught for a while. One ~ |
| time, I was stopped by the ~ |
| Fort Worth police, because my ~ |
| homework was too hard. True ~ |
| story. ~ |
| |
| Note: there is a way to do automatic formatting for specific types of text |
| layouts, see |auto-format|. |
| |
| Since "gq" is an operator, you can use one of the three ways to select the |
| text it works on: With Visual mode, with a movement and with a text object. |
| The example above could also be done with "gq4j". That's less typing, but |
| you have to know the line count. A more useful motion command is "}". This |
| moves to the end of a paragraph. Thus "gq}" formats from the cursor to the |
| end of the current paragraph. |
| A very useful text object to use with "gq" is the paragraph. Try this: > |
| |
| gqap |
| |
| "ap" stands for "a-paragraph". This formats the text of one paragraph |
| (separated by empty lines). Also the part before the cursor. |
| If you have your paragraphs separated by empty lines, you can format the |
| whole file by typing this: > |
| |
| gggqG |
| |
| "gg" to move to the first line, "gqG" to format until the last line. |
| Warning: If your paragraphs are not properly separated, they will be joined |
| together. A common mistake is to have a line with a space or tab. That's a |
| blank line, but not an empty line. |
| |
| Vim is able to format more than just plain text. See |fo-table| for how to |
| change this. See the 'joinspaces' option to change the number of spaces used |
| after a full stop. |
| It is possible to use an external program for formatting. This is useful |
| if your text can't be properly formatted with Vim's builtin command. See the |
| 'formatprg' option. |
| |
| ============================================================================== |
| *25.2* Aligning text |
| |
| To center a range of lines, use the following command: > |
| |
| :{range}center [width] |
| |
| {range} is the usual command-line range. [width] is an optional line width to |
| use for centering. If [width] is not specified, it defaults to the value of |
| 'textwidth'. (If 'textwidth' is 0, the default is 80.) |
| For example: > |
| |
| :1,5center 40 |
| |
| results in the following: |
| |
| I taught for a while. One ~ |
| time, I was stopped by the ~ |
| Fort Worth police, because my ~ |
| homework was too hard. True ~ |
| story. ~ |
| |
| |
| RIGHT ALIGNMENT |
| |
| Similarly, the ":right" command right-justifies the text: > |
| |
| :1,5right 37 |
| |
| gives this result: |
| |
| I taught for a while. One ~ |
| time, I was stopped by the ~ |
| Fort Worth police, because my ~ |
| homework was too hard. True ~ |
| story. ~ |
| |
| LEFT ALIGNMENT |
| |
| Finally there is this command: > |
| |
| :{range}left [margin] |
| |
| Unlike ":center" and ":right", however, the argument to ":left" is not the |
| length of the line. Instead it is the left margin. If it is omitted, the |
| text will be put against the left side of the screen (using a zero margin |
| would do the same). If it is 5, the text will be indented 5 spaces. For |
| example, use these commands: > |
| |
| :1left 5 |
| :2,5left |
| |
| This results in the following: |
| |
| I taught for a while. One ~ |
| time, I was stopped by the ~ |
| Fort Worth police, because my ~ |
| homework was too hard. True ~ |
| story. ~ |
| |
| |
| JUSTIFYING TEXT |
| |
| Vim has no built-in way of justifying text. However, there is a neat macro |
| package that does the job. To use this package, execute the following |
| command: > |
| |
| :runtime macros/justify.vim |
| |
| This Vim script file defines a new visual command "_j". To justify a block of |
| text, highlight the text in Visual mode and then execute "_j". |
| Look in the file for more explanations. To go there, do "gf" on this name: |
| $VIMRUNTIME/macros/justify.vim. |
| |
| An alternative is to filter the text through an external program. Example: > |
| |
| :%!fmt |
| |
| ============================================================================== |
| *25.3* Indents and tabs |
| |
| Indents can be used to make text stand out from the rest. The example texts |
| in this manual, for example, are indented by eight spaces or a tab. You would |
| normally enter this by typing a tab at the start of each line. Take this |
| text: |
| the first line ~ |
| the second line ~ |
| |
| This is entered by typing a tab, some text, <Enter>, tab and more text. |
| The 'autoindent' option inserts indents automatically: > |
| |
| :set autoindent |
| |
| When a new line is started it gets the same indent as the previous line. In |
| the above example, the tab after the <Enter> is not needed anymore. |
| |
| |
| INCREASING INDENT |
| |
| To increase the amount of indent in a line, use the ">" operator. Often this |
| is used as ">>", which adds indent to the current line. |
| The amount of indent added is specified with the 'shiftwidth' option. The |
| default value is 8. To make ">>" insert four spaces worth of indent, for |
| example, type this: > |
| |
| :set shiftwidth=4 |
| |
| When used on the second line of the example text, this is what you get: |
| |
| the first line ~ |
| the second line ~ |
| |
| "4>>" will increase the indent of four lines. |
| |
| |
| TABSTOP |
| |
| If you want to make indents a multiple of 4, you set 'shiftwidth' to 4. But |
| when pressing a <Tab> you still get 8 spaces worth of indent. To change this, |
| set the 'softtabstop' option: > |
| |
| :set softtabstop=4 |
| |
| This will make the <Tab> key insert 4 spaces worth of indent. If there are |
| already four spaces, a <Tab> character is used (saving seven characters in the |
| file). (If you always want spaces and no tab characters, set the 'expandtab' |
| option.) |
| |
| Note: |
| You could set the 'tabstop' option to 4. However, if you edit the |
| file another time, with 'tabstop' set to the default value of 8, it |
| will look wrong. In other programs and when printing the indent will |
| also be wrong. Therefore it is recommended to keep 'tabstop' at eight |
| all the time. That's the standard value everywhere. |
| |
| |
| CHANGING TABS |
| |
| You edit a file which was written with a tabstop of 3. In Vim it looks ugly, |
| because it uses the normal tabstop value of 8. You can fix this by setting |
| 'tabstop' to 3. But you have to do this every time you edit this file. |
| Vim can change the use of tabstops in your file. First, set 'tabstop' to |
| make the indents look good, then use the ":retab" command: > |
| |
| :set tabstop=3 |
| :retab 8 |
| |
| The ":retab" command will change 'tabstop' to 8, while changing the text such |
| that it looks the same. It changes spans of white space into tabs and spaces |
| for this. You can now write the file. Next time you edit it the indents will |
| be right without setting an option. |
| Warning: When using ":retab" on a program, it may change white space inside |
| a string constant. Therefore it's a good habit to use "\t" instead of a |
| real tab. |
| |
| ============================================================================== |
| *25.4* Dealing with long lines |
| |
| Sometimes you will be editing a file that is wider than the number of columns |
| in the window. When that occurs, Vim wraps the lines so that everything fits |
| on the screen. |
| If you switch the 'wrap' option off, each line in the file shows up as one |
| line on the screen. Then the ends of the long lines disappear off the screen |
| to the right. |
| When you move the cursor to a character that can't be seen, Vim will scroll |
| the text to show it. This is like moving a viewport over the text in the |
| horizontal direction. |
| By default, Vim does not display a horizontal scrollbar in the GUI. If you |
| want to enable one, use the following command: > |
| |
| :set guioptions+=b |
| |
| One horizontal scrollbar will appear at the bottom of the Vim window. |
| |
| If you don't have a scrollbar or don't want to use it, use these commands to |
| scroll the text. The cursor will stay in the same place, but it's moved back |
| into the visible text if necessary. |
| |
| zh scroll right |
| 4zh scroll four characters right |
| zH scroll half a window width right |
| ze scroll right to put the cursor at the end |
| zl scroll left |
| 4zl scroll four characters left |
| zL scroll half a window width left |
| zs scroll left to put the cursor at the start |
| |
| Let's attempt to show this with one line of text. The cursor is on the "w" of |
| "which". The "current window" above the line indicates the text that is |
| currently visible. The "window"s below the text indicate the text that is |
| visible after the command left of it. |
| |
| |<-- current window -->| |
| some long text, part of which is visible in the window ~ |
| ze |<-- window -->| |
| zH |<-- window -->| |
| 4zh |<-- window -->| |
| zh |<-- window -->| |
| zl |<-- window -->| |
| 4zl |<-- window -->| |
| zL |<-- window -->| |
| zs |<-- window -->| |
| |
| |
| MOVING WITH WRAP OFF |
| |
| When 'wrap' is off and the text has scrolled horizontally, you can use the |
| following commands to move the cursor to a character you can see. Thus text |
| left and right of the window is ignored. These never cause the text to |
| scroll: |
| |
| g0 to first visible character in this line |
| g^ to first non-blank visible character in this line |
| gm to middle of this line |
| g$ to last visible character in this line |
| |
| |<-- window -->| |
| some long text, part of which is visible ~ |
| g0 g^ gm g$ |
| |
| |
| BREAKING AT WORDS *edit-no-break* |
| |
| When preparing text for use by another program, you might have to make |
| paragraphs without a line break. A disadvantage of using 'nowrap' is that you |
| can't see the whole sentence you are working on. When 'wrap' is on, words are |
| broken halfway, which makes them hard to read. |
| A good solution for editing this kind of paragraph is setting the |
| 'linebreak' option. Vim then breaks lines at an appropriate place when |
| displaying the line. The text in the file remains unchanged. |
| Without 'linebreak' text might look like this: |
| |
| +---------------------------------+ |
| |letter generation program for a b| |
| |ank. They wanted to send out a s| |
| |pecial, personalized letter to th| |
| |eir richest 1000 customers. Unfo| |
| |rtunately for the programmer, he | |
| +---------------------------------+ |
| After: > |
| |
| :set linebreak |
| |
| it looks like this: |
| |
| +---------------------------------+ |
| |letter generation program for a | |
| |bank. They wanted to send out a | |
| |special, personalized letter to | |
| |their richest 1000 customers. | |
| |Unfortunately for the programmer,| |
| +---------------------------------+ |
| |
| Related options: |
| 'breakat' specifies the characters where a break can be inserted. |
| 'showbreak' specifies a string to show at the start of broken line. |
| Set 'textwidth' to zero to avoid a paragraph to be split. |
| |
| |
| MOVING BY VISIBLE LINES |
| |
| The "j" and "k" commands move to the next and previous lines. When used on |
| a long line, this means moving a lot of screen lines at once. |
| To move only one screen line, use the "gj" and "gk" commands. When a line |
| doesn't wrap they do the same as "j" and "k". When the line does wrap, they |
| move to a character displayed one line below or above. |
| You might like to use these mappings, which bind these movement commands to |
| the cursor keys: > |
| |
| :map <Up> gk |
| :map <Down> gj |
| |
| |
| TURNING A PARAGRAPH INTO ONE LINE *edit-paragraph-join* |
| |
| If you want to import text into a program like MS-Word, each paragraph should |
| be a single line. If your paragraphs are currently separated with empty |
| lines, this is how you turn each paragraph into a single line: > |
| |
| :g/./,/^$/join |
| |
| That looks complicated. Let's break it up in pieces: |
| |
| :g/./ A ":global" command that finds all lines that contain |
| at least one character. |
| ,/^$/ A range, starting from the current line (the non-empty |
| line) until an empty line. |
| join The ":join" command joins the range of lines together |
| into one line. |
| |
| Starting with this text, containing eight lines broken at column 30: |
| |
| +----------------------------------+ |
| |A letter generation program | |
| |for a bank. They wanted to | |
| |send out a special, | |
| |personalized letter. | |
| | | |
| |To their richest 1000 | |
| |customers. Unfortunately for | |
| |the programmer, | |
| +----------------------------------+ |
| |
| You end up with two lines: |
| |
| +----------------------------------+ |
| |A letter generation program for a | |
| |bank. They wanted to send out a s| |
| |pecial, personalized letter. | |
| |To their richest 1000 customers. | |
| |Unfortunately for the programmer, | |
| +----------------------------------+ |
| |
| Note that this doesn't work when the separating line is blank but not empty; |
| when it contains spaces and/or tabs. This command does work with blank lines: |
| > |
| :g/\S/,/^\s*$/join |
| |
| This still requires a blank or empty line at the end of the file for the last |
| paragraph to be joined. |
| |
| ============================================================================== |
| *25.5* Editing tables |
| |
| Suppose you are editing a table with four columns: |
| |
| nice table test 1 test 2 test 3 ~ |
| input A 0.534 ~ |
| input B 0.913 ~ |
| |
| You need to enter numbers in the third column. You could move to the second |
| line, use "A", enter a lot of spaces and type the text. |
| For this kind of editing there is a special option: > |
| |
| set virtualedit=all |
| |
| Now you can move the cursor to positions where there isn't any text. This is |
| called "virtual space". Editing a table is a lot easier this way. |
| Move the cursor by searching for the header of the last column: > |
| |
| /test 3 |
| |
| Now press "j" and you are right where you can enter the value for "input A". |
| Typing "0.693" results in: |
| |
| nice table test 1 test 2 test 3 ~ |
| input A 0.534 0.693 ~ |
| input B 0.913 ~ |
| |
| Vim has automatically filled the gap in front of the new text for you. Now, |
| to enter the next field in this column use "Bj". "B" moves back to the start |
| of a white space separated word. Then "j" moves to the place where the next |
| field can be entered. |
| |
| Note: |
| You can move the cursor anywhere in the display, also beyond the end |
| of a line. But Vim will not insert spaces there, until you insert a |
| character in that position. |
| |
| |
| COPYING A COLUMN |
| |
| You want to add a column, which should be a copy of the third column and |
| placed before the "test 1" column. Do this in seven steps: |
| 1. Move the cursor to the left upper corner of this column, e.g., with |
| "/test 3". |
| 2. Press CTRL-V to start blockwise Visual mode. |
| 3. Move the cursor down two lines with "2j". You are now in "virtual space": |
| the "input B" line of the "test 3" column. |
| 4. Move the cursor right, to include the whole column in the selection, plus |
| the space that you want between the columns. "9l" should do it. |
| 5. Yank the selected rectangle with "y". |
| 6. Move the cursor to "test 1", where the new column must be placed. |
| 7. Press "P". |
| |
| The result should be: |
| |
| nice table test 3 test 1 test 2 test 3 ~ |
| input A 0.693 0.534 0.693 ~ |
| input B 0.913 ~ |
| |
| Notice that the whole "test 1" column was shifted right, also the line where |
| the "test 3" column didn't have text. |
| |
| Go back to non-virtual cursor movements with: > |
| |
| :set virtualedit= |
| |
| |
| VIRTUAL REPLACE MODE |
| |
| The disadvantage of using 'virtualedit' is that it "feels" different. You |
| can't recognize tabs or spaces beyond the end of line when moving the cursor |
| around. Another method can be used: Virtual Replace mode. |
| Suppose you have a line in a table that contains both tabs and other |
| characters. Use "rx" on the first tab: |
| |
| inp 0.693 0.534 0.693 ~ |
| |
| | |
| rx | |
| V |
| |
| inpx0.693 0.534 0.693 ~ |
| |
| The layout is messed up. To avoid that, use the "gr" command: |
| |
| inp 0.693 0.534 0.693 ~ |
| |
| | |
| grx | |
| V |
| |
| inpx 0.693 0.534 0.693 ~ |
| |
| What happens is that the "gr" command makes sure the new character takes the |
| right amount of screen space. Extra spaces or tabs are inserted to fill the |
| gap. Thus what actually happens is that a tab is replaced by "x" and then |
| blanks added to make the text after it keep its place. In this case a |
| tab is inserted. |
| When you need to replace more than one character, you use the "R" command |
| to go to Replace mode (see |04.9|). This messes up the layout and replaces |
| the wrong characters: |
| |
| inp 0 0.534 0.693 ~ |
| |
| | |
| R0.786 | |
| V |
| |
| inp 0.78634 0.693 ~ |
| |
| The "gR" command uses Virtual Replace mode. This preserves the layout: |
| |
| inp 0 0.534 0.693 ~ |
| |
| | |
| gR0.786 | |
| V |
| |
| inp 0.786 0.534 0.693 ~ |
| |
| ============================================================================== |
| |
| Next chapter: |usr_26.txt| Repeating |
| |
| Copyright: see |manual-copyright| vim:tw=78:ts=8:ft=help:norl: |