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

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

1 files changed, 661 insertions, 0 deletions

diff --git a/runtime/doc/usr_03.txt b/runtime/doc/usr_03.txt
new file mode 100644
index 0000000..baae7f8
--- /dev/null
+++ b/runtime/doc/usr_03.txt
@@ -0,0 +1,661 @@
+*usr_03.txt*	For Vim version 9.0.  Last change: 2022 Oct 30
+
+		     VIM USER MANUAL - by Bram Moolenaar
+
+			     Moving around
+
+
+Before you can insert or delete text the cursor has to be moved to the right
+place.  Vim has a large number of commands to position the cursor.  This
+chapter shows you how to use the most important ones.  You can find a list of
+these commands below |Q_lr|.
+
+|03.1|	Word movement
+|03.2|	Moving to the start or end of a line
+|03.3|	Moving to a character
+|03.4|	Matching a parenthesis
+|03.5|	Moving to a specific line
+|03.6|	Telling where you are
+|03.7|	Scrolling around
+|03.8|	Simple searches
+|03.9|	Simple search patterns
+|03.10|	Using marks
+
+     Next chapter: |usr_04.txt|  Making small changes
+ Previous chapter: |usr_02.txt|  The first steps in Vim
+Table of contents: |usr_toc.txt|
+
+==============================================================================
+*03.1*	Word movement
+
+To move the cursor forward one word, use the "w" command.  Like most Vim
+commands, you can use a numeric prefix to move past multiple words.  For
+example, "3w" moves three words.  This figure shows how it works (starting at
+the position marked with "x"):
+
+	This is a line with example text ~
+	  x-->-->->----------------->
+	   w  w  w    3w
+
+Notice that "w" moves to the start of the next word if it already is at the
+start of a word.
+   The "b" command moves backward to the start of the previous word:
+
+	This is a line with example text ~
+	<----<--<-<---------<--x
+	   b   b b    2b      b
+
+There is also the "e" command that moves to the next end of a word and "ge",
+which moves to the previous end of a word:
+
+	This is a line with example text ~
+	   <----<----x---->------------>
+	   2ge   ge     e       2e
+
+If you are at the last word of a line, the "w" command will take you to the
+first word in the next line.  Thus you can use this to move through a
+paragraph, much faster than using "l".  "b" does the same in the other
+direction.
+
+A word ends at a non-word character, such as a ".", "-" or ")".  To change
+what Vim considers to be a word, see the 'iskeyword' option.  If you try this
+out in the help directly, 'iskeyword' needs to be reset for the examples to
+work: >
+	:set iskeyword&
+It is also possible to move by white-space separated WORDs.  This is not a
+word in the normal sense, that's why the uppercase is used.  The commands for
+moving by WORDs are also uppercase, as this figure shows:
+
+	       ge      b	  w				e
+	       <-     <-	 --->			       --->
+	This is-a line, with special/separated/words (and some more). ~
+	   <----- <-----	 -------------------->	       ----->
+	     gE      B			 W			 E
+
+With this mix of lowercase and uppercase commands, you can quickly move
+forward and backward through a paragraph.
+
+==============================================================================
+*03.2*	Moving to the start or end of a line
+
+The "$" command moves the cursor to the end of a line.  If your keyboard has
+an <End> key it will do the same thing.
+
+The "^" command moves to the first non-blank character of the line.  The "0"
+command (zero) moves to the very first character of the line, and the <Home>
+key does the same thing.  In a picture ("." indicates a space):
+
+		  ^
+	     <-----------x
+	.....This is a line with example text ~
+	<----------------x   x-------------->
+		0		   $
+
+(the "....." indicates blanks here)
+
+   The "$" command takes a count, like most movement commands.  But moving to
+the end of the line several times doesn't make sense.  Therefore it causes the
+editor to move to the end of another line.  For example, "1$" moves you to
+the end of the first line (the one you're on), "2$" to the end of the next
+line, and so on.
+   The "0" command doesn't take a count argument, because the "0" would be
+part of the count.  Unexpectedly, using a count with "^" doesn't have any
+effect.
+
+==============================================================================
+*03.3*	Moving to a character
+
+One of the most useful movement commands is the single-character search
+command.  The command "fx" searches forward in the line for the single
+character x.  Hint: "f" stands for "Find".
+   For example, you are at the beginning of the following line.  Suppose you
+want to go to the h of human.  Just execute the command "fh" and the cursor
+will be positioned over the h:
+
+	To err is human.  To really foul up you need a computer. ~
+	---------->--------------->
+	    fh		 fy
+
+This also shows that the command "fy" moves to the end of the word really.
+   You can specify a count; therefore, you can go to the "l" of "foul" with
+"3fl":
+
+	To err is human.  To really foul up you need a computer. ~
+		  --------------------->
+			   3fl
+
+The "F" command searches to the left:
+
+	To err is human.  To really foul up you need a computer. ~
+		  <---------------------
+			    Fh
+
+The "tx" command works like the "fx" command, except it stops one character
+before the searched character.  Hint: "t" stands for "To".  The backward
+version of this command is "Tx".
+
+	To err is human.  To really foul up you need a computer. ~
+		   <------------  ------------->
+			Th		tn
+
+These four commands can be repeated with ";".  "," repeats in the other
+direction.  The cursor is never moved to another line.  Not even when the
+sentence continues.
+
+Sometimes you will start a search, only to realize that you have typed the
+wrong command.  You type "f" to search backward, for example, only to realize
+that you really meant "F".  To abort a search, press <Esc>.  So "f<Esc>" is an
+aborted forward search and doesn't do anything.  Note: <Esc> cancels most
+operations, not just searches.
+
+==============================================================================
+*03.4*	Matching a parenthesis
+
+When writing a program you often end up with nested () constructs.  Then the
+"%" command is very handy: It moves to the matching paren.  If the cursor is
+on a "(" it will move to the matching ")".  If it's on a ")" it will move to
+the matching "(".
+
+			    %
+			 <----->
+		if (a == (b * c) / d) ~
+		   <---------------->
+			    %
+
+This also works for [] and {} pairs.  (This can be defined with the
+'matchpairs' option.)
+
+When the cursor is not on a useful character, "%" will search forward to find
+one.  Thus if the cursor is at the start of the line of the previous example,
+"%" will search forward and find the first "(".  Then it moves to its match:
+
+		if (a == (b * c) / d) ~
+		---+---------------->
+			   %
+
+==============================================================================
+*03.5*	Moving to a specific line
+
+If you are a C or C++ programmer, you are familiar with error messages such as
+the following:
+
+	prog.c:33: j   undeclared (first use in this function) ~
+
+This tells you that you might want to fix something on line 33.  So how do you
+find line 33?  One way is to do "9999k" to go to the top of the file and "32j"
+to go down thirty-two lines.  It is not a good way, but it works.  A much
+better way of doing things is to use the "G" command.  With a count, this
+command positions you at the given line number.  For example, "33G" puts you
+on line 33.  (For a better way of going through a compiler's error list, see
+|usr_30.txt|, for information on the :make command.)
+   With no argument, "G" positions you at the end of the file.  A quick way to
+go to the start of a file use "gg".  "1G" will do the same, but is a tiny bit
+more typing.
+
+	    |	first line of a file   ^
+	    |	text text text text    |
+	    |	text text text text    |  gg
+	7G  |	text text text text    |
+	    |	text text text text
+	    |	text text text text
+	    V	text text text text    |
+		text text text text    |  G
+		text text text text    |
+		last line of a file    V
+
+Another way to move to a line is using the "%" command with a count.  For
+example "50%" moves you to halfway the file.  "90%" goes to near the end.
+
+The previous assumes that you want to move to a line in the file, no matter if
+it's currently visible or not.  What if you want to move to one of the lines
+you can see?  This figure shows the three commands you can use:
+
+			+---------------------------+
+		H -->	| text sample text	    |
+			| sample text		    |
+			| text sample text	    |
+			| sample text		    |
+		M -->	| text sample text	    |
+			| sample text		    |
+			| text sample text	    |
+			| sample text		    |
+		L -->	| text sample text	    |
+			+---------------------------+
+
+Hints: "H" stands for Home, "M" for Middle and "L" for Last.  Alternatively,
+"H" for High, "M" for Middle and "L" for Low.
+
+==============================================================================
+*03.6*	Telling where you are
+
+To see where you are in a file, there are three ways:
+
+1.  Use the CTRL-G command.  You get a message like this (assuming the 'ruler'
+    option is off):
+
+	"usr_03.txt" line 233 of 650 --35%-- col 45-52 ~
+
+    This shows the name of the file you are editing, the line number where the
+    cursor is, the total number of lines, the percentage of the way through
+    the file and the column of the cursor.
+       Sometimes you will see a split column number.  For example, "col 2-9".
+    This indicates that the cursor is positioned on the second character, but
+    because character one is a tab, occupying eight spaces worth of columns,
+    the screen column is 9.
+
+2.  Set the 'number' option.  This will display a line number in front of
+    every line: >
+
+	:set number
+<
+    To switch this off again: >
+
+	:set nonumber
+<
+    Since 'number' is a boolean option, prepending "no" to its name has the
+    effect of switching it off.  A boolean option has only these two values,
+    it is either on or off.
+       Vim has many options.  Besides the boolean ones there are options with
+    a numerical value and string options.  You will see examples of this where
+    they are used.
+
+3.  Set the 'ruler' option.  This will display the cursor position in the
+    lower right corner of the Vim window: >
+
+	:set ruler
+
+Using the 'ruler' option has the advantage that it doesn't take much room,
+thus there is more space for your text.
+
+==============================================================================
+*03.7*	Scrolling around
+
+The CTRL-U command scrolls down half a screen of text.  Think of looking
+through a viewing window at the text and moving this window up by half the
+height of the window.  Thus the window moves up over the text, which is
+backward in the file.  Don't worry if you have a little trouble remembering
+which end is up.  Most users have the same problem.
+   The CTRL-D command moves the viewing window down half a screen in the file,
+thus scrolls the text up half a screen.
+
+				       +----------------+
+				       | some text	|
+				       | some text	|
+				       | some text	|
+	+---------------+	       | some text	|
+	| some text	|  CTRL-U  --> |		|
+	|		|	       | 123456		|
+	| 123456	|	       +----------------+
+	| 7890		|
+	|		|	       +----------------+
+	| example	|  CTRL-D -->  | 7890		|
+	+---------------+	       |		|
+				       | example	|
+				       | example	|
+				       | example	|
+				       | example	|
+				       +----------------+
+
+To scroll one line at a time use CTRL-E (scroll up) and CTRL-Y (scroll down).
+Think of CTRL-E to give you one line Extra.  (If you use MS-Windows compatible
+key mappings CTRL-Y will redo a change instead of scroll.)
+
+To scroll forward by a whole screen (except for two lines) use CTRL-F.  To
+scroll backwards, use CTRL-B.  These should be easy to remember: F for
+Forwards and B for Backwards.
+
+A common issue is that after moving down many lines with "j" your cursor is at
+the bottom of the screen.  You would like to see the context of the line with
+the cursor.  That's done with the "zz" command.
+
+	+------------------+		 +------------------+
+	| earlier text	   |		 | earlier text	    |
+	| earlier text	   |		 | earlier text	    |
+	| earlier text	   |		 | earlier text	    |
+	| earlier text	   |   zz  -->	 | line with cursor |
+	| earlier text	   |		 | later text	    |
+	| earlier text	   |		 | later text	    |
+	| line with cursor |		 | later text	    |
+	+------------------+		 +------------------+
+
+The "zt" command puts the cursor line at the top, "zb" at the bottom.  There
+are a few more scrolling commands, see |Q_sc|.  To always keep a few lines of
+context around the cursor, use the 'scrolloff' option.
+
+==============================================================================
+*03.8*	Simple searches
+
+To search for a string, use the "/string" command.  To find the word include,
+for example, use the command: >
+
+	/include
+
+You will notice that when you type the "/" the cursor jumps to the last line
+of the Vim window, like with colon commands.  That is where you type the word.
+You can press the backspace key (backarrow or <BS>) to make corrections.  Use
+the <Left> and <Right> cursor keys when necessary.
+   Pressing <Enter> executes the command.
+
+	Note:
+	The characters .*[]^%/\?~$ have special meanings.  If you want to use
+	them in a search you must put a \ in front of them.  See below.
+
+To find the next occurrence of the same string use the "n" command.  Use this
+to find the first #include after the cursor: >
+
+	/#include
+
+And then type "n" several times.  You will move to each #include in the text.
+You can also use a count if you know which match you want.  Thus "3n" finds
+the third match.  You can also use a count with "/": "4/the" goes to the
+fourth match of "the".
+
+The "?" command works like "/" but searches backwards: >
+
+	?word
+
+The "N" command repeats the last search the opposite direction.  Thus using
+"N" after a "/" command searches backwards, using "N" after "?" searches
+forwards.
+
+
+IGNORING CASE
+
+Normally you have to type exactly what you want to find.  If you don't care
+about upper or lowercase in a word, set the 'ignorecase' option: >
+
+	:set ignorecase
+
+If you now search for "word", it will also match "Word" and "WORD".  To match
+case again: >
+
+	:set noignorecase
+
+
+HISTORY
+
+Suppose you do three searches: >
+
+	/one
+	/two
+	/three
+
+Now let's start searching by typing a simple "/" without pressing <Enter>.  If
+you press <Up> (the cursor key), Vim puts "/three" on the command line.
+Pressing <Enter> at this point searches for three.  If you do not press
+<Enter>, but press <Up> instead, Vim changes the prompt to "/two".  Another
+press of <Up> moves you to "/one".
+   You can also use the <Down> cursor key to move through the history of
+search commands in the other direction.
+
+If you know what a previously used pattern starts with, and you want to use it
+again, type that character before pressing <Up>.  With the previous example,
+you can type "/o<Up>" and Vim will put "/one" on the command line.
+
+The commands starting with ":" also have a history.  That allows you to recall
+a previous command and execute it again.  These two histories are separate.
+
+
+SEARCHING FOR A WORD IN THE TEXT
+
+Suppose you see the word "TheLongFunctionName" in the text and you want to
+find the next occurrence of it.  You could type "/TheLongFunctionName", but
+that's a lot of typing.  And when you make a mistake Vim won't find it.
+   There is an easier way: Position the cursor on the word and use the "*"
+command.  Vim will grab the word under the cursor and use it as the search
+string.
+   The "#" command does the same in the other direction.  You can prepend a
+count: "3*" searches for the third occurrence of the word under the cursor.
+
+
+SEARCHING FOR WHOLE WORDS
+
+If you type "/the" it will also match "there".  To only find words that end
+in "the" use: >
+
+	/the\>
+
+The "\>" item is a special marker that only matches at the end of a word.
+Similarly "\<" only matches at the beginning of a word.  Thus to search for
+the word "the" only: >
+
+	/\<the\>
+
+This does not match "there" or "soothe".  Notice that the "*" and "#" commands
+use these start-of-word and end-of-word markers to only find whole words (you
+can use "g*" and "g#" to match partial words).
+
+
+HIGHLIGHTING MATCHES
+
+While editing a program you see a variable called "nr".  You want to check
+where it's used.  You could move the cursor to "nr" and use the "*" command
+and press "n" to go along all the matches.
+   There is another way.  Type this command: >
+
+	:set hlsearch
+
+If you now search for "nr", Vim will highlight all matches.  That is a very
+good way to see where the variable is used, without the need to type commands.
+   To switch this off: >
+
+	:set nohlsearch
+
+Then you need to switch it on again if you want to use it for the next search
+command.  If you only want to remove the highlighting, use this command: >
+
+	:nohlsearch
+
+This doesn't reset the option.  Instead, it disables the highlighting.  As
+soon as you execute a search command, the highlighting will be used again.
+Also for the "n" and "N" commands.
+
+
+TUNING SEARCHES
+
+There are a few options that change how searching works.  These are the
+essential ones:
+>
+	:set incsearch
+
+This makes Vim display the match for the string while you are still typing it.
+Use this to check if the right match will be found.  Then press <Enter> to
+really jump to that location.  Or type more to change the search string.
+>
+	:set nowrapscan
+
+This stops the search at the end of the file.  Or, when you are searching
+backwards, it stops the search at the start of the file.  The 'wrapscan'
+option is on by default, thus searching wraps around the end of the file.
+
+
+INTERMEZZO
+
+If you like one of the options mentioned before, and set it each time you use
+Vim, you can put the command in your Vim startup file.
+   Edit the file, as mentioned at |not-compatible|.  Or use this command to
+find out where it is: >
+
+	:scriptnames
+
+Edit the file, for example with: >
+
+	:edit ~/.vimrc
+
+Then add a line with the command to set the option, just like you typed it in
+Vim.  Example: >
+
+	Go:set hlsearch<Esc>
+
+"G" moves to the end of the file.  "o" starts a new line, where you type the
+":set" command.  You end insert mode with <Esc>.  Then write and close the
+file: >
+
+	ZZ
+
+If you now start Vim again, the 'hlsearch' option will already be set.
+
+==============================================================================
+*03.9*	Simple search patterns
+
+The Vim editor uses regular expressions to specify what to search for.
+Regular expressions are an extremely powerful and compact way to specify a
+search pattern.  Unfortunately, this power comes at a price, because regular
+expressions are a bit tricky to specify.
+   In this section we mention only a few essential ones.  More about search
+patterns and commands can be found in chapter 27 |usr_27.txt|.  You can find
+the full explanation here: |pattern|.
+
+
+BEGINNING AND END OF A LINE
+
+The ^ character matches the beginning of a line.  On an English-US keyboard
+you find it above the 6.  The pattern "include" matches the word include
+anywhere on the line.  But the pattern "^include" matches the word include
+only if it is at the beginning of a line.
+   The $ character matches the end of a line.  Therefore, "was$" matches the
+word was only if it is at the end of a line.
+
+Let's mark the places where "/the" matches in this example line with "x"s:
+
+	the solder holding one of the chips melted and the ~
+	xxx			  xxx		       xxx
+
+Using "/the$" we find this match:
+
+	the solder holding one of the chips melted and the ~
+						       xxx
+
+And with "/^the" we find this one:
+	the solder holding one of the chips melted and the ~
+	xxx
+
+You can try searching with "/^the$"; it will only match a single line
+consisting entirely of "the".  White space does matter here, thus if a line
+contains a space after the word, like "the ", the pattern will not match.
+
+
+MATCHING ANY SINGLE CHARACTER
+
+The . (dot) character matches any existing character.  For example, the
+pattern "c.m" matches a string whose first character is a c, whose second
+character is anything, and whose third character is m.  Example:
+
+	We use a computer that became the cummin winter. ~
+		 xxx		 xxx	  xxx
+
+
+MATCHING SPECIAL CHARACTERS
+
+If you really want to match a dot, you must avoid its special meaning by
+putting a backslash before it.
+   If you search for "ter.", you will find these matches:
+
+	We use a computer that became the cummin winter. ~
+		      xxxx			    xxxx
+
+Searching for "ter\." only finds the second match.
+
+==============================================================================
+*03.10*	Using marks
+
+When you make a jump to a position with the "G" command, Vim remembers the
+position from before this jump.  This position is called a mark.  To go back
+where you came from, use this command: >
+
+	``
+
+This ` is a backtick or open single-quote character.
+   If you use the same command a second time you will jump back again.  That's
+because the "`" command is a jump itself, and the position from before this
+jump is remembered.
+
+Generally, every time you do a command that can move the cursor further than
+within the same line, this is called a jump.  This includes the search
+commands "/" and "n" (it doesn't matter how far away the match is).  But not
+the character searches with "fx" and "tx" or the word movements "w" and "e".
+   Also, "j" and "k" are not considered to be a jump, even when you use a
+count to make them move the cursor quite a long way away.
+
+The "``" command jumps back and forth, between two points.  The CTRL-O command
+jumps to older positions (Hint: O for older).  CTRL-I then jumps back to newer
+positions (Hint: for many common keyboard layouts, I is just next to O).
+Consider this sequence of commands: >
+
+	33G
+	/^The
+	CTRL-O
+
+You first jump to line 33, then search for a line that starts with "The".
+Then with CTRL-O you jump back to line 33.  Another CTRL-O takes you back to
+where you started.  If you now use CTRL-I you jump to line 33 again.  And
+to the match for "The" with another CTRL-I.
+
+
+	     |	example text   ^	     |
+	33G  |	example text   |  CTRL-O     | CTRL-I
+	     |	example text   |	     |
+	     V	line 33 text   ^	     V
+	     |	example text   |	     |
+       /^The |	example text   |  CTRL-O     | CTRL-I
+	     V	There you are  |	     V
+		example text
+
+	Note:
+	CTRL-I is the same as <Tab>.
+
+The ":jumps" command gives a list of positions you jumped to.  The entry which
+you used last is marked with a ">".
+
+
+NAMED MARKS							*bookmark*
+
+Vim enables you to place your own marks in the text.  The command "ma" marks
+the place under the cursor as mark a.  You can place 26 marks (a through z) in
+your text.  You can't see them, it's just a position that Vim remembers.
+   To go to a mark, use the command `{mark}, where {mark} is the mark letter.
+Thus to move to the a mark:
+>
+	`a
+
+The command "'mark" (single quotation mark, or apostrophe) moves you to the
+beginning of the line containing the mark.  This differs from the "`mark"
+command, which also moves you to the marked column.
+
+The marks can be very useful when working on two related parts in a file.
+Suppose you have some text near the start of the file you need to look at,
+while working on some text near the end of the file.
+   Move to the text at the start and place the s (start) mark there: >
+
+	ms
+
+Then move to the text you want to work on and put the e (end) mark there: >
+
+	me
+
+Now you can move around, and when you want to look at the start of the file,
+you use this to jump there: >
+
+	's
+
+Then you can use '' to jump back to where you were, or 'e to jump to the text
+you were working on at the end.
+   There is nothing special about using s for start and e for end, they are
+just easy to remember.
+
+You can use this command to get a list of marks: >
+
+	:marks
+
+You will notice a few special marks.  These include:
+
+	'	The cursor position before doing a jump
+	"	The cursor position when last editing the file
+	[	Start of the last change
+	]	End of the last change
+
+==============================================================================
+
+Next chapter: |usr_04.txt|  Making small changes
+
+Copyright: see |manual-copyright|  vim:tw=78:ts=8:noet:ft=help:norl: