summaryrefslogtreecommitdiffstats
path: root/runtime/doc/usr_25.txt
diff options
context:
space:
mode:
Diffstat (limited to 'runtime/doc/usr_25.txt')
-rw-r--r--runtime/doc/usr_25.txt583
1 files changed, 583 insertions, 0 deletions
diff --git a/runtime/doc/usr_25.txt b/runtime/doc/usr_25.txt
new file mode 100644
index 0000000..2f25a9f
--- /dev/null
+++ b/runtime/doc/usr_25.txt
@@ -0,0 +1,583 @@
+*usr_25.txt* For Vim version 9.0. Last change: 2016 Mar 28
+
+ 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: >
+
+ :packadd justify
+
+Or put this line in your |vimrc|: >
+
+ packadd! justify
+
+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/pack/dist/opt/justify/plugin/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 screen line
+ gM to middle of the text in this line
+ g$ to last visible character in this line
+
+ |<-- window -->|
+ some long text, part of which is visible in one line ~
+ g0 g^ gm 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:noet:ft=help:norl: