vim

Fork of vim, an acceptable text editor
git clone git://git.laack.co/vim.git
Log | Files | Refs | README | LICENSE

usr_25.txt (19423B)


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