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 b1b630454d33963835c4969cd54e93372de3fdee..1ed1b6b3768c84e3bee87474745108629ce31883 100644 (file)
--- 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: