From: Enrico Maria De Angelis <enricomaria.dean6elis@gmail.com>
Date: Thu, 28 May 2026 18:31:33 +0000 (+0000)
Subject: runtime(doc): Clarify the use of <Plug> mappings
X-Git-Tag: v9.2.0546~1
X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=9d5a20e4409ad47557d6374dd57c88e601b7bf7d;p=thirdparty%2Fvim.git

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

related: #6705
closes:  #20351

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

diff --git a/runtime/doc/usr_51.txt b/runtime/doc/usr_51.txt
index b1b630454d..1ed1b6b376 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 "\a".
 
@@ -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 "\a", this sequence is invoked: >
 
-	\a  ->  <Plug>TypecorrAdd;  ->  <SID>Add  ->  :call <SID>Add(...)
+	\a  ->  <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: