Merge pull request #1109 from tsuyoshicho/update/20220612/autocmd

Update autocmd.{txt,jax}

Author: h-east

doc/autocmd.jax

@@ -1,4 +1,4 @@
-*autocmd.txt*   For Vim バージョン 9.0.  Last change: 2022 Apr 17
+*autocmd.txt*   For Vim バージョン 9.0.  Last change: 2022 May 24
 
 
 		  VIMリファレンスマニュアル    by Bram Moolenaar
@@ -46,6 +46,28 @@
   る場合がたまにある)。可能であれば、イベント File* や Buf* には同じ自動コマン
   ドを使うのはよい考えだ。
 
+推奨される使用法:
+- 常にグループを使用することで、自動コマンドの削除が容易になる。
+- コマンド自体を短く維持し、より多くの仕事をする関数を呼ぶようにする。
+- 定義されているスクリプトを、自動コマンドを繰り返さずに数回ソースできるように
+  する。
+
+Vim9 script での例: >
+   autocmd_add({replace: true,
+		group:   'DemoGroup',
+		event:   'BufEnter',
+		pattern: '*.txt',
+		cmd:     'call DemoBufEnter()'
+		})
+
+旧来のスクリプトの例: >
+   call autocmd_add(#{replace: v:true,
+		    \ group: 'DemoGroup',
+   		    \ event: 'BufEnter',
+		    \ pattern: '*.txt',
+		    \ cmd: 'call DemoBufEnter()'
+		    \ })
+
 ==============================================================================
 2. 自動コマンドの定義					*autocmd-define*
 
@@ -79,6 +101,10 @@
 		  /<start
 		}
 
+|autocmd_add()| 関数は、Vim script から自動コマンドやグループのリストを追加す
+るために使用できる。`:autocmd` で `:execute` を使用する必要があるような場合は、
+この関数を使用することが好ましい。
+
 Note: ":autocmd" コマンドの後には、パターンが期待される位置に '|' が現れる場合
 にのみ別のコマンドを続けることができる。これは動作する: >
 	:augroup mine | au! BufRead | augroup END
@@ -144,6 +170,9 @@ Note [group] はあらかじめ定義されていなければならないこと
 ==============================================================================
 3. 自動コマンドの除去					*autocmd-remove*
 
+以下で説明するコマンドに加えて、|autocmd_delete()| 関数を使用し Vim script か
+ら自動コマンドおよびグループのリストを削除できる。
+
 :au[tocmd]! [group] {event} {aupat} [++once] [++nested] {cmd}
 			{event} と {aupat} に関連づけられた全ての自動コマンド
 			を除去し、コマンド {cmd} を加える。
@@ -198,6 +227,8 @@ Note [group] はあらかじめ定義されていなければならないこと
 バッファローカルな自動コマンドを列挙するには、<buffer>または<buffer=N>という形
 のパターンを使う。|autocmd-buflocal|を参照。
 
+|autocmd_get()| 関数で自動コマンドのリストを Vim script から取得できる。
+
 							*:autocmd-verbose*
 'verbose' がゼロでないならば、自動コマンドを列挙するときに、それが最後にどこで
 定義されたかも表示する。例: >

en/autocmd.txt

@@ -1,4 +1,4 @@
-*autocmd.txt*   For Vim version 9.0.  Last change: 2022 Apr 17
+*autocmd.txt*   For Vim version 9.0.  Last change: 2022 May 24
 
 
 		  VIM REFERENCE MANUAL    by Bram Moolenaar
@@ -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 in 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*
 
@@ -82,6 +104,10 @@ triggered.
 		  /<start
 		}
 
+The |autocmd_add()| function can be used to add a list of autocmds and autocmd
+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: >
 	:augroup mine | au! BufRead | augroup END
@@ -146,6 +172,9 @@ prompt.  When one command outputs two messages this can happen anyway.
 ==============================================================================
 3. Removing autocommands				*autocmd-remove*
 
+In addition to the below described commands, the |autocmd_delete()| function can
+be used to remove a list of autocmds and autocmd groups from a Vim script.
+
 :au[tocmd]! [group] {event} {aupat} [++once] [++nested] {cmd}
 			Remove all autocommands associated with {event} and
 			{aupat}, and add the command {cmd}.
@@ -198,6 +227,9 @@ argument behavior differs from that for defining and removing autocommands.
 In order to list buffer-local autocommands, use a pattern in the form <buffer>
 or <buffer=N>.  See |autocmd-buflocal|.
 
+The |autocmd_get()| function can be used from a Vim script to get a list of
+autocmds.
+
 							*:autocmd-verbose*
 When 'verbose' is non-zero, listing an autocommand will also display where it
 was last defined. Example: >