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, 502 insertions, 0 deletions

diff --git a/runtime/doc/usr_21.txt b/runtime/doc/usr_21.txt
new file mode 100644
index 0000000..95ded58
--- /dev/null
+++ b/runtime/doc/usr_21.txt
@@ -0,0 +1,502 @@
+*usr_21.txt*	For Vim version 9.1.  Last change: 2019 Apr 25
+
+		     VIM USER MANUAL - by Bram Moolenaar
+
+			   Go away and come back
+
+
+This chapter goes into mixing the use of other programs with Vim.  Either by
+executing program from inside Vim or by leaving Vim and coming back later.
+Furthermore, this is about the ways to remember the state of Vim and restore
+it later.
+
+|21.1|	Suspend and resume
+|21.2|	Executing shell commands
+|21.3|	Remembering information; viminfo
+|21.4|	Sessions
+|21.5|	Views
+|21.6|	Modelines
+
+     Next chapter: |usr_22.txt|  Finding the file to edit
+ Previous chapter: |usr_20.txt|  Typing command-line commands quickly
+Table of contents: |usr_toc.txt|
+
+==============================================================================
+*21.1*	Suspend and resume
+
+Like most Unix programs Vim can be suspended by pressing CTRL-Z.  This stops
+Vim and takes you back to the shell it was started in.  You can then do any
+other commands until you are bored with them.  Then bring back Vim with the
+"fg" command. >
+
+	CTRL-Z
+	{any sequence of shell commands}
+	fg
+
+You are right back where you left Vim, nothing has changed.
+   In case pressing CTRL-Z doesn't work, you can also use ":suspend".
+Don't forget to bring Vim back to the foreground, you would lose any changes
+that you made!
+
+Only Unix has support for this.  On other systems Vim will start a shell for
+you.  This also has the functionality of being able to execute shell commands.
+But it's a new shell, not the one that you started Vim from.
+   When you are running the GUI you can't go back to the shell where Vim was
+started.  CTRL-Z will minimize the Vim window instead.
+
+==============================================================================
+*21.2*	Executing shell commands
+
+To execute a single shell command from Vim use ":!{command}".  For example, to
+see a directory listing: >
+
+	:!ls
+	:!dir
+
+The first one is for Unix, the second one for MS-Windows.
+   Vim will execute the program.  When it ends you will get a prompt to hit
+<Enter>.  This allows you to have a look at the output from the command before
+returning to the text you were editing.
+   The "!" is also used in other places where a program is run.  Let's take
+a look at an overview:
+
+	:!{program}		execute {program}
+	:r !{program}		execute {program} and read its output
+	:w !{program}		execute {program} and send text to its input
+	:[range]!{program}	filter text through {program}
+
+Notice that the presence of a range before "!{program}" makes a big
+difference.  Without it executes the program normally, with the range a number
+of text lines is filtered through the program.
+
+Executing a whole row of programs this way is possible.  But a shell is much
+better at it.  You can start a new shell this way: >
+
+	:shell
+
+This is similar to using CTRL-Z to suspend Vim.  The difference is that a new
+shell is started.
+
+When using the GUI the shell will be using the Vim window for its input and
+output.  Since Vim is not a terminal emulator, this will not work perfectly.
+If you have trouble, try toggling the 'guipty' option.  If this still doesn't
+work well enough, start a new terminal to run the shell in.  For example with:
+>
+	:!xterm&
+
+==============================================================================
+*21.3*	Remembering information; viminfo
+
+After editing for a while you will have text in registers, marks in various
+files, a command line history filled with carefully crafted commands.  When
+you exit Vim all of this is lost.  But you can get it back!
+
+The viminfo file is designed to store status information:
+
+	Command-line and Search pattern history
+	Text in registers
+	Marks for various files
+	The buffer list
+	Global variables
+
+Each time you exit Vim it will store this information in a file, the viminfo
+file.  When Vim starts again, the viminfo file is read and the information
+restored.
+
+The 'viminfo' option is set by default to restore a limited number of items.
+You might want to set it to remember more information.  This is done through
+the following command: >
+
+	:set viminfo=string
+
+The string specifies what to save.  The syntax of this string is an option
+character followed by an argument.  The option/argument pairs are separated by
+commas.
+   Take a look at how you can build up your own viminfo string.  First, the '
+option is used to specify how many files for which you save marks (a-z).  Pick
+a nice even number for this option (1000, for instance).  Your command now
+looks like this: >
+
+	:set viminfo='1000
+
+The f option controls whether global marks (A-Z and 0-9) are stored.  If this
+option is 0, none are stored.  If it is 1 or you do not specify an f option,
+the marks are stored.  You want this feature, so now you have this: >
+
+	:set viminfo='1000,f1
+
+The < option controls how many lines are saved for each of the registers.  By
+default, all the lines are saved.  If 0, nothing is saved.  To avoid adding
+thousands of lines to your viminfo file (which might never get used and makes
+starting Vim slower) you use a maximum of 500 lines: >
+
+	:set viminfo='1000,f1,<500
+<
+Other options you might want to use:
+	:	number of lines to save from the command line history
+	@	number of lines to save from the input line history
+	/	number of lines to save from the search history
+	r	removable media, for which no marks will be stored (can be
+		used several times)
+	!	global variables that start with an uppercase letter and
+		don't contain lowercase letters
+	h	disable 'hlsearch' highlighting when starting
+	%	the buffer list (only restored when starting Vim without file
+		arguments)
+	c	convert the text using 'encoding'
+	n	name used for the viminfo file (must be the last option)
+
+See the 'viminfo' option and |viminfo-file| for more information.
+
+When you run Vim multiple times, the last one exiting will store its
+information.  This may cause information that previously exiting Vims stored
+to be lost.  Each item can be remembered only once.
+
+
+GETTING BACK TO WHERE YOU STOPPED VIM
+
+You are halfway editing a file and it's time to leave for holidays.  You exit
+Vim and go enjoy yourselves, forgetting all about your work.  After a couple
+of weeks you start Vim, and type:
+>
+	'0
+
+And you are right back where you left Vim.  So you can get on with your work.
+   Vim creates a mark each time you exit Vim.  The last one is '0.  The
+position that '0 pointed to is made '1.  And '1 is made to '2, and so forth.
+Mark '9 is lost.
+   The |:marks| command is useful to find out where '0 to '9 will take you.
+
+
+GETTING BACK TO SOME FILE
+
+If you want to go back to a file that you edited recently, but not when
+exiting Vim, there is a slightly more complicated way.  You can see a list of
+files by typing the command: >
+
+	:oldfiles
+<	1: ~/.viminfo ~
+	2: ~/text/resume.txt ~
+	3: /tmp/draft ~
+
+Now you would like to edit the second file, which is in the list preceded by
+"2:".  You type: >
+
+	:e #<2
+
+Instead of ":e" you can use any command that has a file name argument, the
+"#<2" item works in the same place as "%" (current file name) and "#"
+(alternate file name).  So you can also split the window to edit the third
+file: >
+
+	:split #<3
+
+That #<123 thing is a bit complicated when you just want to edit a file.
+Fortunately there is a simpler way: >
+
+	:browse oldfiles
+<	1: ~/.viminfo ~
+	2: ~/text/resume.txt ~
+	3: /tmp/draft ~
+	-- More --
+
+You get the same list of files as with |:oldfiles|.  If you want to edit
+"resume.txt" first press "q" to stop the listing.  You will get a prompt:
+
+	Type number and <Enter> (empty cancels): ~
+
+Type "2" and press <Enter> to edit the second file.
+
+More info at |:oldfiles|, |v:oldfiles| and |c_#<|.
+
+
+MOVE INFO FROM ONE VIM TO ANOTHER
+
+You can use the ":wviminfo" and ":rviminfo" commands to save and restore the
+information while still running Vim.  This is useful for exchanging register
+contents between two instances of Vim, for example.  In the first Vim do: >
+
+	:wviminfo! ~/tmp/viminfo
+
+And in the second Vim do: >
+
+	:rviminfo! ~/tmp/viminfo
+
+Obviously, the "w" stands for "write" and the "r" for "read".
+   The ! character is used by ":wviminfo" to forcefully overwrite an existing
+file.  When it is omitted, and the file exists, the information is merged into
+the file.
+   The ! character used for ":rviminfo" means that all the information is
+used, this may overwrite existing information.  Without the ! only information
+that wasn't set is used.
+   These commands can also be used to store info and use it again later.  You
+could make a directory full of viminfo files, each containing info for a
+different purpose.
+
+==============================================================================
+*21.4*	Sessions
+
+Suppose you are editing along, and it is the end of the day.  You want to quit
+work and pick up where you left off the next day.  You can do this by saving
+your editing session and restoring it the next day.
+   A Vim session contains all the information about what you are editing.
+This includes things such as the file list, window layout, global variables,
+options and other information.  (Exactly what is remembered is controlled by
+the 'sessionoptions' option, described below.)
+   The following command creates a session file: >
+
+	:mksession vimbook.vim
+
+Later if you want to restore this session, you can use this command: >
+
+	:source vimbook.vim
+
+If you want to start Vim and restore a specific session, you can use the
+following command: >
+
+	vim -S vimbook.vim
+
+This tells Vim to read a specific file on startup.  The 'S' stands for
+session (actually, you can source any Vim script with -S, thus it might as
+well stand for "source").
+
+The windows that were open are restored, with the same position and size as
+before.  Mappings and option values are like before.
+   What exactly is restored depends on the 'sessionoptions' option.  The
+default value is:
+"blank,buffers,curdir,folds,help,options,tabpages,winsize,terminal".
+
+	blank		keep empty windows
+	buffers		all buffers, not only the ones in a window
+	curdir		the current directory
+	folds		folds, also manually created ones
+	help		the help window
+	options		all options and mappings
+	tabpages	all tab pages
+	winsize		window sizes
+	terminal	include terminal windows
+
+Change this to your liking.  To also restore the size of the Vim window, for
+example, use: >
+
+	:set sessionoptions+=resize
+
+
+SESSION HERE, SESSION THERE
+
+The obvious way to use sessions is when working on different projects.
+Suppose you store your session files in the directory "~/.vim".  You are
+currently working on the "secret" project and have to switch to the "boring"
+project: >
+
+	:wall
+	:mksession! ~/.vim/secret.vim
+	:source ~/.vim/boring.vim
+
+This first uses ":wall" to write all modified files.  Then the current session
+is saved, using ":mksession!".  This overwrites the previous session.  The
+next time you load the secret session you can continue where you were at this
+point.  And finally you load the new "boring" session.
+
+If you open help windows, split and close various windows, and generally mess
+up the window layout, you can go back to the last saved session: >
+
+	:source ~/.vim/boring.vim
+
+Thus you have complete control over whether you want to continue next time
+where you are now, by saving the current setup in a session, or keep the
+session file as a starting point.
+   Another way of using sessions is to create a window layout that you like to
+use, and save this in a session.  Then you can go back to this layout whenever
+you want.
+   For example, this is a nice layout to use:
+
+	+----------------------------------------+
+	|		   VIM - main help file  |
+	|					 |
+	|Move around:  Use the cursor keys, or "h|
+	|help.txt================================|
+	|explorer   |				 |
+	|dir	    |~				 |
+	|dir	    |~				 |
+	|file	    |~				 |
+	|file	    |~				 |
+	|file	    |~				 |
+	|file	    |~				 |
+	|~/=========|[No File]===================|
+	|					 |
+	+----------------------------------------+
+
+This has a help window at the top, so that you can read this text.  The narrow
+vertical window on the left contains a file explorer.  This is a Vim plugin
+that lists the contents of a directory.  You can select files to edit there.
+More about this in the next chapter.
+   Create this from a just started Vim with: >
+
+	:help
+	CTRL-W w
+	:vertical split ~/
+
+You can resize the windows a bit to your liking.  Then save the session with:
+>
+	:mksession ~/.vim/mine.vim
+
+Now you can start Vim with this layout: >
+
+	vim -S ~/.vim/mine.vim
+
+Hint: To open a file you see listed in the explorer window in the empty
+window, move the cursor to the filename and press "O".  Double clicking with
+the mouse will also do this.
+
+
+UNIX AND MS-WINDOWS
+
+Some people have to do work on MS-Windows systems one day and on Unix another
+day.  If you are one of them, consider adding "slash" and "unix" to
+'sessionoptions'.  The session files will then be written in a format that can
+be used on both systems.  This is the command to put in your vimrc file: >
+
+	:set sessionoptions+=unix,slash
+
+Vim will use the Unix format then, because the MS-Windows Vim can read and
+write Unix files, but Unix Vim can't read MS-Windows format session files.
+Similarly, MS-Windows Vim understands file names with / to separate names, but
+Unix Vim doesn't understand \.
+
+
+SESSIONS AND VIMINFO
+
+Sessions store many things, but not the position of marks, contents of
+registers and the command line history.  You need to use the viminfo feature
+for these things.
+   In most situations you will want to use sessions separately from viminfo.
+This can be used to switch to another session, but keep the command line
+history.  And yank text into registers in one session, and paste it back in
+another session.
+   You might prefer to keep the info with the session.  You will have to do
+this yourself then.  Example: >
+
+	:mksession! ~/.vim/secret.vim
+	:wviminfo! ~/.vim/secret.viminfo
+
+And to restore this again: >
+
+	:source ~/.vim/secret.vim
+	:rviminfo! ~/.vim/secret.viminfo
+
+==============================================================================
+*21.5*	Views
+
+A session stores the looks of the whole of Vim.  When you want to store the
+properties for one window only, use a view.
+   The use of a view is for when you want to edit a file in a specific way.
+For example, you have line numbers enabled with the 'number' option and
+defined a few folds.  Just like with sessions, you can remember this view on
+the file and restore it later.  Actually, when you store a session, it stores
+the view of each window.
+   There are two basic ways to use views.  The first is to let Vim pick a name
+for the view file.  You can restore the view when you later edit the same
+file.  To store the view for the current window: >
+
+	:mkview
+
+Vim will decide where to store the view.  When you later edit the same file
+you get the view back with this command: >
+
+	:loadview
+
+That's easy, isn't it?
+   Now you want to view the file without the 'number' option on, or with all
+folds open, you can set the options to make the window look that way.  Then
+store this view with: >
+
+	:mkview 1
+
+Obviously, you can get this back with: >
+
+	:loadview 1
+
+Now you can switch between the two views on the file by using ":loadview" with
+and without the "1" argument.
+   You can store up to ten views for the same file this way, one unnumbered
+and nine numbered 1 to 9.
+
+
+A VIEW WITH A NAME
+
+The second basic way to use views is by storing the view in a file with a name
+you choose.  This view can be loaded while editing another file.  Vim will
+then switch to editing the file specified in the view.  Thus you can use this
+to quickly switch to editing another file, with all its options set as you
+saved them.
+   For example, to save the view of the current file: >
+
+	:mkview ~/.vim/main.vim
+
+You can restore it with: >
+
+	:source ~/.vim/main.vim
+
+==============================================================================
+*21.6*	Modelines
+
+When editing a specific file, you might set options specifically for that
+file.  Typing these commands each time is boring.  Using a session or view for
+editing a file doesn't work when sharing the file between several people.
+   The solution for this situation is adding a modeline to the file.  This is
+a line of text that tells Vim the values of options, to be used in this file
+only.
+   A typical example is a C program where you make indents by a multiple of 4
+spaces.  This requires setting the 'shiftwidth' option to 4.  This modeline
+will do that:
+
+	/* vim:set shiftwidth=4: */ ~
+
+Put this line as one of the first or last five lines in the file.  When
+editing the file, you will notice that 'shiftwidth' will have been set to
+four.  When editing another file, it's set back to the default value of eight.
+   For some files the modeline fits well in the header, thus it can be put at
+the top of the file.  For text files and other files where the modeline gets
+in the way of the normal contents, put it at the end of the file.
+
+The 'modelines' option specifies how many lines at the start and end of the
+file are inspected for containing a modeline.  To inspect ten lines: >
+
+	:set modelines=10
+
+The 'modeline' option can be used to switch this off.  Do this when you are
+working as root on Unix or Administrator on MS-Windows, or when you don't
+trust the files you are editing: >
+
+	:set nomodeline
+
+Use this format for the modeline:
+
+	any-text vim:set {option}={value} ... : any-text ~
+
+The "any-text" indicates that you can put any text before and after the part
+that Vim will use.  This allows making it look like a comment, like what was
+done above with /* and */.
+   The " vim:" part is what makes Vim recognize this line.  There must be
+white space before "vim", or "vim" must be at the start of the line.  Thus
+using something like "gvim:" will not work.
+   The part between the colons is a ":set" command.  It works the same way as
+typing the ":set" command, except that you need to insert a backslash before a
+colon (otherwise it would be seen as the end of the modeline).
+
+Another example:
+
+	// vim:set textwidth=72 dir=c\:\tmp:  use c:\tmp here ~
+
+There is an extra backslash before the first colon, so that it's included in
+the ":set" command.  The text after the second colon is ignored, thus a remark
+can be placed there.
+
+For more details see |modeline|.
+
+==============================================================================
+
+Next chapter: |usr_22.txt|  Finding the file to edit
+
+Copyright: see |manual-copyright|  vim:tw=78:ts=8:noet:ft=help:norl: