patch 8.2.5011: Replacing an autocommand requires several linesv8.2.5011

Problem:    Replacing an autocommand requires several lines.
Solution:   Add the "replace" flag to autocmd_add(). (Yegappan Lakshmanan,
            closes #10473)

2 files changed, 38 insertions, 9 deletions

diff --git a/runtime/doc/autocmd.txt b/runtime/doc/autocmd.txt
index fb4532fc4e..0ef7c4c67b 100644
--- a/runtime/doc/autocmd.txt
+++ b/runtime/doc/autocmd.txt
@@ -47,6 +47,28 @@ effects.  Be careful not to destroy your text.
   It's a good idea to use the same autocommands for the File* and Buf* events
   when possible.
 
+Recommended use:
+- Always use a group, so that it's easy to delete the autocommand.
+- Keep the command itself short, call a function to do more work.
+- Make it so that the script it is defined it can be sourced several times
+  without the autocommand being repeated.
+
+Example in Vim9 script: >
+   autocmd_add({replace: true,
+		group:   'DemoGroup',
+		event:   'BufEnter',
+		pattern: '*.txt',
+		cmd:     'call DemoBufEnter()'
+		})
+
+In legacy script: >
+   call autocmd_add(#{replace: v:true,
+		    \ group: 'DemoGroup',
+   		    \ event: 'BufEnter',
+		    \ pattern: '*.txt',
+		    \ cmd: 'call DemoBufEnter()'
+		    \ })
+
 ==============================================================================
 2. Defining autocommands				*autocmd-define*
 
@@ -83,7 +105,8 @@ triggered.
 		}
 
 The |autocmd_add()| function can be used to add a list of autocmds and autocmd
-groups from a Vim script.
+groups from a Vim script.  It is preferred if you have anything that would
+require using `:execute` with `:autocmd`.
 
 Note: The ":autocmd" command can only be followed by another command when the
 '|' appears where the pattern is expected.  This works: >
diff --git a/runtime/doc/builtin.txt b/runtime/doc/builtin.txt
index 29cc506273..5b20ea3322 100644
--- a/runtime/doc/builtin.txt
+++ b/runtime/doc/builtin.txt
@@ -940,13 +940,19 @@ autocmd_add({acmds})					*autocmd_add()*
 				If this group doesn't exist then it is
 				created.  If not specified or empty, then the
 				default group is used.
-		    nested	set to v:true to add a nested autocmd.
-				Refer to |autocmd-nested|.
-		    once	set to v:true to add a autocmd which executes
-				only once. Refer to |autocmd-once|.
+		    nested	boolean flag, set to v:true to add a nested
+				autocmd.  Refer to |autocmd-nested|.
+		    once	boolean flag, set to v:true to add a autocmd
+				which executes only once. Refer to
+				|autocmd-once|.
 		    pattern	autocmd pattern string. Refer to
 				|autocmd-patterns|.  If "bufnr" item is
 				present, then this item is ignored.
+		    replace	boolean flag, set to v:true to remove all the
+				commands associated with the specified autocmd
+				event and group and add the {cmd}.  This is
+				useful to avoid adding the same command
+				multiple times for a autocmd event in a group.
 
 		Returns v:true on success and v:false on failure.
 		Examples: >
@@ -1037,10 +1043,10 @@ autocmd_get([{opts}])					*autocmd_get()*
 		    cmd		Command executed for this autocmd.
 		    event	Autocmd event name.
 		    group	Autocmd group name.
-		    nested	Set to v:true for a nested autocmd. See
-				|autocmd-nested|.
-		    once	Set to v:true, if the autocmd will be executed
-				only once. See |autocmd-once|.
+		    nested	Boolean flag, set to v:true for a nested
+				autocmd. See |autocmd-nested|.
+		    once	Boolean flag, set to v:true, if the autocmd
+				will be executed only once. See |autocmd-once|.
 		    pattern	Autocmd pattern.  For a buffer-local
 				autocmd, this will be of the form "<buffer=n>".
 		If there are multiple commands for an autocmd event in a