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

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

1 files changed, 702 insertions, 0 deletions

diff --git a/runtime/doc/usr_02.txt b/runtime/doc/usr_02.txt
new file mode 100644
index 0000000..486426e
--- /dev/null
+++ b/runtime/doc/usr_02.txt
@@ -0,0 +1,702 @@
+*usr_02.txt*	For Vim version 9.1.  Last change: 2021 Apr 24
+
+		     VIM USER MANUAL - by Bram Moolenaar
+
+			    The first steps in Vim
+
+
+This chapter provides just enough information to edit a file with Vim.  Not
+well or fast, but you can edit.  Take some time to practice with these
+commands, they form the base for what follows.
+
+|02.1|	Running Vim for the First Time
+|02.2|	Inserting text
+|02.3|	Moving around
+|02.4|	Deleting characters
+|02.5|	Undo and Redo
+|02.6|	Other editing commands
+|02.7|	Getting out
+|02.8|	Finding help
+
+     Next chapter: |usr_03.txt|  Moving around
+ Previous chapter: |usr_01.txt|  About the manuals
+Table of contents: |usr_toc.txt|
+
+==============================================================================
+*02.1*	Running Vim for the First Time
+
+To start Vim, enter this command: >
+
+	gvim file.txt
+
+In UNIX you can type this at any command prompt.  If you are running Microsoft
+Windows, open a Command Prompt and enter the command.
+   In either case, Vim starts editing a file called file.txt.  Because this
+is a new file, you get a blank window. This is what your screen will look
+like:
+
+	+---------------------------------------+
+	|#					|
+	|~					|
+	|~					|
+	|~					|
+	|~					|
+	|"file.txt" [New file]			|
+	+---------------------------------------+
+		('#' is the cursor position.)
+
+The tilde (~) lines indicate lines not in the file.  In other words, when Vim
+runs out of file to display, it displays tilde lines.  At the bottom of the
+screen, a message line indicates the file is named file.txt and shows that you
+are creating a new file.  The message information is temporary and other
+information overwrites it.
+
+
+THE VIM COMMAND
+
+The gvim command causes the editor to create a new window for editing.  If you
+use this command: >
+
+	vim file.txt
+
+the editing occurs inside your command window.  In other words, if you are
+running inside an xterm, the editor uses your xterm window.  If you are using
+an MS-Windows command prompt window, the editing occurs inside this window.
+The text in the window will look the same for both versions, but with gvim you
+have extra features, like a menu bar.  More about that later.
+
+==============================================================================
+*02.2*	Inserting text
+
+The Vim editor is a modal editor.  That means that the editor behaves
+differently, depending on which mode you are in.  The two basic modes are
+called Normal mode and Insert mode.  In Normal mode the characters you type
+are commands.  In Insert mode the characters are inserted as text.
+   Since you have just started Vim it will be in Normal mode.  To start Insert
+mode you type the "i" command (i for Insert).  Then you can enter
+the text.  It will be inserted into the file.  Do not worry if you make
+mistakes; you can correct them later.  To enter the following programmer's
+limerick, this is what you type: >
+
+	iA very intelligent turtle
+	Found programming UNIX a hurdle
+
+After typing "turtle" you press the <Enter> key to start a new line.  Finally
+you press the <Esc> key to stop Insert mode and go back to Normal mode.  You
+now have two lines of text in your Vim window:
+
+	+---------------------------------------+
+	|A very intelligent turtle		|
+	|Found programming UNIX a hurdle	|
+	|~					|
+	|~					|
+	|					|
+	+---------------------------------------+
+
+
+WHAT IS THE MODE?
+
+To be able to see what mode you are in, type this command: >
+
+	:set showmode
+
+You will notice that when typing the colon Vim moves the cursor to the last
+line of the window.  That's where you type colon commands (commands that start
+with a colon).  Finish this command by pressing the <Enter> key (all commands
+that start with a colon are finished this way).
+   Now, if you type the "i" command Vim will display --INSERT-- at the bottom
+of the window.  This indicates you are in Insert mode.
+
+	+---------------------------------------+
+	|A very intelligent turtle		|
+	|Found programming UNIX a hurdle	|
+	|~					|
+	|~					|
+	|-- INSERT --				|
+	+---------------------------------------+
+
+If you press <Esc> to go back to Normal mode the last line will be made blank.
+
+
+GETTING OUT OF TROUBLE
+
+One of the problems for Vim novices is mode confusion, which is caused by
+forgetting which mode you are in or by accidentally typing a command that
+switches modes.  To get back to Normal mode, no matter what mode you are in,
+press the <Esc> key.  Sometimes you have to press it twice.  If Vim beeps back
+at you, you already are in Normal mode.
+
+==============================================================================
+*02.3*	Moving around
+
+After you return to Normal mode, you can move around by using these keys:
+
+	h   left						*hjkl*
+	j   down
+	k   up
+	l   right
+
+At first, it may appear that these commands were chosen at random.  After all,
+who ever heard of using l for right?  But actually, there is a very good
+reason for these choices: Moving the cursor is the most common thing you do in
+an editor, and these keys are on the home row of your right hand.  In other
+words, these commands are placed where you can type them the fastest
+(especially when you type with ten fingers).
+
+	Note:
+	You can also move the cursor by using the arrow keys.  If you do,
+	however, you greatly slow down your editing because to press the arrow
+	keys, you must move your hand from the text keys to the arrow keys.
+	Considering that you might be doing it hundreds of times an hour, this
+	can take a significant amount of time.
+	   Also, there are keyboards which do not have arrow keys, or which
+	locate them in unusual places; therefore, knowing the use of the hjkl
+	keys helps in those situations.
+
+One way to remember these commands is that h is on the left, l is on the
+right and j points down.  In a picture: >
+
+		       k
+		   h     l
+		     j
+
+The best way to learn these commands is by using them.  Use the "i" command to
+insert some more lines of text.  Then use the hjkl keys to move around and
+insert a word somewhere.  Don't forget to press <Esc> to go back to Normal
+mode.  The |vimtutor| is also a nice way to learn by doing.
+
+For Japanese users, Hiroshi Iwatani suggested using this:
+
+			Komsomolsk
+			    ^
+			    |
+	   Huan Ho	<--- --->  Los Angeles
+	(Yellow river)	    |
+			    v
+			  Java (the island, not the programming language)
+
+==============================================================================
+*02.4*	Deleting characters
+
+To delete a character, move the cursor over it and type "x".  (This is a
+throwback to the old days of the typewriter, when you deleted things by typing
+xxxx over them.)  Move the cursor to the beginning of the first line, for
+example, and type xxxxxxx (seven x's) to delete "A very ".  The result should
+look like this:
+
+	+---------------------------------------+
+	|intelligent turtle			|
+	|Found programming UNIX a hurdle	|
+	|~					|
+	|~					|
+	|					|
+	+---------------------------------------+
+
+Now you can insert new text, for example by typing: >
+
+	iA young <Esc>
+
+This begins an insert (the i), inserts the words "A young", and then exits
+insert mode (the final <Esc>).	The result:
+
+	+---------------------------------------+
+	|A young intelligent turtle		|
+	|Found programming UNIX a hurdle	|
+	|~					|
+	|~					|
+	|					|
+	+---------------------------------------+
+
+
+DELETING A LINE
+
+To delete a whole line use the "dd" command.  The following line will
+then move up to fill the gap:
+
+	+---------------------------------------+
+	|Found programming UNIX a hurdle	|
+	|~					|
+	|~					|
+	|~					|
+	|					|
+	+---------------------------------------+
+
+
+DELETING A LINE BREAK
+
+In Vim you can join two lines together, which means that the line break
+between them is deleted.  The "J" command does this.
+   Take these two lines:
+
+	A young intelligent ~
+	turtle ~
+
+Move the cursor to the first line and press "J":
+
+	A young intelligent turtle ~
+
+==============================================================================
+*02.5*	Undo and Redo
+
+Suppose you delete too much.  Well, you can type it in again, but an easier
+way exists.  The "u" command undoes the last edit.  Take a look at this in
+action: After using "dd" to delete the first line, "u" brings it back.
+   Another one: Move the cursor to the A in the first line:
+
+	A young intelligent turtle ~
+
+Now type xxxxxxx to delete "A young".  The result is as follows:
+
+	 intelligent turtle ~
+
+Type "u" to undo the last delete.  That delete removed the g, so the undo
+restores the character.
+
+	g intelligent turtle ~
+
+The next "u" command restores the next-to-last character deleted:
+
+	ng intelligent turtle ~
+
+The next "u" command gives you the u, and so on:
+
+	ung intelligent turtle ~
+	oung intelligent turtle ~
+	young intelligent turtle ~
+	 young intelligent turtle ~
+	A young intelligent turtle ~
+
+	Note:
+	If you type "u" twice, and the result is that you get the same text
+	back, you have Vim configured to work Vi compatible.  Look here to fix
+	this: |not-compatible|.
+	   This text assumes you work "The Vim Way".  You might prefer to use
+	the good old Vi way, but you will have to watch out for small
+	differences in the text then.
+
+
+REDO
+
+If you undo too many times, you can press CTRL-R (redo) to reverse the
+preceding command.  In other words, it undoes the undo.  To see this in
+action, press CTRL-R twice.  The character A and the space after it disappear:
+
+	young intelligent turtle ~
+
+There's a special version of the undo command, the "U" (undo line) command.
+The undo line command undoes all the changes made on the last line that was
+edited.  Typing this command twice cancels the preceding "U".
+
+	A very intelligent turtle ~
+	  xxxx				Delete very
+
+	A intelligent turtle ~
+		      xxxxxx		Delete turtle
+
+	A intelligent ~
+					Restore line with "U"
+	A very intelligent turtle ~
+					Undo "U" with "u"
+	A intelligent ~
+
+The "U" command is a change by itself, which the "u" command undoes and CTRL-R
+redoes.  This might be a bit confusing.  Don't worry, with "u" and CTRL-R you
+can go to any of the situations you had.  More about that in section |32.2|.
+
+==============================================================================
+*02.6*	Other editing commands
+
+Vim has a large number of commands to change the text.  See |Q_in| and below.
+Here are a few often used ones.
+
+
+APPENDING
+
+The "i" command inserts a character before the character under the cursor.
+That works fine; but what happens if you want to add stuff to the end of the
+line?  For that you need to insert text after the cursor.  This is done with
+the "a" (append) command.
+   For example, to change the line
+
+	and that's not saying much for the turtle. ~
+to
+	and that's not saying much for the turtle!!! ~
+
+move the cursor over to the dot at the end of the line. Then type "x" to
+delete the period.  The cursor is now positioned at the end of the line on the
+e in turtle.  Now type >
+
+	a!!!<Esc>
+
+to append three exclamation points after the e in turtle:
+
+	and that's not saying much for the turtle!!! ~
+
+
+OPENING UP A NEW LINE
+
+The "o" command creates a new, empty line below the cursor and puts Vim in
+Insert mode.  Then you can type the text for the new line.
+   Suppose the cursor is somewhere in the first of these two lines:
+
+	A very intelligent turtle ~
+	Found programming UNIX a hurdle ~
+
+If you now use the "o" command and type new text: >
+
+	oThat liked using Vim<Esc>
+
+The result is:
+
+	A very intelligent turtle ~
+	That liked using Vim ~
+	Found programming UNIX a hurdle ~
+
+The "O" command (uppercase) opens a line above the cursor.
+
+
+USING A COUNT
+
+Suppose you want to move up nine lines.  You can type "kkkkkkkkk" or you can
+enter the command "9k".  In fact, you can precede many commands with a number.
+Earlier in this chapter, for instance, you added three exclamation points to
+the end of a line by typing "a!!!<Esc>".  Another way to do this is to use the
+command "3a!<Esc>".  The count of 3 tells the command that follows to triple
+its effect.  Similarly, to delete three characters, use the command "3x".  The
+count always comes before the command it applies to.
+
+==============================================================================
+*02.7*	Getting out
+
+To exit, use the "ZZ" command.  This command writes the file and exits.
+
+	Note:
+	Unlike many other editors, Vim does not automatically make a backup
+	file.  If you type "ZZ", your changes are committed and there's no
+	turning back.  You can configure the Vim editor to produce backup
+	files; see |07.4|.
+
+
+DISCARDING CHANGES
+
+Sometimes you will make a sequence of changes and suddenly realize you were
+better off before you started.  Not to worry; Vim has a
+quit-and-throw-things-away command.  It is: >
+
+	:q!
+
+Don't forget to press <Enter> to finish the command.
+
+For those of you interested in the details, the three parts of this command
+are the colon (:), which enters Command-line mode; the q command, which tells
+the editor to quit; and the override command modifier (!).
+   The override command modifier is needed because Vim is reluctant to throw
+away changes.  If you were to just type ":q", Vim would display an error
+message and refuse to exit:
+
+	E37: No write since last change (use ! to override) ~
+
+By specifying the override, you are in effect telling Vim, "I know that what
+I'm doing looks stupid, but I really want to do this."
+
+If you want to continue editing with Vim: The ":e!" command reloads the
+original version of the file.
+
+==============================================================================
+*02.8*	Finding help
+
+Everything you always wanted to know can be found in the Vim help files.
+Don't be afraid to ask!
+
+If you know what you are looking for, it is usually easier to search for it
+using the help system, instead of using Google.  Because the subjects follow
+a certain style guide.
+
+Also the help has the advantage of belonging to your particular Vim version.
+You won't see help for commands added later.  These would not work for you.
+
+To get generic help use this command: >
+
+	:help
+
+You could also use the first function key <F1>.  If your keyboard has a <Help>
+key it might work as well.
+   If you don't supply a subject, ":help" displays the general help window.
+The creators of Vim did something very clever (or very lazy) with the help
+system: They made the help window a normal editing window.  You can use all
+the normal Vim commands to move through the help information.  Therefore h, j,
+k, and l move left, down, up and right.
+   To get out of the help window, use the same command you use to get out of
+the editor: "ZZ".  This will only close the help window, not exit Vim.
+
+As you read the help text, you will notice some text enclosed in vertical bars
+(for example, |help|).  This indicates a hyperlink.  If you position the
+cursor anywhere between the bars and press CTRL-] (jump to tag), the help
+system takes you to the indicated subject.  (For reasons not discussed here,
+the Vim terminology for a hyperlink is tag.  So CTRL-] jumps to the location
+of the tag given by the word under the cursor.)
+   After a few jumps, you might want to go back.  CTRL-T (pop tag) takes you
+back to the preceding position.  CTRL-O (jump to older position) also works
+nicely here.
+   At the top of the help screen, there is the notation *help.txt*.  This name
+between "*" characters is used by the help system to define a tag (hyperlink
+destination).
+   See |29.1| for details about using tags.
+
+To get help on a given subject, use the following command: >
+
+	:help {subject}
+
+To get help on the "x" command, for example, enter the following: >
+
+	:help x
+
+To find out how to delete text, use this command: >
+
+	:help deleting
+
+To get a complete index of all Vim commands, use the following command: >
+
+	:help index
+
+When you need to get help for a control character command (for example,
+CTRL-A), you need to spell it with the prefix "CTRL-". >
+
+	:help CTRL-A
+
+The Vim editor has many different modes.  By default, the help system displays
+the normal-mode commands.  For example, the following command displays help
+for the normal-mode CTRL-H command: >
+
+	:help CTRL-H
+
+To identify other modes, use a mode prefix.  If you want the help for the
+insert-mode version of a command, use "i_".  For CTRL-H this gives you the
+following command: >
+
+	:help i_CTRL-H
+
+When you start the Vim editor, you can use several command-line arguments.
+These all begin with a dash (-).  To find what the -t argument does, for
+example, use the command: >
+
+	:help -t
+
+The Vim editor has a number of options that enable you to configure and
+customize the editor.  If you want help for an option, you need to enclose it
+in single quotation marks.  To find out what the 'number' option does, for
+example, use the following command: >
+
+	:help 'number'
+
+The table with all mode prefixes can be found below: |help-summary|.
+
+Special keys are enclosed in angle brackets.  To find help on the up-arrow key
+in Insert mode, for instance, use this command: >
+
+	:help i_<Up>
+
+If you see an error message that you don't understand, for example:
+
+	E37: No write since last change (use ! to override) ~
+
+You can use the error ID at the start to find help about it: >
+
+	:help E37
+
+
+Summary:					*help-summary*  >
+
+1) Use Ctrl-D after typing a topic and let Vim show all available topics.
+   Or press Tab to complete: >
+	:help some<Tab>
+<   More information on how to use the help: >
+	:help helphelp
+
+2) Follow the links in bars to related help.  You can go from the detailed
+   help to the user documentation, which describes certain commands more from
+   a user perspective and less detailed.  E.g. after: >
+	:help pattern.txt
+<   You can see the user guide topics |03.9| and |usr_27.txt| in the
+   introduction.
+
+3) Options are enclosed in single apostrophes.  To go to the help topic for the
+   list option: >
+	:help 'list'
+<   If you only know you are looking for a certain option, you can also do: >
+	:help options.txt
+<   to open the help page which describes all option handling and then search
+   using regular expressions, e.g. textwidth.
+   Certain options have their own namespace, e.g.: >
+	:help cpo-<letter>
+<   for the corresponding flag of the 'cpoptions' settings, substitute <letter>
+   by a specific flag, e.g.: >
+	:help cpo-;
+<   And for the 'guioptions' flags: >
+	:help go-<letter>
+
+4) Normal mode commands do not have a prefix. To go to the help page for the
+   "gt" command: >
+	:help gt
+
+5) Insert mode commands start with i_.  Help for deleting a word: >
+	:help i_CTRL-W
+
+6) Visual mode commands start with v_.  Help for jumping to the other side of
+   the Visual area: >
+	:help v_o
+
+7) Command line editing and arguments start with c_.  Help for using the
+   command argument %: >
+	:help c_%
+
+8) Ex-commands always start with ":", so to go to the ":s" command help: >
+	:help :s
+
+9) Commands specifically for debugging start with ">".  To go to the help
+   for the "cont" debug command: >
+	:help >cont
+
+10) Key combinations.  They usually start with a single letter indicating
+    the mode for which they can be used.  E.g.: >
+	:help i_CTRL-X
+<    takes you to the family of CTRL-X commands for insert mode which can be
+    used to auto-complete different things.  Note, that certain keys will
+    always be written the same, e.g. Control will always be CTRL.
+    For normal mode commands there is no prefix and the topic is available at
+    :h CTRL-<Letter>. E.g.  >
+	:help CTRL-W
+<    In contrast >
+	:help c_CTRL-R
+<    will describe what the CTRL-R does when entering commands in the Command
+    line and >
+	:help v_CTRL-A
+<    talks about incrementing numbers in visual mode and >
+	:help g_CTRL-A
+<    talks about the "g<C-A>" command (e.g. you have to press "g" then
+    <CTRL-A>).  Here the "g" stands for the normal command "g" which always
+    expects a second key before doing something similar to the commands
+    starting with "z".
+
+11) Regexp items always start with /.  So to get help for the "\+" quantifier
+    in Vim regexes: >
+	:help /\+
+<    If you need to know everything about regular expressions, start reading
+    at: >
+	:help pattern.txt
+
+12) Registers always start with "quote". To find out about the special ":"
+    register: >
+	:help quote:
+
+13) Vim script is available at >
+	:help eval.txt
+<    Certain aspects of the language are available at :h expr-X where "X" is a
+    single letter. E.g.  >
+	:help expr-!
+<    will take you to the topic describing the "!" (Not) operator for Vim
+    script.
+    Also important is >
+	:help function-list
+<    to find a short description of all functions available.  Help topics for
+    Vim script functions always include the "()", so: >
+	:help append()
+<    talks about the append Vim script function rather than how to append text
+    in the current buffer.
+
+14) Mappings are talked about in the help page :h |map.txt|. Use >
+	:help mapmode-i
+<    to find out about the |:imap| command.  Also use :map-topic
+    to find out about certain subtopics particular for mappings.  e.g: >
+	:help :map-local
+<    for buffer-local mappings or >
+	:help map-bar
+<    for how the '|' is handled in mappings.
+
+15) Command definitions are talked about :h command-topic, so use >
+	:help command-bar
+<    to find out about the '!' argument for custom commands.
+
+16) Window management commands always start with CTRL-W, so you find the
+    corresponding help at :h CTRL-W_letter.  E.g. >
+	:help CTRL-W_p
+<    for moving the previous accessed window.  You can also access >
+	:help windows.txt
+<    and read your way through if you are looking for window handling
+    commands.
+
+17) Use |:helpgrep| to search in all help pages (and also of any installed
+    plugins).  See |:helpgrep| for how to use it.
+    To search for a topic: >
+	:helpgrep topic
+<    This takes you to the first match.  To go to the next one: >
+	:cnext
+<    All matches are available in the quickfix window which can be opened
+    with: >
+	:copen
+<    Move around to the match you like and press Enter to jump to that help.
+
+18) The user manual.  This describes help topics for beginners in a rather
+    friendly way.  Start at |usr_toc.txt| to find the table of content (as you
+    might have guessed): >
+	:help usr_toc.txt
+<    Skim over the contents to find interesting topics. The "Digraphs" and
+    "Entering special characters" items are in chapter 24, so to go to that
+    particular help page: >
+	:help usr_24.txt
+<    Also if you want to access a certain chapter in the help, the chapter
+    number can be accessed directly like this: >
+	:help 10.1
+<    which goes to chapter 10.1 in |usr_10.txt| and talks about recording
+    macros.
+
+19) Highlighting groups.  Always start with hl-groupname.  E.g. >
+	:help hl-WarningMsg
+<    talks about the WarningMsg highlighting group.
+
+20) Syntax highlighting is namespaced to :syn-topic.  E.g. >
+	:help :syn-conceal
+<    talks about the conceal argument for the ":syn" command.
+
+21) Quickfix commands usually start with :c while location list commands
+    usually start with :l
+
+22) Autocommand events can be found by their name: >
+	:help BufWinLeave
+<    To see all possible events: >
+	:help autocommand-events
+
+23) Command-line switches always start with "-".  So for the help of the -f
+    command switch of Vim use: >
+	:help -f
+
+24) Optional features always start with "+".  To find out about the
+    conceal feature use: >
+	:help +conceal
+
+25) Documentation for included filetype specific functionality is usually
+    available in the form ft-<filetype>-<functionality>.  So >
+	:help ft-c-syntax
+<    talks about the C syntax file and the option it provides.  Sometimes,
+    additional sections for omni completion >
+	:help ft-php-omni
+<    or filetype plugins >
+	:help ft-tex-plugin
+<    are available.
+
+26) Error and Warning codes can be looked up directly in the help.  So >
+	:help E297
+<    takes you exactly to the description of the swap error message and >
+	:help W10
+<    talks about the warning "Changing a readonly file".
+    Sometimes, however, those error codes are not described, but rather are
+    listed at the Vim command that usually causes this.  So: >
+	:help E128
+<    takes you to the |:function| command
+
+
+==============================================================================
+
+Next chapter: |usr_03.txt|  Moving around
+
+Copyright: see |manual-copyright|  vim:tw=78:ts=8:noet:ft=help:norl: