patch 8.2.5011: Replacing an autocommand requires several lines
Problem: Replacing an autocommand requires several lines.
Solution: Add the "replace" flag to autocmd_add(). (Yegappan Lakshmanan,
closes #10473)
diff --git a/runtime/doc/autocmd.txt b/runtime/doc/autocmd.txt
index fb4532f..0ef7c4c 100644
--- a/runtime/doc/autocmd.txt
+++ b/runtime/doc/autocmd.txt
@@ -47,6 +47,28 @@
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 @@
}
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: >