Merge remote-tracking branch 'upstream/master' into aucmd_textputpostaucmd_textputpost

1 files changed, 94 insertions, 58 deletions

diff --git a/runtime/doc/autocmd.txt b/runtime/doc/autocmd.txt
index 8cc4754880..c6f6559e37 100644
--- a/runtime/doc/autocmd.txt
+++ b/runtime/doc/autocmd.txt
@@ -16,7 +16,7 @@ For a basic explanation, see section |40.3| in the user manual.
 You can specify commands to be executed automatically when reading or writing
 a file, when entering or leaving a buffer or window, and when exiting Vim.
 For example, you can create an autocommand to set the 'cindent' option for
-files matching *.c.  You can also use autocommands to implement advanced
+files matching `*.c`.  You can also use autocommands to implement advanced
 features, such as editing compressed files (see |gzip-example|).  The usual
 place to put autocommands is in your vimrc file.
 
@@ -118,7 +118,7 @@ manually.  Mostly the screen will not scroll up, thus there is no hit-enter
 prompt.  When one command outputs two messages this can happen anyway.
 
 ==============================================================================
-3. Removing autocommands				*autocmd-remove*
+3. Removing autocommands			*autocmd!* *autocmd-remove*
 
 :au[tocmd]! [group] {event} {aupat} [++once] [++nested] {cmd}
 			Remove all autocommands associated with {event} and
@@ -197,7 +197,7 @@ For READING FILES there are four kinds of events possible:
 Vim uses only one of these four kinds when reading a file.  The "Pre" and
 "Post" events are both triggered, before and after reading the file.
 
-Note that the autocommands for the *ReadPre events and all the Filter events
+Note that the autocommands for the "*ReadPre" events and all the Filter events
 are not allowed to change the current buffer (you will get an error message if
 this happens).  This is to prevent the file to be read into the wrong buffer.
 
@@ -212,28 +212,27 @@ events.
 Nvim recognizes the following events.  Names are case-insensitive.
 
 							*BufAdd*
-BufAdd				Just after creating a new buffer which is
-				added to the buffer list, or adding a buffer
-				to the buffer list, a buffer in the buffer
-				list was renamed.
-				Not triggered for the initial buffers created
-				during startup.
+BufAdd				After adding a new buffer or existing unlisted
+				buffer to the buffer list (except during
+				startup, see |VimEnter|), or renaming a listed
+				buffer.
 				Before |BufEnter|.
-				NOTE: Current buffer "%" may be different from
-				the buffer being created "<afile>".
+				NOTE: Current buffer "%" is not the target
+				buffer "<afile>", "<abuf>". |<buffer=abuf>|
 							*BufDelete*
 BufDelete			Before deleting a buffer from the buffer list.
 				The BufUnload may be called first (if the
 				buffer was loaded).
 				Also used just before a buffer in the buffer
 				list is renamed.
-				NOTE: Current buffer "%" may be different from
-				the buffer being deleted "<afile>" and "<abuf>".
+				NOTE: Current buffer "%" is not the target
+				buffer "<afile>", "<abuf>". |<buffer=abuf>|
 				Do not change to another buffer.
 							*BufEnter*
-BufEnter			After entering a buffer.  Useful for setting
-				options for a file type.  Also executed when
-				starting to edit a buffer.
+BufEnter			After entering (visiting, switching-to) a new
+				or existing buffer. Useful for setting
+				filetype options.  Compare |BufNew| which
+				does not trigger for existing buffers.
 				After |BufAdd|.
 				After |BufReadPost|.
 							*BufFilePost*
@@ -248,8 +247,8 @@ BufHidden			Before a buffer becomes hidden: when there are
 				the buffer is not unloaded or deleted.
 
 				Not used for ":qa" or ":q" when exiting Vim.
-				NOTE: current buffer "%" may be different from
-				the buffer being unloaded "<afile>".
+				NOTE: Current buffer "%" is not the target
+				buffer "<afile>", "<abuf>". |<buffer=abuf>|
 							*BufLeave*
 BufLeave			Before leaving to another buffer.  Also when
 				leaving or closing the current window and the
@@ -260,12 +259,14 @@ BufLeave			Before leaving to another buffer.  Also when
 BufModifiedSet			After the `'modified'` value of a buffer has
 				been changed.
 							*BufNew*
-BufNew				Just after creating a new buffer.  Also used
-				just after a buffer has been renamed.  When
-				the buffer is added to the buffer list BufAdd
-				will be triggered too.
-				NOTE: Current buffer "%" may be different from
-				the buffer being created "<afile>".
+BufNew				After creating a new buffer (except during
+				startup, see |VimEnter|) or renaming an
+				existing buffer. Unlike |BufEnter|, visiting
+				(switching to) an existing buffer will not
+				trigger this again.
+				NOTE: Current buffer "%" is not the target
+				buffer "<afile>", "<abuf>". |<buffer=abuf>|
+				See also |BufAdd|, |BufNewFile|.
 							*BufNewFile*
 BufNewFile			When starting to edit a file that doesn't
 				exist.  Can be used to read in a skeleton
@@ -292,14 +293,14 @@ 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, when the text in 
+BufUnload			Before unloading a buffer, when the text in
 				the buffer is going to be freed.
 				After BufWritePost.
 				Before BufDelete.
 				Triggers for all loaded buffers when Vim is
 				going to exit.
-				NOTE: Current buffer "%" may be different from
-				the buffer being unloaded "<afile>".
+				NOTE: Current buffer "%" is not the target
+				buffer "<afile>", "<abuf>". |<buffer=abuf>|
 				Do not switch buffers or windows!
 				Not triggered when exiting and v:dying is 2 or
 				more.
@@ -319,8 +320,8 @@ BufWinLeave			Before a buffer is removed from a window.
 				Not when it's still visible in another window.
 				Also triggered when exiting.
 				Before BufUnload, BufHidden.
-				NOTE: Current buffer "%" may be different from
-				the buffer being unloaded "<afile>".
+				NOTE: Current buffer "%" is not the target
+				buffer "<afile>", "<abuf>". |<buffer=abuf>|
 				Not triggered when exiting and v:dying is 2 or
 				more.
 							*BufWipeout*
@@ -330,8 +331,8 @@ BufWipeout			Before completely deleting a buffer.  The
 				buffer list).  Also used just before a buffer
 				is renamed (also when it's not in the buffer
 				list).
-				NOTE: Current buffer "%" may be different from
-				the buffer being deleted "<afile>".
+				NOTE: Current buffer "%" is not the target
+				buffer "<afile>", "<abuf>". |<buffer=abuf>|
 				Do not change to another buffer.
 						*BufWrite* *BufWritePre*
 BufWrite or BufWritePre		Before writing the whole buffer to a file.
@@ -380,6 +381,7 @@ CmdlineChanged			After a change was made to the text inside
 CmdlineEnter			After entering the command-line (including
 				non-interactive use of ":" in a mapping: use
 				|<Cmd>| instead to avoid this).
+				The pattern is matched against |cmdline-char|.
 				<afile> expands to the |cmdline-char|.
 				Sets these |v:event| keys:
 				    cmdlevel
@@ -425,7 +427,7 @@ ColorSchemePre			Before loading a color scheme. |:colorscheme|
 				Useful to setup removing things added by a
 				color scheme, before another one is loaded.
 
-CompleteChanged 					*CompleteChanged*
+CompleteChanged						*CompleteChanged*
 				After each time the Insert mode completion
 				menu changed.  Not fired on popup menu hide,
 				use |CompleteDonePre| or |CompleteDone| for
@@ -504,8 +506,7 @@ CursorMoved			After the cursor was moved in Normal or Visual
 				"x", "rx" or "p".
 				Not always triggered when there is typeahead,
 				while executing commands in a script file, or
-				when an operator is pending. Always triggered
-				when moving to another window.
+				when an operator is pending.
 				For an example see |match-parens|.
 				Note: Cannot be skipped with |:noautocmd|.
 				Careful: This is triggered very often, don't
@@ -589,7 +590,7 @@ FileChangedShell		When Vim notices that the modification time of
 				Triggered for each changed file, after:
 				- executing a shell command
 				- |:checktime|
-				- |FocusGained| 
+				- |FocusGained|
 
 				Not used when 'autoread' is set and the buffer
 				was not changed.  If a FileChangedShell
@@ -597,8 +598,8 @@ FileChangedShell		When Vim notices that the modification time of
 				prompt is not given.
 				|v:fcs_reason| indicates what happened. Set
 				|v:fcs_choice| to control what happens next.
-				NOTE: Current buffer "%" may be different from
-				the buffer that was changed "<afile>".
+				NOTE: Current buffer "%" is not the target
+				buffer "<afile>" and "<abuf>". |<buffer=abuf>|
 							*E246* *E811*
 				Cannot switch, jump to or delete buffers.
 				Non-recursive (event cannot trigger itself).
@@ -703,7 +704,6 @@ InsertCharPre			When a character is typed in Insert mode,
 				inserted literally.
 
 				Cannot change the text. |textlock|
-				Not triggered when 'paste' is set.
 							*InsertEnter*
 InsertEnter			Just before starting Insert mode.  Also for
 				Replace mode and Virtual Replace mode.  The
@@ -775,11 +775,13 @@ OptionSet			After setting an option (except during
 				the option. Similarly |v:option_oldglobal| is
 				only set when |:set| or |:setglobal| was used.
 
-				Note that when setting a |global-local| string
-				option with |:set|, then |v:option_old| is the
-				old global value. However, for all other kinds
-				of options (local string options, global-local
-				number options, ...) it is the old local
+				This does not set |<abuf>|, you could use
+				|bufnr()|.
+
+				Note that when setting a |global-local| option
+				with |:set|, then |v:option_old| is the old
+				global value. However, for all options that
+				are not global-local it is the old local
 				value.
 
 				OptionSet is not triggered on startup and for
@@ -859,6 +861,27 @@ RecordingLeave			When a macro stops recording.
 				Sets these |v:event| keys:
 				    regcontents
 				    regname
+							*SafeState*
+SafeState			When nothing is pending, going to wait for the
+				user to type a character.
+				This will not be triggered when:
+				- an operator is pending
+				- a register was entered with "r
+				- halfway executing a command
+				- executing a mapping
+				- there is typeahead
+				- Insert mode completion is active
+				- Command line completion is active
+				You can use `mode()` to find out what state
+				Vim is in.  That may be:
+				- VIsual mode
+				- Normal mode
+				- Insert mode
+				- Command-line mode
+				Depending on what you want to do, you may also
+				check more with `state()`, e.g. whether the
+				screen was scrolled for messages.
+
 							*SessionLoadPost*
 SessionLoadPost			After loading the session file created using
 				the |:mksession| command.
@@ -964,12 +987,25 @@ TermClose			When a |terminal| job ends.
 				Sets these |v:event| keys:
 				    status
 							*TermResponse*
-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.  May be triggered halfway
-				through another event (file I/O, a shell
-				command, or anything else that takes time).
+TermResponse			When Nvim receives an OSC or DCS response from
+				the terminal.  Sets |v:termresponse|. When used
+				from Lua, the response string is included in
+				the "data" field of the autocommand callback.
+				May be triggered halfway through another event
+				(file I/O, a shell command, or anything else
+				that takes time). Example: >lua
+
+				-- Query the terminal palette for the RGB value of color 1
+				-- (red) using OSC 4
+				vim.api.nvim_create_autocmd('TermResponse', {
+				  once = true,
+				  callback = function(args)
+				    local resp = args.data
+				    local r, g, b = resp:match("\x1b%]4;1;rgb:(%w+)/(%w+)/(%w+)")
+				  end,
+				})
+				io.stdout:write("\x1b]4;1;?\x1b\\")
+<
 							*TextChanged*
 TextChanged			After a change was made to the text in the
 				current buffer in Normal mode.  That is after
@@ -999,7 +1035,7 @@ TextChangedT			After a change was made to the text in the
 							*TextYankPost*
 TextYankPost			Just after a |yank| or |deleting| command, but not
 				if the black hole register |quote_| is used nor
-				for |setreg()|. Pattern must be *.
+				for |setreg()|. Pattern must be "*".
 				Sets these |v:event| keys:
 				    inclusive
 				    operator
@@ -1162,7 +1198,7 @@ Set the 'cindent' option for C files in the /vim/src directory. >
 If you have a link from "/tmp/test.c" to "/home/nobody/vim/src/test.c", and
 you start editing "/tmp/test.c", this autocommand will match.
 
-Note:  To match part of a path, but not from the root directory, use a '*' as
+Note:  To match part of a path, but not from the root directory, use a "*" as
 the first character.  Example: >
 	:autocmd BufRead */doc/*.txt	set tw=78
 This autocommand will for example be executed for "/tmp/doc/xx.txt" and
@@ -1415,8 +1451,8 @@ When there is a matching "*Cmd" autocommand, it is assumed it will do the
 writing.  No further writing is done and the other events are not triggered.
 |Cmd-event|
 
-Note that the *WritePost commands should undo any changes to the buffer that
-were caused by the *WritePre commands; otherwise, writing the file will have
+Note that the "*WritePost" commands should undo any changes to the buffer that
+were caused by the "*WritePre" commands; otherwise, writing the file will have
 the side effect of changing the buffer.
 
 Before executing the autocommands, the buffer from which the lines are to be
@@ -1424,15 +1460,15 @@ written temporarily becomes the current buffer.  Unless the autocommands
 change the current buffer or delete the previously current buffer, the
 previously current buffer is made the current buffer again.
 
-The *WritePre and *AppendPre autocommands must not delete the buffer from
+The "*WritePre" and "*AppendPre" autocommands must not delete the buffer from
 which the lines are to be written.
 
 The '[ and '] marks have a special position:
-- Before the *ReadPre event the '[ mark is set to the line just above where
+- Before the "*ReadPre" event the '[ mark is set to the line just above where
   the new lines will be inserted.
-- Before the *ReadPost event the '[ mark is set to the first line that was
+- Before the "*ReadPost" event the '[ mark is set to the first line that was
   just read, the '] mark to the last line.
-- Before executing the *WriteCmd, *WritePre and *AppendPre autocommands the '[
+- Before executing the "*WriteCmd", "*WritePre" and "*AppendPre" autocommands the '[
   mark is set to the first line that will be written, the '] mark to the last
   line.
 Careful: '[ and '] change when using commands that change the buffer.
@@ -1540,7 +1576,7 @@ To read a skeleton (template) file when opening a new file: >
   :autocmd BufNewFile  *.h	0r ~/vim/skeleton.h
   :autocmd BufNewFile  *.java	0r ~/vim/skeleton.java
 
-To insert the current date and time in a *.html file when writing it: >
+To insert the current date and time in a "*.html" file when writing it: >
 
   :autocmd BufWritePre,FileWritePre *.html   ks|call LastMod()|'s
   :fun LastMod()