FM / doc

/usr/share/vim/vim82/doc

Name	Size	Mode	Actions
arabic.txt	12204	0644	edit dl rm
autocmd.txt	74314	0644	edit dl rm
builtin.txt	389075	0644	edit dl rm
change.txt	79214	0644	edit dl rm
channel.txt	50387	0644	edit dl rm
cmdline.txt	50130	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	17515	0644	edit dl rm
digraph.txt	62082	0644	edit dl rm
editing.txt	75319	0644	edit dl rm
eval.txt	178282	0644	edit dl rm
farsi.txt	523	0644	edit dl rm
filetype.txt	27998	0644	edit dl rm
fold.txt	24139	0644	edit dl rm
ft_ada.txt	18246	0644	edit dl rm
ft_ps1.txt	2187	0644	edit dl rm
ft_raku.txt	4183	0644	edit dl rm
ft_rust.txt	9596	0644	edit dl rm
ft_sql.txt	30697	0644	edit dl rm
gui.txt	53076	0644	edit dl rm
gui_w32.txt	19117	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	9098	0644	edit dl rm
help.txt.vim-tiny	1431	0644	edit dl rm
helphelp.txt	15933	0644	edit dl rm
howto.txt	2916	0644	edit dl rm
if_cscop.txt	19325	0644	edit dl rm
if_lua.txt	18546	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	38644	0644	edit dl rm
if_ruby.txt	8516	0644	edit dl rm
if_sniff.txt	271	0644	edit dl rm
if_tcl.txt	22941	0644	edit dl rm
indent.txt	41902	0644	edit dl rm
index.txt	81125	0644	edit dl rm
insert.txt	87568	0644	edit dl rm
intro.txt	38934	0644	edit dl rm
map.txt	74464	0644	edit dl rm
mbyte.txt	59640	0644	edit dl rm
message.txt	31671	0644	edit dl rm
mlang.txt	8187	0644	edit dl rm
motion.txt	51891	0644	edit dl rm
netbeans.txt	37982	0644	edit dl rm
options.txt	401254	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	15496	0644	edit dl rm
os_haiku.txt	8496	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	32903	0644	edit dl rm
os_win32.txt	14404	0644	edit dl rm
pattern.txt	62949	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	181824	0644	edit dl rm
pi_paren.txt	2274	0644	edit dl rm
pi_spec.txt	4127	0644	edit dl rm
pi_tar.txt	7247	0644	edit dl rm
pi_vimball.txt	11859	0644	edit dl rm
pi_zip.txt	7491	0644	edit dl rm
popup.txt	39689	0644	edit dl rm
print.txt	31209	0644	edit dl rm
quickfix.txt	83331	0644	edit dl rm
quickref.txt	72492	0644	edit dl rm
quotes.txt	12748	0644	edit dl rm
README.Debian	324	0644	edit dl rm
recover.txt	10720	0644	edit dl rm
remote.txt	8420	0644	edit dl rm
repeat.txt	43565	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	26870	0644	edit dl rm
spell.txt	64095	0644	edit dl rm
sponsor.txt	6803	0644	edit dl rm
starting.txt	73599	0644	edit dl rm
syntax.txt	229795	0644	edit dl rm
tabpage.txt	17248	0644	edit dl rm
tags	362670	0644	edit dl rm
tags.vim-tiny	30	0644	edit dl rm
tagsrch.txt	40278	0644	edit dl rm
term.txt	49822	0644	edit dl rm
terminal.txt	57098	0644	edit dl rm
testing.txt	16678	0644	edit dl rm
textprop.txt	16395	0644	edit dl rm
tips.txt	21089	0644	edit dl rm
todo.txt	307147	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	24229	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	10638	0644	edit dl rm
usr_07.txt	15995	0644	edit dl rm
usr_08.txt	19379	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	13433	0644	edit dl rm
usr_20.txt	13733	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	95626	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	31483	0644	edit dl rm
version4.txt	13911	0644	edit dl rm
version5.txt	308533	0644	edit dl rm
version6.txt	576942	0644	edit dl rm
version7.txt	674703	0644	edit dl rm
version8.txt	1940466	0644	edit dl rm
vim9.txt	68612	0644	edit dl rm
visual.txt	21846	0644	edit dl rm
vi_diff.txt	57428	0644	edit dl rm
windows.txt	55898	0644	edit dl rm
workshop.txt	371	0644	edit dl rm

Edit: /usr/share/vim/vim82/doc/usr_40.txt (23195B)

*usr_40.txt*	For Vim version 8.2.  Last change: 2020 Sep 02

VIM USER MANUAL - by Bram Moolenaar

Make new commands

Vim is an extensible editor.  You can take a sequence of commands you use
often and turn it into a new command.  Or redefine an existing command.
Autocommands make it possible to execute commands automatically.

|40.1|	Key mapping
|40.2|	Defining command-line commands
|40.3|	Autocommands

==============================================================================
*40.1*	Key mapping

A simple mapping was explained in section |05.3|.  The principle is that one
sequence of key strokes is translated into another sequence of key strokes.
This is a simple, yet powerful mechanism.
   The simplest form is that one key is mapped to a sequence of keys.  Since
the function keys, except <F1>, have no predefined meaning in Vim, these are
good choices to map.  Example: >

:map <F2> GoDate: <Esc>:read !date<CR>kJ

This shows how three modes are used.  After going to the last line with "G",
the "o" command opens a new line and starts Insert mode.  The text "Date: " is
inserted and <Esc> takes you out of insert mode.
   Notice the use of special keys inside <>.  This is called angle bracket
notation.  You type these as separate characters, not by pressing the key
itself.  This makes the mappings better readable and you can copy and paste
the text without problems.
   The ":" character takes Vim to the command line.  The ":read !date" command
reads the output from the "date" command and appends it below the current
line.  The <CR> is required to execute the ":read" command.
   At this point of execution the text looks like this:

Date:  ~
	Fri Jun 15 12:54:34 CEST 2001 ~

Now "kJ" moves the cursor up and joins the lines together.
   To decide which key or keys you use for mapping, see |map-which-keys|.

MAPPING AND MODES

The ":map" command defines remapping for keys in Normal mode.  You can also
define mappings for other modes.  For example, ":imap" applies to Insert mode.
You can use it to insert a date below the cursor: >

:imap <F2> <CR>Date: <Esc>:read !date<CR>kJ

It looks a lot like the mapping for <F2> in Normal mode, only the start is
different.  The <F2> mapping for Normal mode is still there.  Thus you can map
the same key differently for each mode.
   Notice that, although this mapping starts in Insert mode, it ends in Normal
mode.  If you want it to continue in Insert mode, append an "a" to the
mapping.

Here is an overview of map commands and in which mode they work:

:map		Normal, Visual and Operator-pending
	:vmap		Visual
	:nmap		Normal
	:omap		Operator-pending
	:map!		Insert and Command-line
	:imap		Insert
	:cmap		Command-line

Operator-pending mode is when you typed an operator character, such as "d" or
"y", and you are expected to type the motion command or a text object.  Thus
when you type "dw", the "w" is entered in operator-pending mode.

Suppose that you want to define <F7> so that the command d<F7> deletes a C
program block (text enclosed in curly braces, {}).  Similarly y<F7> would yank
the program block into the unnamed register.  Therefore, what you need to do
is to define <F7> to select the current program block.  You can do this with
the following command: >

:omap <F7> a{

This causes <F7> to perform a select block "a{" in operator-pending mode, just
like you typed it.  This mapping is useful if typing a { on your keyboard is a
bit difficult.

LISTING MAPPINGS

To see the currently defined mappings, use ":map" without arguments.  Or one
of the variants that include the mode in which they work.  The output could
look like this:

_g		 :call MyGrep(1)<CR> ~
	v  <F2>		 :s/^/> /<CR>:noh<CR>`` ~
	n  <F2>		 :.,$s/^/> /<CR>:noh<CR>`` ~
	   <xHome>	 <Home>
	   <xEnd>	 <End>

The first column of the list shows in which mode the mapping is effective.
This is "n" for Normal mode, "i" for Insert mode, etc.  A blank is used for a
mapping defined with ":map", thus effective in both Normal and Visual mode.
   One useful purpose of listing the mapping is to check if special keys in <>
form have been recognized (this only works when color is supported).  For
example, when <Esc> is displayed in color, it stands for the escape character.
When it has the same color as the other text, it is five characters.

REMAPPING

The result of a mapping is inspected for other mappings in it.  For example,
the mappings for <F2> above could be shortened to: >

:map <F2> G<F3>
	:imap <F2> <Esc><F3>
	:map <F3>  oDate: <Esc>:read !date<CR>kJ

For Normal mode <F2> is mapped to go to the last line, and then behave like
<F3> was pressed.  In Insert mode <F2> stops Insert mode with <Esc> and then
also uses <F3>.  Then <F3> is mapped to do the actual work.

Suppose you hardly ever use Ex mode, and want to use the "Q" command to format
text (this was so in old versions of Vim).  This mapping will do it: >

:map Q gq

But, in rare cases you need to use Ex mode anyway.  Let's map "gQ" to Q, so
that you can still go to Ex mode: >

:map gQ Q

What happens now is that when you type "gQ" it is mapped to "Q".  So far so
good.  But then "Q" is mapped to "gq", thus typing "gQ" results in "gq", and
you don't get to Ex mode at all.
   To avoid keys to be mapped again, use the ":noremap" command: >

:noremap gQ Q

Now Vim knows that the "Q" is not to be inspected for mappings that apply to
it.  There is a similar command for every mode:

:noremap	Normal, Visual and Operator-pending
	:vnoremap	Visual
	:nnoremap	Normal
	:onoremap	Operator-pending
	:noremap!	Insert and Command-line
	:inoremap	Insert
	:cnoremap	Command-line

RECURSIVE MAPPING

When a mapping triggers itself, it will run forever.  This can be used to
repeat an action an unlimited number of times.
   For example, you have a list of files that contain a version number in the
first line.  You edit these files with "vim *.txt".  You are now editing the
first file.  Define this mapping: >

:map ,, :s/5.1/5.2/<CR>:wnext<CR>,,

Now you type ",,".  This triggers the mapping.  It replaces "5.1" with "5.2"
in the first line.  Then it does a ":wnext" to write the file and edit the
next one.  The mapping ends in ",,".  This triggers the same mapping again,
thus doing the substitution, etc.
   This continues until there is an error.  In this case it could be a file
where the substitute command doesn't find a match for "5.1".  You can then
make a change to insert "5.1" and continue by typing ",," again.  Or the
":wnext" fails, because you are in the last file in the list.
   When a mapping runs into an error halfway, the rest of the mapping is
discarded.  CTRL-C interrupts the mapping (CTRL-Break on MS-Windows).

DELETE A MAPPING

To remove a mapping use the ":unmap" command.  Again, the mode the unmapping
applies to depends on the command used:

:unmap		Normal, Visual and Operator-pending
	:vunmap		Visual
	:nunmap		Normal
	:ounmap		Operator-pending
	:unmap!		Insert and Command-line
	:iunmap		Insert
	:cunmap		Command-line

There is a trick to define a mapping that works in Normal and Operator-pending
mode, but not in Visual mode.  First define it for all three modes, then
delete it for Visual mode: >

:map <C-A> /---><CR>
	:vunmap <C-A>

Notice that the five characters "<C-A>" stand for the single key CTRL-A.

To remove all mappings use the |:mapclear| command.  You can guess the
variations for different modes by now.  Be careful with this command, it can't
be undone.

SPECIAL CHARACTERS

The ":map" command can be followed by another command.  A | character
separates the two commands.  This also means that a | character can't be used
inside a map command.  To include one, use <Bar> (five characters).  Example:
>
	:map <F8> :write <Bar> !checkin %:S<CR>

The same problem applies to the ":unmap" command, with the addition that you
have to watch out for trailing white space.  These two commands are different:
>
	:unmap a | unmap b
	:unmap a| unmap b

The first command tries to unmap "a ", with a trailing space.

When using a space inside a mapping, use <Space> (seven characters): >

:map <Space> W

This makes the spacebar move a blank-separated word forward.

It is not possible to put a comment directly after a mapping, because the "
character is considered to be part of the mapping.  You can use |", this
starts a new, empty command with a comment.  Example: >

:map <Space> W|     " Use spacebar to move forward a word

MAPPINGS AND ABBREVIATIONS

Abbreviations are a lot like Insert mode mappings.  The arguments are handled
in the same way.  The main difference is the way they are triggered.  An
abbreviation is triggered by typing a non-word character after the word.  A
mapping is triggered when typing the last character.
   Another difference is that the characters you type for an abbreviation are
inserted in the text while you type them.  When the abbreviation is triggered
these characters are deleted and replaced by what the abbreviation produces.
When typing the characters for a mapping, nothing is inserted until you type
the last character that triggers it.  If the 'showcmd' option is set, the
typed characters are displayed in the last line of the Vim window.
   An exception is when a mapping is ambiguous.  Suppose you have done two
mappings: >

:imap aa foo
	:imap aaa bar

Now, when you type "aa", Vim doesn't know if it should apply the first or the
second mapping.  It waits for another character to be typed.  If it is an "a",
the second mapping is applied and results in "bar".  If it is a space, for
example, the first mapping is applied, resulting in "foo", and then the space
is inserted.

ADDITIONALLY...

The <script> keyword can be used to make a mapping local to a script.  See
|:map-<script>|.

The <buffer> keyword can be used to make a mapping local to a specific buffer.
See |:map-<buffer>|

The <unique> keyword can be used to make defining a new mapping fail when it
already exists.  Otherwise a new mapping simply overwrites the old one.  See
|:map-<unique>|.

To make a key do nothing, map it to <Nop> (five characters).  This will make
the <F7> key do nothing at all: >

:map <F7> <Nop>| map! <F7> <Nop>

There must be no space after <Nop>.

==============================================================================
*40.2*	Defining command-line commands

The Vim editor enables you to define your own commands.  You execute these
commands just like any other Command-line mode command.
   To define a command, use the ":command" command, as follows: >

:command DeleteFirst 1delete

Now when you execute the command ":DeleteFirst" Vim executes ":1delete", which
deletes the first line.

Note:
	User-defined commands must start with a capital letter.  You cannot
	use ":X", ":Next" and ":Print".  The underscore cannot be used!  You
	can use digits, but this is discouraged.

To list the user-defined commands, execute the following command: >

:command

Just like with the builtin commands, the user defined commands can be
abbreviated.  You need to type just enough to distinguish the command from
another.  Command line completion can be used to get the full name.

NUMBER OF ARGUMENTS

User-defined commands can take a series of arguments.  The number of arguments
must be specified by the -nargs option.  For instance, the example
:DeleteFirst command takes no arguments, so you could have defined it as
follows: >

:command -nargs=0 DeleteFirst 1delete

However, because zero arguments is the default, you do not need to add
"-nargs=0".  The other values of -nargs are as follows:

-nargs=0	No arguments
	-nargs=1	One argument
	-nargs=*	Any number of arguments
	-nargs=?	Zero or one argument
	-nargs=+	One or more arguments

USING THE ARGUMENTS

Inside the command definition, the arguments are represented by the
<args> keyword.  For example: >

:command -nargs=+ Say :echo "<args>"

Now when you type >

:Say Hello World

Vim echoes "Hello World".  However, if you add a double quote, it won't work.
For example: >

:Say he said "hello"

To get special characters turned into a string, properly escaped to use as an
expression, use "<q-args>": >

:command -nargs=+ Say :echo <q-args>

Now the above ":Say" command will result in this to be executed: >

:echo "he said \"hello\""

The <f-args> keyword contains the same information as the <args> keyword,
except in a format suitable for use as function call arguments.  For example:
>
	:command -nargs=* DoIt :call AFunction(<f-args>)
	:DoIt a b c

Executes the following command: >

:call AFunction("a", "b", "c")

LINE RANGE

Some commands take a range as their argument.  To tell Vim that you are
defining such a command, you need to specify a -range option.  The values for
this option are as follows:

-range		Range is allowed; default is the current line.
	-range=%	Range is allowed; default is the whole file.
	-range={count}	Range is allowed; the last number in it is used as a
			single number whose default is {count}.

When a range is specified, the keywords <line1> and <line2> get the values of
the first and last line in the range.  For example, the following command
defines the SaveIt command, which writes out the specified range to the file
"save_file": >

:command -range=% SaveIt :<line1>,<line2>write! save_file

OTHER OPTIONS

Some of the other options and keywords are as follows:

-count={number}		The command can take a count whose default is
				{number}.  The resulting count can be used
				through the <count> keyword.
	-bang			You can use a !.  If present, using <bang> will
				result in a !.
	-register		You can specify a register.  (The default is
				the unnamed register.)
				The register specification is available as
				<reg> (a.k.a. <register>).
	-complete={type}	Type of command-line completion used.  See
				|:command-completion| for the list of possible
				values.
	-bar			The command can be followed by | and another
				command, or " and a comment.
	-buffer			The command is only available for the current
				buffer.

Finally, you have the <lt> keyword.  It stands for the character <.  Use this
to escape the special meaning of the <> items mentioned.

REDEFINING AND DELETING

To redefine the same command use the ! argument: >

:command -nargs=+ Say :echo "<args>"
	:command! -nargs=+ Say :echo <q-args>

To delete a user command use ":delcommand".  It takes a single argument, which
is the name of the command.  Example: >

:delcommand SaveIt

To delete all the user commands: >

:comclear

Careful, this can't be undone!

More details about all this in the reference manual: |user-commands|.

==============================================================================
*40.3*	Autocommands

An autocommand is a command that is executed automatically in response to some
event, such as a file being read or written or a buffer change.  Through the
use of autocommands you can train Vim to edit compressed files, for example.
That is used in the |gzip| plugin.
   Autocommands are very powerful.  Use them with care and they will help you
avoid typing many commands.  Use them carelessly and they will cause a lot of
trouble.

Suppose you want to replace a datestamp on the end of a file every time it is
written.  First you define a function: >

:function DateInsert()
	:  $delete
	:  read !date
	:endfunction

You want this function to be called each time, just before a buffer is written
to a file.  This will make that happen: >

:autocmd BufWritePre *  call DateInsert()

"BufWritePre" is the event for which this autocommand is triggered: Just
before (pre) writing a buffer to a file.  The "*" is a pattern to match with
the file name.  In this case it matches all files.
   With this command enabled, when you do a ":write", Vim checks for any
matching BufWritePre autocommands and executes them, and then it
performs the ":write".
   The general form of the :autocmd command is as follows: >

:autocmd [group] {events} {file-pattern} [++nested] {command}

The [group] name is optional.  It is used in managing and calling the commands
(more on this later).  The {events} parameter is a list of events (comma
separated) that trigger the command.
   {file-pattern} is a filename, usually with wildcards.  For example, using
"*.txt" makes the autocommand be used for all files whose name end in ".txt".
The optional [++nested] flag allows for nesting of autocommands (see below),
and finally, {command} is the command to be executed.

EVENTS

One of the most useful events is BufReadPost.  It is triggered after a new
file is being edited.  It is commonly used to set option values.  For example,
you know that "*.gsm" files are GNU assembly language.  To get the syntax file
right, define this autocommand: >

:autocmd BufReadPost *.gsm  set filetype=asm

If Vim is able to detect the type of file, it will set the 'filetype' option
for you.  This triggers the Filetype event.  Use this to do something when a
certain type of file is edited.  For example, to load a list of abbreviations
for text files: >

:autocmd Filetype text  source ~/.vim/abbrevs.vim

When starting to edit a new file, you could make Vim insert a skeleton: >

:autocmd BufNewFile *.[ch]  0read ~/skeletons/skel.c

See |autocmd-events| for a complete list of events.

PATTERNS

The {file-pattern} argument can actually be a comma-separated list of file
patterns.  For example: "*.c,*.h" matches files ending in ".c" and ".h".
   The usual file wildcards can be used.  Here is a summary of the most often
used ones:

*		Match any character any number of times
	?		Match any character once
	[abc]		Match the character a, b or c
	.		Matches a dot
	a{b,c}		Matches "ab" and "ac"

When the pattern includes a slash (/) Vim will compare directory names.
Without the slash only the last part of a file name is used.  For example,
"*.txt" matches "/home/biep/readme.txt".  The pattern "/home/biep/*" would
also match it.  But "home/foo/*.txt" wouldn't.
   When including a slash, Vim matches the pattern against both the full path
of the file ("/home/biep/readme.txt") and the relative path (e.g.,
"biep/readme.txt").

Note:
	When working on a system that uses a backslash as file separator, such
	as MS-Windows, you still use forward slashes in autocommands.  This
	makes it easier to write the pattern, since a backslash has a special
	meaning.  It also makes the autocommands portable.

DELETING

To delete an autocommand, use the same command as what it was defined with,
but leave out the {command} at the end and use a !.  Example: >

:autocmd! FileWritePre *

This will delete all autocommands for the "FileWritePre" event that use the
"*" pattern.

LISTING

To list all the currently defined autocommands, use this: >

:autocmd

The list can be very long, especially when filetype detection is used.  To
list only part of the commands, specify the group, event and/or pattern.  For
example, to list all BufNewFile autocommands: >

:autocmd BufNewFile

To list all autocommands for the pattern "*.c": >

:autocmd * *.c

Using "*" for the event will list all the events.  To list all autocommands
for the cprograms group: >

:autocmd cprograms

GROUPS

The {group} item, used when defining an autocommand, groups related autocommands
together.  This can be used to delete all the autocommands in a certain group,
for example.
   When defining several autocommands for a certain group, use the ":augroup"
command.  For example, let's define autocommands for C programs: >

:augroup cprograms
	:  autocmd BufReadPost *.c,*.h :set sw=4 sts=4
	:  autocmd BufReadPost *.cpp   :set sw=3 sts=3
	:augroup END

This will do the same as: >

:autocmd cprograms BufReadPost *.c,*.h :set sw=4 sts=4
	:autocmd cprograms BufReadPost *.cpp   :set sw=3 sts=3

To delete all autocommands in the "cprograms" group: >

:autocmd! cprograms

NESTING

Generally, commands executed as the result of an autocommand event will not
trigger any new events.  If you read a file in response to a FileChangedShell
event, it will not trigger the autocommands that would set the syntax, for
example.  To make the events triggered, add the "nested" argument: >

:autocmd FileChangedShell * ++nested  edit

EXECUTING AUTOCOMMANDS

It is possible to trigger an autocommand by pretending an event has occurred.
This is useful to have one autocommand trigger another one.  Example: >

:autocmd BufReadPost *.new  execute "doautocmd BufReadPost " . expand("<afile>:r")

This defines an autocommand that is triggered when a new file has been edited.
The file name must end in ".new".  The ":execute" command uses expression
evaluation to form a new command and execute it.  When editing the file
"tryout.c.new" the executed command will be: >

:doautocmd BufReadPost tryout.c

The expand() function takes the "<afile>" argument, which stands for the file
name the autocommand was executed for, and takes the root of the file name
with ":r".

":doautocmd" executes on the current buffer.  The ":doautoall" command works
like "doautocmd" except it executes on all the buffers.

USING NORMAL MODE COMMANDS

The commands executed by an autocommand are Command-line commands.  If you
want to use a Normal mode command, the ":normal" command can be used.
Example: >

:autocmd BufReadPost *.log normal G

This will make the cursor jump to the last line of *.log files when you start
to edit it.
   Using the ":normal" command is a bit tricky.  First of all, make sure its
argument is a complete command, including all the arguments.  When you use "i"
to go to Insert mode, there must also be a <Esc> to leave Insert mode again.
If you use a "/" to start a search pattern, there must be a <CR> to execute
it.
   The ":normal" command uses all the text after it as commands.  Thus there
can be no | and another command following.  To work around this, put the
":normal" command inside an ":execute" command.  This also makes it possible
to pass unprintable characters in a convenient way.  Example: >

:autocmd BufReadPost *.chg execute "normal ONew entry:\<Esc>" |
		\ 1read !date

This also shows the use of a backslash to break a long command into more
lines.  This can be used in Vim scripts (not at the command line).

When you want the autocommand do something complicated, which involves jumping
around in the file and then returning to the original position, you may want
to restore the view on the file.  See |restore-position| for an example.

IGNORING EVENTS

At times, you will not want to trigger an autocommand.  The 'eventignore'
option contains a list of events that will be totally ignored.  For example,
the following causes events for entering and leaving a window to be ignored: >

:set eventignore=WinEnter,WinLeave

To ignore all events, use the following command: >

:set eventignore=all

To set it back to the normal behavior, make 'eventignore' empty: >

:set eventignore=

==============================================================================

Next chapter: |usr_41.txt|  Write a Vim script

cmd: