Merge remote-tracking branch 'upstream/master' into aucmd_textputpostaucmd_textputpost

1 files changed, 58 insertions, 50 deletions

diff --git a/runtime/doc/map.txt b/runtime/doc/map.txt
index cb8b162eb6..6f61259af0 100644
--- a/runtime/doc/map.txt
+++ b/runtime/doc/map.txt
@@ -290,7 +290,7 @@ Therefore the following is blocked for <expr> mappings:
 - Moving the cursor is allowed, but it is restored afterwards.
 - If the cmdline is changed, the old text and cursor position are restored.
 If you want the mapping to do any of these let the returned characters do
-that. (Or use a |<Cmd>| mapping instead.)
+that, or use a |<Cmd>| mapping instead.
 
 You can use getchar(), it consumes typeahead if there is any. E.g., if you
 have these mappings: >
@@ -324,20 +324,22 @@ be seen as a special key.
 
 						*<Cmd>* *:map-cmd*
 The <Cmd> pseudokey begins a "command mapping", which executes the command
-directly (without changing modes).  Where you might use ":...<CR>" in the
+directly without changing modes.  Where you might use ":...<CR>" in the
 {rhs} of a mapping, you can instead use "<Cmd>...<CR>".
 Example: >
-	noremap x <Cmd>echo mode(1)<cr>
+	noremap x <Cmd>echo mode(1)<CR>
 <
-This is more flexible than `:<C-U>` in visual and operator-pending mode, or
-`<C-O>:` in insert-mode, because the commands are executed directly in the
-current mode (instead of always going to normal-mode).  Visual-mode is
+This is more flexible than `:<C-U>` in Visual and Operator-pending mode, or
+`<C-O>:` in Insert mode, because the commands are executed directly in the
+current mode, instead of always going to Normal mode.  Visual mode is
 preserved, so tricks with |gv| are not needed.  Commands can be invoked
-directly in cmdline-mode (which would otherwise require timer hacks).
+directly in Command-line mode (which would otherwise require timer hacks).
+Example of using <Cmd> halfway Insert mode: >
+	nnoremap <F3> aText <Cmd>echo mode(1)<CR> Added<Esc>
 
 Unlike <expr> mappings, there are no special restrictions on the <Cmd>
 command: it is executed as if an (unrestricted) |autocommand| was invoked
-or an async event event was processed.
+or an async event was processed.
 
 Note:
 - Because <Cmd> avoids mode-changes (unlike ":") it does not trigger
@@ -347,10 +349,10 @@ Note:
 - The command is not echo'ed, no need for <silent>.
 - The {rhs} is not subject to abbreviations nor to other mappings, even if the
   mapping is recursive.
-- In Visual mode  you can use `line('v')` and `col('v')` to get one end of the
+- In Visual mode you can use `line('v')` and `col('v')` to get one end of the
   Visual area, the cursor is at the other end.
 
-							*E5520*
+							*E1255* *E1136*
 <Cmd> commands must terminate, that is, they must be followed by <CR> in the
 {rhs} of the mapping definition.  |Command-line| mode is never entered.
 
@@ -540,28 +542,10 @@ See |:verbose-cmd| for more information.
 
 1.5 MAPPING SPECIAL KEYS				*:map-special-keys*
 
-There are two ways to map a special key:
-1. The Vi-compatible method: Map the key code.  Often this is a sequence that
-   starts with <Esc>.  To enter a mapping like this you type ":map " and then
-   you have to type CTRL-V before hitting the function key.  Note that when
-   the key code for the key is in the |terminfo| entry, it will automatically
-   be translated into the internal code and become the second way of mapping.
-2. The second method is to use the internal code for the function key.  To
-   enter such a mapping type CTRL-K and then hit the function key, or use
-   the form "#1", "#2", .. "#9", "#0", "<Up>", "<S-Down>", "<S-F7>", etc.
-   (see table of keys |key-notation|, all keys from <Up> can be used).  The
-   first ten function keys can be defined in two ways: Just the number, like
-   "#2", and with "<F>", like "<F2>".  Both stand for function key 2.  "#0"
-   refers to function key 10.
-
-DETAIL: Vim first checks if a sequence from the keyboard is mapped.  If it
-isn't the terminal key codes are tried.  If a terminal code is found it is
-replaced with the internal code.  Then the check for a mapping is done again
-(so you can map an internal code to something else).  What is written into the
-script file depends on what is recognized. If the terminal key code was
-recognized as a mapping the key code itself is written to the script file.  If
-it was recognized as a terminal code the internal code is written to the
-script file.
+To map a function key, use the internal code for it.  To enter such a mapping
+type CTRL-K and then hit the function key, or use the form "<F2>", "<F10>",
+"<Up>", "<S-Down>", "<S-F7>", etc. (see table of keys |key-notation|, all keys
+from <Up> can be used).
 
 
 1.6 SPECIAL CHARACTERS					*:map-special-chars*
@@ -654,6 +638,7 @@ not to be matched with any key sequence.  This is useful in plugins
 							*<MouseMove>*
 The special key name "<MouseMove>" can be used to handle mouse movement.  It
 needs to be enabled with 'mousemoveevent'.
+The |getmousepos()| function can be used to obtain the mouse position.
 
 							*<Char>* *<Char->*
 To map a character by its decimal, octal or hexadecimal number the <Char>
@@ -695,8 +680,7 @@ this (see |<>|).  Example: >
    :map  _ls  :!ls -l %:S<CR>:echo "the end"<CR>
 
 To avoid mapping of the characters you type in insert or Command-line mode,
-type a CTRL-V first.  The mapping in Insert mode is disabled if the 'paste'
-option is on.
+type a CTRL-V first.
 							*map-error*
 Note that when an error is encountered (that causes an error message or might
 cause a beep) the rest of the mapping is not executed.  This is Vi-compatible.
@@ -764,7 +748,7 @@ option).  After that it assumes that the 'q' is to be interpreted as such.  If
 you type slowly, or your system is slow, reset the 'timeout' option.  Then you
 might want to set the 'ttimeout' option.
 
-			      				*map-precedence*
+							*map-precedence*
 Buffer-local mappings (defined using |:map-<buffer>|) take precedence over
 global mappings.  When a buffer-local mapping is the same as a global mapping,
 Vim will use the buffer-local mapping.  In addition, Vim will use a complete
@@ -838,6 +822,11 @@ in the original Vi, you would get back the text before the first undo).
 
 1.10 MAPPING ALT-KEYS					*:map-alt-keys*
 
+For a readable mapping command the <A-k> form can be used.  Note that <A-k>
+and <A-K> are different, the latter will use an upper case letter.  Actually,
+<A-K> and <A-S-K> are the same.  Instead of "A" you can use "M".  If you have
+an actual Meta modifier key, please see |:map-meta-keys|.
+
 In the GUI Nvim handles the |ALT| key itself, thus mapping keys with ALT
 should always work.  But in a terminal Nvim gets a sequence of bytes and has
 to figure out whether ALT was pressed.  Terminals may use ESC to indicate that
@@ -847,7 +836,21 @@ milliseconds, the ESC is interpreted as:
 otherwise it is interpreted as two key presses:
         <ESC> {key}
 
-1.11 MAPPING AN OPERATOR				*:map-operator*
+1.11 MAPPING META-KEYS					*:map-meta-keys*
+
+Mapping keys with the Meta modifier works very similar to using the Alt key.
+What key on your keyboard produces the Meta modifier depends on your keyboard
+and configuration.
+
+Note that mapping <M-a> actually is for using the Alt key.  That can be
+confusing!  It cannot be changed, it would not be backwards compatible.
+
+For the Meta modifier the "T" character is used.  For example, to map Meta-b
+in Insert mode: >
+	:imap <T-b> terrible
+
+
+1.12 MAPPING AN OPERATOR				*:map-operator*
 
 An operator is used before a {motion} command.  To define your own operator
 you must create a mapping that first sets the 'operatorfunc' option and then
@@ -952,7 +955,7 @@ operator to add quotes around text in the current line: >
 				\ ->setline(".")}'<CR>g@
 
 ==============================================================================
-2. Abbreviations			*abbreviations* *Abbreviations*
+2. Abbreviations		*abbreviation* *abbreviations* *Abbreviations*
 
 Abbreviations are used in Insert mode, Replace mode and Command-line mode.
 If you enter a word that is an abbreviation, it is replaced with the word it
@@ -984,7 +987,7 @@ non-id	  The "non-id" type ends in a non-keyword character, the other
 Examples of strings that cannot be abbreviations: "a.b", "#def", "a b", "_$r"
 
 An abbreviation is only recognized when you type a non-keyword character.
-This can also be the <Esc> that ends insert mode or the <CR> that ends a
+This can also be the <Esc> that ends Insert mode or the <CR> that ends a
 command.  The non-keyword character which ends the abbreviation is inserted
 after the expanded abbreviation.  An exception to this is the character <C-]>,
 which is used to expand an abbreviation without inserting any extra
@@ -1048,10 +1051,7 @@ typed after an abbreviation: >
 There are no default abbreviations.
 
 Abbreviations are never recursive.  You can use ":ab f f-o-o" without any
-problem.  But abbreviations can be mapped.  {some versions of Vi support
-recursive abbreviations, for no apparent reason}
-
-Abbreviations are disabled if the 'paste' option is on.
+problem.  But abbreviations can be mapped.
 
 				*:abbreviate-local* *:abbreviate-<buffer>*
 Just like mappings, abbreviations can be local to a buffer.  This is mostly
@@ -1186,12 +1186,14 @@ functions used in one script use the same name as in other scripts.  To avoid
 this, they can be made local to the script.
 
 						*<SID>* *<SNR>* *E81*
-The string "<SID>" can be used in a mapping or menu.
+The string "<SID>" can be used in a mapping or menu.  This is useful if you
+have a script-local function that you want to call from a mapping in the same
+script.
    When executing the map command, Vim will replace "<SID>" with the special
 key code <SNR>, followed by a number that's unique for the script, and an
 underscore.  Example: >
 	:map <SID>Add
-could define a mapping "<SNR>23_Add".
+would define a mapping "<SNR>23_Add".
 
 When defining a function in a script, "s:" can be prepended to the name to
 make it local to the script.  But when a mapping is executed from outside of
@@ -1322,6 +1324,11 @@ can have arguments, or have a range specified.  Arguments are subject to
 completion as filenames, buffers, etc.  Exactly how this works depends upon the
 command's attributes, which are specified when the command is defined.
 
+When defining a user command in a script, it will be able to call functions
+local to the script and use mappings local to the script.  When the user
+invokes the user command, it will run in the context of the script it was
+defined in.  This matters if |<SID>| is used in a command.
+
 There are a number of attributes, split into four categories: argument
 handling, completion behavior, range handling, and special cases.  The
 attributes are described below, by category.
@@ -1383,7 +1390,7 @@ completion can be enabled:
 	-complete=highlight	highlight groups
 	-complete=history	:history suboptions
 	-complete=locale	locale names (as output of locale -a)
-	-complete=lua		Lua expression
+	-complete=lua		Lua expression |:lua|
 	-complete=mapclear	buffer argument
 	-complete=mapping	mapping name
 	-complete=menu		menus
@@ -1484,7 +1491,7 @@ which by default correspond to the current line, last line and the whole
 buffer, relate to arguments, (loaded) buffers, windows or tab pages.
 
 Possible values are (second column is the short name used in listing):
-    -addr=lines		  	Range of lines (this is the default for -range)
+    -addr=lines			Range of lines (this is the default for -range)
     -addr=arguments	  arg	Range for arguments
     -addr=buffers	  buf	Range for buffers (also not loaded buffers)
     -addr=loaded_buffers  load	Range for loaded buffers
@@ -1538,6 +1545,7 @@ supports incremental command preview:
 	-- If invoked as a preview callback, performs 'inccommand' preview by
 	-- highlighting trailing whitespace in the current buffer.
 	local function trim_space_preview(opts, preview_ns, preview_buf)
+	  vim.cmd('hi clear Whitespace')
 	  local line1 = opts.line1
 	  local line2 = opts.line2
 	  local buf = vim.api.nvim_get_current_buf()
@@ -1722,7 +1730,11 @@ remains unmodified.  Also see |f-args-example| below.  Overview:
 	XX a\\\ b	   'a\ b'
 	XX a\\\\b	   'a\\b'
 	XX a\\\\ b	   'a\\', 'b'
+	XX		   [nothing]
+
 
+Note that if the "no arguments" situation is to be handled, you have to make
+sure that the function can be called without arguments.
 
 Examples for user commands: >
 
@@ -1770,9 +1782,5 @@ errors and the "update" command to write modified buffers): >
 This will invoke: >
 	:call Allargs("%s/foo/bar/ge|update")
 <
-When defining a user command in a script, it will be able to call functions
-local to the script and use mappings local to the script.  When the user
-invokes the user command, it will run in the context of the script it was
-defined in.  This matters if |<SID>| is used in a command.
 
  vim:tw=78:ts=8:noet:ft=help:norl: