FM / doc

/usr/share/vim/vim82/doc

Name	Size	Mode	Actions
arabic.txt	11901	0644	edit dl rm
autocmd.txt	72220	0644	edit dl rm
change.txt	78049	0644	edit dl rm
channel.txt	50309	0644	edit dl rm
cmdline.txt	49342	0644	edit dl rm
debug.txt	6896	0644	edit dl rm
debugger.txt	5443	0644	edit dl rm
develop.txt	22861	0644	edit dl rm
diff.txt	17024	0644	edit dl rm
digraph.txt	61978	0644	edit dl rm
editing.txt	74161	0644	edit dl rm
eval.txt	541209	0644	edit dl rm
farsi.txt	523	0644	edit dl rm
filetype.txt	27594	0644	edit dl rm
fold.txt	23689	0644	edit dl rm
ft_ada.txt	18246	0644	edit dl rm
ft_rust.txt	9596	0644	edit dl rm
ft_sql.txt	30700	0644	edit dl rm
gui.txt	52741	0644	edit dl rm
gui_w32.txt	19451	0644	edit dl rm
gui_x11.txt	29906	0644	edit dl rm
hangulin.txt	598	0644	edit dl rm
hebrew.txt	5666	0644	edit dl rm
help.txt	8899	0644	edit dl rm
helphelp.txt	15729	0644	edit dl rm
howto.txt	2916	0644	edit dl rm
if_cscop.txt	19325	0644	edit dl rm
if_lua.txt	16755	0644	edit dl rm
if_mzsch.txt	11941	0644	edit dl rm
if_ole.txt	7361	0644	edit dl rm
if_perl.txt	11281	0644	edit dl rm
if_pyth.txt	38435	0644	edit dl rm
if_ruby.txt	8516	0644	edit dl rm
if_sniff.txt	271	0644	edit dl rm
if_tcl.txt	22951	0644	edit dl rm
indent.txt	42284	0644	edit dl rm
index.txt	80638	0644	edit dl rm
insert.txt	85294	0644	edit dl rm
intro.txt	38972	0644	edit dl rm
map.txt	70799	0644	edit dl rm
mbyte.txt	59642	0644	edit dl rm
message.txt	31425	0644	edit dl rm
mlang.txt	8187	0644	edit dl rm
motion.txt	51341	0644	edit dl rm
netbeans.txt	37982	0644	edit dl rm
options.txt	391308	0644	edit dl rm
os_390.txt	4749	0644	edit dl rm
os_amiga.txt	5466	0644	edit dl rm
os_beos.txt	293	0644	edit dl rm
os_dos.txt	12378	0644	edit dl rm
os_haiku.txt	8592	0644	edit dl rm
os_mac.txt	6856	0644	edit dl rm
os_mint.txt	391	0644	edit dl rm
os_msdos.txt	523	0644	edit dl rm
os_os2.txt	299	0644	edit dl rm
os_qnx.txt	4071	0644	edit dl rm
os_risc.txt	328	0644	edit dl rm
os_unix.txt	2603	0644	edit dl rm
os_vms.txt	32906	0644	edit dl rm
os_win32.txt	13351	0644	edit dl rm
pattern.txt	60137	0644	edit dl rm
pi_getscript.txt	21082	0644	edit dl rm
pi_gzip.txt	1294	0644	edit dl rm
pi_logipat.txt	4196	0644	edit dl rm
pi_netrw.txt	179286	0644	edit dl rm
pi_paren.txt	2274	0644	edit dl rm
pi_spec.txt	4127	0644	edit dl rm
pi_tar.txt	6813	0644	edit dl rm
pi_vimball.txt	11859	0644	edit dl rm
pi_zip.txt	7294	0644	edit dl rm
popup.txt	39472	0644	edit dl rm
print.txt	31025	0644	edit dl rm
quickfix.txt	82925	0644	edit dl rm
quickref.txt	72144	0644	edit dl rm
quotes.txt	12748	0644	edit dl rm
recover.txt	10720	0644	edit dl rm
remote.txt	8417	0644	edit dl rm
repeat.txt	42186	0644	edit dl rm
rileft.txt	4938	0644	edit dl rm
russian.txt	3024	0644	edit dl rm
scroll.txt	13781	0644	edit dl rm
sign.txt	25859	0644	edit dl rm
spell.txt	64099	0644	edit dl rm
sponsor.txt	7203	0644	edit dl rm
starting.txt	73591	0644	edit dl rm
syntax.txt	225863	0644	edit dl rm
tabpage.txt	17248	0644	edit dl rm
tags	354812	0644	edit dl rm
tagsrch.txt	40278	0644	edit dl rm
term.txt	47498	0644	edit dl rm
terminal.txt	56100	0644	edit dl rm
testing.txt	14954	0644	edit dl rm
textprop.txt	13402	0644	edit dl rm
tips.txt	21067	0644	edit dl rm
todo.txt	309420	0644	edit dl rm
uganda.txt	14028	0644	edit dl rm
undo.txt	16584	0644	edit dl rm
usr_01.txt	7081	0644	edit dl rm
usr_02.txt	24226	0644	edit dl rm
usr_03.txt	23872	0644	edit dl rm
usr_04.txt	19131	0644	edit dl rm
usr_05.txt	27023	0644	edit dl rm
usr_06.txt	9611	0644	edit dl rm
usr_07.txt	15995	0644	edit dl rm
usr_08.txt	19378	0644	edit dl rm
usr_09.txt	11502	0644	edit dl rm
usr_10.txt	29200	0644	edit dl rm
usr_11.txt	13025	0644	edit dl rm
usr_12.txt	13429	0644	edit dl rm
usr_20.txt	13709	0644	edit dl rm
usr_21.txt	18456	0644	edit dl rm
usr_22.txt	14999	0644	edit dl rm
usr_23.txt	12744	0644	edit dl rm
usr_24.txt	20827	0644	edit dl rm
usr_25.txt	19176	0644	edit dl rm
usr_26.txt	8259	0644	edit dl rm
usr_27.txt	17709	0644	edit dl rm
usr_28.txt	16020	0644	edit dl rm
usr_29.txt	20121	0644	edit dl rm
usr_30.txt	22658	0644	edit dl rm
usr_31.txt	10399	0644	edit dl rm
usr_32.txt	5378	0644	edit dl rm
usr_40.txt	23195	0644	edit dl rm
usr_41.txt	97378	0644	edit dl rm
usr_42.txt	13853	0644	edit dl rm
usr_43.txt	7409	0644	edit dl rm
usr_44.txt	28948	0644	edit dl rm
usr_45.txt	17688	0644	edit dl rm
usr_46.txt	7096	0644	edit dl rm
usr_90.txt	16836	0644	edit dl rm
usr_toc.txt	9505	0644	edit dl rm
various.txt	31097	0644	edit dl rm
version4.txt	13911	0644	edit dl rm
version5.txt	308532	0644	edit dl rm
version6.txt	576940	0644	edit dl rm
version7.txt	674701	0644	edit dl rm
version8.txt	1940307	0644	edit dl rm
vim9.txt	57158	0644	edit dl rm
visual.txt	21794	0644	edit dl rm
vi_diff.txt	57428	0644	edit dl rm
windows.txt	55732	0644	edit dl rm
workshop.txt	371	0644	edit dl rm

Edit: /usr/share/vim/vim82/doc/usr_21.txt (18456B)

*usr_21.txt*	For Vim version 8.2.  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

==============================================================================
*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

cmd: