Commit: runtime(doc): Clarify the use of <Plug> mappings

[Christian Brabandt]

runtime(doc): Clarify the use of <Plug> mappings

Commit: https://github.com/vim/vim/commit/9d5a20e4409ad47557d6374dd57c88e601b7bf7d
Author: Enrico Maria De Angelis <enricomari...@gmail.com>
Date: Thu May 28 18:31:33 2026 +0000

runtime(doc): Clarify the use of <Plug> mappings

related: https://github.com/vim/vim/issues/6705
closes: https://github.com/vim/vim/issues/20351

Signed-off-by: Enrico Maria De Angelis <enricomari...@gmail.com>
Signed-off-by: Christian Brabandt <c...@256bit.org>

diff --git a/runtime/doc/usr_51.txt b/runtime/doc/usr_51.txt
index b1b630454..1ed1b6b37 100644
--- a/runtime/doc/usr_51.txt
+++ b/runtime/doc/usr_51.txt
@@ -1,4 +1,4 @@
-*usr_51.txt* For Vim version 9.2. Last change: 2026 May 26
+*usr_51.txt* For Vim version 9.2. Last change: 2026 May 28


VIM USER MANUAL by Bram Moolenaar
@@ -134,9 +134,9 @@ for this mapping, but the user might already use it for something else. To
allow the user to define which keys a mapping in a plugin uses, the <Leader>
item can be used: >

- 20 map <unique> <Leader>a <Plug>TypecorrAdd;
+ 20 map <unique> <Leader>a <Plug>(TypecorrAdd)

-The "<Plug>TypecorrAdd;" thing will do the work, more about that further on.
+The "<Plug>(TypecorrAdd)" thing will do the work, more about that further on.

The user can set the "g:mapleader" variable to the key sequence that they want
plugin mappings to start with. Thus if the user has done: >
@@ -152,15 +152,15 @@ already happened to exist. |:map-<unique>|
But what if the user wants to define their own key sequence? We can allow
that with this mechanism: >

- 19 if !hasmapto('<Plug>TypecorrAdd;')
- 20 map <unique> <Leader>a <Plug>TypecorrAdd;
+ 19 if !hasmapto('<Plug>(TypecorrAdd)')
+ 20 map <unique> <Leader>a <Plug>(TypecorrAdd)
21 endif

-This checks if a mapping to "<Plug>TypecorrAdd;" already exists, and only
+This checks if a mapping to "<Plug>(TypecorrAdd)" already exists, and only
defines the mapping from "<Leader>a" if it doesn't. The user then has a
chance of putting this in their vimrc file: >

- map ,c <Plug>TypecorrAdd;
+ map ,c <Plug>(TypecorrAdd)

Then the mapped key sequence will be ",c" instead of "_a" or " ".

@@ -191,13 +191,13 @@ which is again another function.
<SID> can be used with mappings. It generates a script ID, which identifies
the current script. In our typing correction plugin we use it like this: >

- 22 noremap <unique> <script> <Plug>TypecorrAdd; <SID>Add
+ 22 noremap <unique> <script> <Plug>(TypecorrAdd) <SID>Add
...
26 noremap <SID>Add :call <SID>Add(expand("<cword>"), true)<CR>

Thus when a user types " ", this sequence is invoked: >

- -> <Plug>TypecorrAdd; -> <SID>Add -> :call <SID>Add(...)
+ -> <Plug>(TypecorrAdd) -> <SID>Add -> :call <SID>Add(...)

If another script also maps <SID>Add, it will get another script ID and
thus define another mapping.
@@ -240,9 +240,16 @@ difference between using <SID> and <Plug>:
To make it very unlikely that other plugins use the same sequence of
characters, use this structure: <Plug> scriptname mapname
In our example the scriptname is "Typecorr" and the mapname is "Add".
- We add a semicolon as the terminator. This results in
- "<Plug>TypecorrAdd;". Only the first character of scriptname and
- mapname is uppercase, so that we can see where mapname starts.
+ We wrap the name in parentheses. This results in
+ "<Plug>(TypecorrAdd)". The convention of using PascalCase helps
+ telling scriptname apart from mapname.
+
+ Note: the text after "<Plug>" is chosen by the plugin author and is
+ entirely arbitrary. Wrapping the name in parentheses, using
+ PascalCase, or adding a ";" terminator like "<Plug>TypecorrAdd;" are
+ only conventions to keep the name readable and unlikely to clash with
+ other plugins. None of them are required: all that matters is that
+ the sequence starts with "<Plug>" and is unique.

<SID> is the script ID, a unique identifier for a script.
Internally Vim translates <SID> to "<SNR>123_", where "123" can be any
@@ -324,10 +331,10 @@ Here is the resulting complete example: >
16 \ synchronization
17 var count = 4
18
- 19 if !hasmapto('<Plug>TypecorrAdd;')
- 20 map <unique> <Leader>a <Plug>TypecorrAdd;
+ 19 if !hasmapto('<Plug>(TypecorrAdd)')
+ 20 map <unique> <Leader>a <Plug>(TypecorrAdd)
21 endif
- 22 noremap <unique> <script> <Plug>TypecorrAdd; <SID>Add
+ 22 noremap <unique> <script> <Plug>(TypecorrAdd) <SID>Add
23
24 noremenu <script> Plugin.Add\ Correction <SID>Add
25
@@ -368,7 +375,7 @@ Here is a simple example for a plugin help file, called "typecorrect.txt": >
6 There are currently only a few corrections. Add your own if you like.
7
8 Mappings:
- 9 <Leader>a or <Plug>TypecorrAdd;
+ 9 <Leader>a or <Plug>(TypecorrAdd)
10 Add a correction for the word under the cursor.
11
12 Commands: