Adding upstream version 2:8.2.2434.upstream/2%8.2.2434upstream

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

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..5afe7b7
--- /dev/null
+++ b/runtime/doc/usr_25.txt
@@ -0,0 +1,583 @@
+*usr_25.txt*	For Vim version 8.2.  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: