doc: autocmd.txt

runtime/doc/autocmd.txt

@@ -397,17 +397,18 @@ BufFilePost			After changing the name of the current buffer
 BufFilePre			Before changing the name of the current buffer
 				with the ":file" or ":saveas" command.
 							*BufHidden*
-BufHidden			Just before a buffer becomes hidden.  That is,
+BufHidden			Before a buffer becomes hidden: when there are
-				when there are no longer windows that show
+				no longer windows that show the buffer, but
-				the buffer, but the buffer is not unloaded or
+				the buffer is not unloaded or deleted.
-				deleted.  Not used for ":qa" or ":q" when
+
-				exiting Vim.
+				Not used for ":qa" or ":q" when exiting Vim.
 				NOTE: current buffer "%" may be different from
 				the buffer being unloaded "<afile>".
 							*BufLeave*
 BufLeave			Before leaving to another buffer.  Also when
 				leaving or closing the current window and the
 				new current window is not for the same buffer.
+
 				Not used for ":qa" or ":q" when exiting Vim.
 							*BufNew*
 BufNew				Just after creating a new buffer.  Also used
@@ -423,16 +424,17 @@ BufNewFile			When starting to edit a file that doesn't
 						*BufRead* *BufReadPost*
 BufRead or BufReadPost		When starting to edit a new buffer, after
 				reading the file into the buffer, before
-				executing the modelines.  See |BufWinEnter|
+				processing modelines.  See |BufWinEnter| to do
-				for when you need to do something after
+				something after processing modelines.
-				processing the modelines.
+				Also triggered:
-				This does NOT work for ":r file".  Not used
+				- when writing an unnamed buffer such that the
-				when the file doesn't exist.  Also used after
+				  buffer gets a name
-				successfully recovering a file.
+				- after successfully recovering a file
-				Also triggered for the filetypedetect group
+				- for the "filetypedetect" group when
-				when executing ":filetype detect" and when
+				  executing ":filetype detect"
-				writing an unnamed buffer in a way that the
+				Not triggered:
-				buffer gets a name.
+				- for ":r file"
+				- if the file doesn't exist
 							*BufReadCmd*
 BufReadCmd			Before starting to edit a new buffer.  Should
 				read the file into the buffer. |Cmd-event|
@@ -441,34 +443,33 @@ BufReadPre			When starting to edit a new buffer, before
 				reading the file into the buffer.  Not used
 				if the file doesn't exist.
 							*BufUnload*
-BufUnload			Before unloading a buffer.  This is when the
+BufUnload			Before unloading a buffer, when the text in 
-				text in the buffer is going to be freed.  This
+				the buffer is going to be freed.
-				may be after a BufWritePost and before a
+				After BufWritePost.
-				BufDelete.  Also used for all buffers that are
+				Before BufDelete.
-				loaded when Vim is going to exit.
+				Triggers for all loaded buffers when Vim is
+				going to exit.
 				NOTE: Current buffer "%" may be different from
 				the buffer being unloaded "<afile>".
-				Do not change to another buffer or window!
+				Do not switch buffers or windows!
 				Not triggered when exiting and v:dying is 2 or
 				more.
 							*BufWinEnter*
 BufWinEnter			After a buffer is displayed in a window.  This
-				can be when the buffer is loaded (after
+				may be when the buffer is loaded (after
-				processing the modelines) or when a hidden
+				processing modelines) or when a hidden buffer
-				buffer is displayed in a window (and is no
+				is displayed (and is no longer hidden).
-				longer hidden).
+
-				Does not happen for |:split| without
+				Not triggered for |:split| without arguments,
-				arguments, since you keep editing the same
+				since the buffer does not change, or :split
-				buffer, or ":split" with a file that's already
+				with a file already open in a window.
-				open in a window, because it re-uses an
+				Triggered for ":split" with the name of the
-				existing buffer.  But it does happen for a
+				current buffer, since it reloads that buffer.
-				":split" with the name of the current buffer,
-				since it reloads that buffer.
 							*BufWinLeave*
 BufWinLeave			Before a buffer is removed from a window.
 				Not when it's still visible in another window.
-				Also triggered when exiting.  It's triggered
+				Also triggered when exiting.
-				before BufUnload or BufHidden.
+				Before BufUnload, BufHidden.
 				NOTE: Current buffer "%" may be different from
 				the buffer being unloaded "<afile>".
 				Not triggered when exiting and v:dying is 2 or
@@ -516,7 +517,7 @@ CmdUndefined			When a user command is used but it isn't
 				defined.  Useful for defining a command only
 				when it's used.  The pattern is matched
 				against the command name.  Both <amatch> and
-				<afile> are set to the name of the command.
+				<afile> expand to the command name.
 				NOTE: Autocompletion won't work until the
 				command is defined.  An alternative is to
 				always define the user command and have it
@@ -525,12 +526,12 @@ CmdUndefined			When a user command is used but it isn't
 CmdlineChanged			After a change was made to the text inside
 				command line.  Be careful not to mess up the
 				command line, it may cause Vim to lock up.
-				<afile> is set to the |cmdline-char|.
+				<afile> expands to the |cmdline-char|.
 							*CmdlineEnter*
 CmdlineEnter			After entering the command-line (including
 				non-interactive use of ":" in a mapping: use
 				|<Cmd>| instead to avoid this).
-				<afile> is set to the |cmdline-char|.
+				<afile> expands to the |cmdline-char|.
 				Sets these |v:event| keys:
 				    cmdlevel
 				    cmdtype
@@ -538,26 +539,26 @@ CmdlineEnter			After entering the command-line (including
 CmdlineLeave			Before leaving the command-line (including
 				non-interactive use of ":" in a mapping: use
 				|<Cmd>| instead to avoid this).
-				<afile> is set to the |cmdline-char|.
+				<afile> expands to the |cmdline-char|.
 				Sets these |v:event| keys:
 				    abort (mutable)
 				    cmdlevel
 				    cmdtype
 				Note: `abort` can only be changed from false
-				to true. An autocmd cannot execute an already
+				to true: cannot execute an already aborted
-				aborted cmdline by changing it to false.
+				cmdline by changing it to false.
 							*CmdwinEnter*
 CmdwinEnter			After entering the command-line window.
 				Useful for setting options specifically for
 				this special type of window.
-				<afile> is set to a single character,
+				<afile> expands to a single character,
 				indicating the type of command-line.
 				|cmdwin-char|
 							*CmdwinLeave*
 CmdwinLeave			Before leaving the command-line window.
 				Useful to clean up any global setting done
 				with CmdwinEnter.
-				<afile> is set to a single character,
+				<afile> expands to a single character,
 				indicating the type of command-line.
 				|cmdwin-char|
 							*ColorScheme*
@@ -599,8 +600,7 @@ CompleteDone			After Insert mode completion is done.  Either
 				completion. |ins-completion|
 				|complete_info()| can be used, the info is
 				cleared after triggering CompleteDone.
-				The |v:completed_item| variable contains the
+				|v:completed_item| gives the completed item.
-				completed item.
 
 							*CursorHold*
 CursorHold			When the user doesn't press a key for the time
@@ -630,9 +630,9 @@ CursorHold			When the user doesn't press a key for the time
 					:let &ro = &ro
 
 							*CursorHoldI*
-CursorHoldI			Just like CursorHold, but in Insert mode.
+CursorHoldI			Like CursorHold, but in Insert mode. Not
-				Not triggered when waiting for another key,
+				triggered when waiting for another key, e.g.
-				e.g. after CTRL-V, and not when in CTRL-X mode
+				after CTRL-V, and not in CTRL-X mode
 				|insert_expand|.
 
 							*CursorMoved*
@@ -643,7 +643,7 @@ CursorMoved			After the cursor was moved in Normal or Visual
 				Not triggered when there is typeahead or when
 				an operator is pending.
 				For an example see |match-parens|.
-				Note: Cannot be skipped with `:noautocmd`.
+				Note: Cannot be skipped with |:noautocmd|.
 				Careful: This is triggered very often, don't
 				do anything that the user does not expect or
 				that is slow.
@@ -673,19 +673,18 @@ FileAppendPre			Before appending to a file.  Use the '[ and ']
 				marks for the range of lines.
 							*FileChangedRO*
 FileChangedRO			Before making the first change to a read-only
-				file.  Can be used to check-out the file from
+				file.  Can be used to checkout the file from
 				a source control system.  Not triggered when
 				the change was caused by an autocommand.
-				This event is triggered when making the first
+				Triggered when making the first change in
-				change in a buffer or the first change after
+				a buffer or the first change after 'readonly'
-				'readonly' was set, just before the change is
+				was set, just before the change is applied to
-				applied to the text.
+				the text.
 				WARNING: If the autocommand moves the cursor
 				the effect of the change is undefined.
 							*E788*
-				It is not allowed to change to another buffer
+				Cannot switch buffers.  You can reload the
-				here.  You can reload the buffer but not edit
+				buffer but not edit another one.
-				another one.
 							*E881*
 				If the number of lines changes saving for undo
 				may fail and the change will be aborted.
@@ -704,28 +703,21 @@ FileChangedShell		When Vim notices that the modification time of
 				Also when the file attributes of the file
 				change or when the size of the file changes.
 				|timestamp|
-				Mostly triggered after executing a shell
+				Triggered for each changed file, after:
-				command, but also with a |:checktime| command
+				- executing a shell command
-				or when gvim regains input focus.
+				- |:checktime|
-				This autocommand is triggered for each changed
+				- |FocusGained| 
-				file.  It is not used when 'autoread' is set
+				Not used when 'autoread' is set and the buffer
-				and the buffer was not changed.  If a
+				was not changed.  If a FileChangedShell
-				FileChangedShell autocommand is present the
+				autocommand exists the warning message and
-				warning message and prompt is not given.
+				prompt is not given.
-				The |v:fcs_reason| variable is set to indicate
+				|v:fcs_reason| indicates what happened. Set
-				what happened and |v:fcs_choice| can be used
+				|v:fcs_choice| to control what happens next.
-				to tell Vim what to do next.
+				NOTE: Current buffer "%" may be different from
-				NOTE: When this autocommand is executed, the
+				the buffer that was changed "<afile>".
-				current buffer "%" may be different from the
+							*E246* *E811*
-				buffer that was changed, which is in "<afile>".
+				Cannot switch, jump to or delete buffers.
-				NOTE: The commands must not change the current
+				Non-recursive (event cannot trigger itself).
-				buffer, jump to another buffer or delete a
-				buffer.  *E246* *E811*
-				NOTE: This event never nests, to avoid an
-				endless loop.  This means that while executing
-				commands for the FileChangedShell event no
-				other FileChangedShell event will be
-				triggered.
 							*FileChangedShellPost*
 FileChangedShellPost		After handling a file that was changed outside
 				of Vim.  Can be used to update the statusline.
@@ -742,10 +734,10 @@ FileReadPre			Before reading a file with a ":read" command.
 							*FileType*
 FileType			When the 'filetype' option has been set.  The
 				pattern is matched against the filetype.
-				<afile> can be used for the name of the file
+				<afile> is the name of the file where this
-				where this option was set, and <amatch> for
+				option was set.  <amatch> is the new value of
-				the new value of 'filetype'.  Navigating to
+				'filetype'.
-				another window or buffer is not allowed.
+				Cannot switch windows or buffers.
 				See |filetypes|.
 							*FileWriteCmd*
 FileWriteCmd			Before writing to a file, when not writing the
@@ -1018,27 +1010,26 @@ SwapExists			Detected an existing swap file when starting
 				When set to an empty string the user will be
 				asked, as if there was no SwapExists autocmd.
 							*E812*
-				It is not allowed to change to another buffer,
+				Cannot change to another buffer, change
-				change a buffer name or change directory
+				the buffer name or change directory.
-				here.
 							*Syntax*
 Syntax				When the 'syntax' option has been set.  The
 				pattern is matched against the syntax name.
-				<afile> can be used for the name of the file
+				<afile> expands to the name of the file where
-				where this option was set, and <amatch> for
+				this option was set. <amatch> expands to the
-				the new value of 'syntax'.
+				new value of 'syntax'.
 				See |:syn-on|.
 							*TabEnter*
 TabEnter			Just after entering a tab page. |tab-page|
-				After triggering the WinEnter and before
+				After WinEnter.
-				triggering the BufEnter event.
+				Before BufEnter.
 							*TabLeave*
 TabLeave			Just before leaving a tab page. |tab-page|
-				A WinLeave event will have been triggered
+				After WinLeave.
-				first.
 							*TabNew*
 TabNew				When creating a new tab page. |tab-page|
-				After WinEnter and before TabEnter.
+				After WinEnter.
+				Before TabEnter.
 							*TabNewEntered*
 TabNewEntered			After entering a new tab page. |tab-page|
 				After BufEnter.
@@ -1060,10 +1051,9 @@ TermClose			When a |terminal| job ends.
 TermResponse			After the response to t_RV is received from
 				the terminal.  The value of |v:termresponse|
 				can be used to do things depending on the
-				terminal version.  Note that this event may be
+				terminal version.  May be triggered halfway
-				triggered halfway through another event
+				through another event (file I/O, a shell
-				(especially if file I/O, a shell command, or
+				command, or anything else that takes time).
-				anything else that takes time is involved).
 							*TextChanged*
 TextChanged			After a change was made to the text in the
 				current buffer in Normal mode.  That is after
@@ -1136,6 +1126,7 @@ VimSuspend			Before Nvim enters |suspend| state.
 							*WinClosed*
 WinClosed			After closing a window. <afile> expands to the
 				|window-ID|.
+				After WinLeave.
 				Non-recursive (event cannot trigger itself).
 				See also |ExitPre|, |QuitPre|.
 							*WinEnter*
@@ -1155,10 +1146,11 @@ WinLeave			Before leaving a window.  If the window to be
 				executes the BufLeave autocommands before the
 				WinLeave autocommands (but not for ":new").
 				Not used for ":qa" or ":q" when exiting Vim.
+				After WinClosed.
 							*WinNew*
 WinNew				When a new window was created.  Not done for
 				the first window, when Vim has just started.
-				Before a WinEnter event.
+				Before WinEnter.
 
 ==============================================================================
 6. Patterns					*autocmd-pattern* *{pat}*