vim-patch:d592deb33652 (#19002)

Update runtime files
https://github.com/vim/vim/commit/d592deb336523a5448779ee3d4bba80334cff1f7

4 files changed, 59 insertions, 17 deletions

diff --git a/runtime/doc/builtin.txt b/runtime/doc/builtin.txt
index 0b32b3a420..43c1f80fd6 100644
--- a/runtime/doc/builtin.txt
+++ b/runtime/doc/builtin.txt
@@ -7618,6 +7618,8 @@ strcharpart({src}, {start} [, {len}])			*strcharpart()*
 			strcharpart('abc', -1, 2)
 <		results in 'a'.
 
+		Returns an empty string on error.
+
 		Can also be used as a |method|: >
 			GetText()->strcharpart(5)
 
@@ -7627,6 +7629,9 @@ strchars({string} [, {skipcc}])					*strchars()*
 		When {skipcc} is omitted or zero, composing characters are
 		counted separately.
 		When {skipcc} set to 1, Composing characters are ignored.
+
+		Returns zero on error.
+
 		Also see |strlen()|, |strdisplaywidth()| and |strwidth()|.
 
 		{skipcc} is only available after 7.4.755.  For backward
@@ -7659,6 +7664,7 @@ strdisplaywidth({string} [, {col}])			*strdisplaywidth()*
 		'tabstop' and 'display'.
 		When {string} contains characters with East Asian Width Class
 		Ambiguous, this function's return value depends on 'ambiwidth'.
+		Returns zero on error.
 		Also see |strlen()|, |strwidth()| and |strchars()|.
 
 		Can also be used as a |method|: >
@@ -7690,6 +7696,7 @@ strgetchar({str}, {index})				*strgetchar()*
 		index.  Composing characters are considered separate
 		characters here.  Use |nr2char()| to convert the Number to a
 		String.
+		Returns -1 if {index} is invalid.
 		Also see |strcharpart()| and |strchars()|.
 
 		Can also be used as a |method|: >
@@ -7748,7 +7755,7 @@ strlen({string})						*strlen()*
 		The result is a Number, which is the length of the String
 		{string} in bytes.
 		If the argument is a Number it is first converted to a String.
-		For other types an error is given.
+		For other types an error is given and zero is returned.
 		If you want to count the number of multibyte characters use
 		|strchars()|.
 		Also see |len()|, |strdisplaywidth()| and |strwidth()|.
@@ -7779,6 +7786,8 @@ strpart({src}, {start} [, {len} [, {chars}]])			*strpart()*
 		example, to get the character under the cursor: >
 			strpart(getline("."), col(".") - 1, 1, v:true)
 <
+		Returns an empty string on error.
+
 		Can also be used as a |method|: >
 			GetText()->strpart(5)
 
@@ -7838,6 +7847,8 @@ strtrans({string})					*strtrans()*
 <		This displays a newline in register a as "^@" instead of
 		starting a new line.
 
+		Returns an empty string on error.
+
 		Can also be used as a |method|: >
 			GetString()->strtrans()
 
@@ -7847,6 +7858,7 @@ strwidth({string})					*strwidth()*
 		cell, alternatively use |strdisplaywidth()|.
 		When {string} contains characters with East Asian Width Class
 		Ambiguous, this function's return value depends on 'ambiwidth'.
+		Returns zero on error.
 		Also see |strlen()|, |strdisplaywidth()| and |strchars()|.
 
 		Can also be used as a |method|: >
@@ -7872,6 +7884,8 @@ submatch({nr} [, {list}])			*submatch()* *E935*
 		When substitute() is used recursively only the submatches in
 		the current (deepest) call can be obtained.
 
+		Returns an empty string or list on error.
+
 		Examples: >
 			:s/\d\+/\=submatch(0) + 1/
 			:echo substitute(text, '\d\+', '\=submatch(0) + 1', '')
@@ -7922,7 +7936,9 @@ substitute({string}, {pat}, {sub}, {flags})		*substitute()*
 		|submatch()| returns.  Example: >
 		   :echo substitute(s, '%\(\x\x\)', {m -> '0x' .. m[1]}, 'g')
 
-<		Can also be used as a |method|: >
+<		Returns an empty string on error.
+
+		Can also be used as a |method|: >
 			GetString()->substitute(pat, sub, flags)
 
 swapinfo({fname})					*swapinfo()*
@@ -7976,6 +7992,8 @@ synID({lnum}, {col}, {trans})				*synID()*
 		Warning: This function can be very slow.  Best speed is
 		obtained by going through the file in forward direction.
 
+		Returns zero on error.
+
 		Example (echoes the name of the syntax item under the cursor): >
 			:echo synIDattr(synID(line("."), col("."), 1), "name")
 <
@@ -8018,6 +8036,8 @@ synIDattr({synID}, {what} [, {mode}])			*synIDattr()*
 		cursor): >
 	:echo synIDattr(synIDtrans(synID(line("."), col("."), 1)), "fg")
 <
+		Returns an empty string on error.
+
 		Can also be used as a |method|: >
 	:echo synID(line("."), col("."), 1)->synIDtrans()->synIDattr("fg")
 
@@ -8027,6 +8047,8 @@ synIDtrans({synID})					*synIDtrans()*
 		highlight the character.  Highlight links given with
 		":highlight link" are followed.
 
+		Returns zero on error.
+
 		Can also be used as a |method|: >
 	:echo synID(line("."), col("."), 1)->synIDtrans()->synIDattr("fg")
 
@@ -8071,7 +8093,7 @@ synstack({lnum}, {col})					*synstack()*
 			   echo synIDattr(id, "name")
 			endfor
 <		When the position specified with {lnum} and {col} is invalid
-		nothing is returned.  The position just after the last
+		an empty list is returned.  The position just after the last
 		character in a line and the first column in an empty line are
 		valid positions.
 
@@ -8170,6 +8192,8 @@ tabpagenr([{arg}])					*tabpagenr()*
 				previous tab page, 0 is returned.
 		The number can be used with the |:tab| command.
 
+		Returns zero on error.
+
 tabpagewinnr({tabarg} [, {arg}])			*tabpagewinnr()*
 		Like |winnr()| but for tab page {tabarg}.
 		{tabarg} specifies the number of tab page to be used.
@@ -8262,6 +8286,7 @@ tan({expr})						*tan()*
 		Return the tangent of {expr}, measured in radians, as a |Float|
 		in the range [-inf, inf].
 		{expr} must evaluate to a |Float| or a |Number|.
+		Returns 0.0 if {expr} is not a |Float| or a |Number|.
 		Examples: >
 			:echo tan(10)
 <			0.648361 >
@@ -8275,6 +8300,7 @@ tanh({expr})						*tanh()*
 		Return the hyperbolic tangent of {expr} as a |Float| in the
 		range [-1, 1].
 		{expr} must evaluate to a |Float| or a |Number|.
+		Returns 0.0 if {expr} is not a |Float| or a |Number|.
 		Examples: >
 			:echo tanh(0.5)
 <			0.462117 >
@@ -8338,6 +8364,8 @@ timer_start({time}, {callback} [, {options}])
 				If the timer causes an error three times in a
 				row the repeat is cancelled.
 
+		Returns -1 on error.
+
 		Example: >
 			func MyHandler(timer)
 			  echo 'Handler called'
@@ -8367,7 +8395,7 @@ timer_stopall()						*timer_stopall()*
 tolower({expr})						*tolower()*
 		The result is a copy of the String given, with all uppercase
 		characters turned into lowercase (just like applying |gu| to
-		the string).
+		the string).  Returns an empty string on error.
 
 		Can also be used as a |method|: >
 			GetText()->tolower()
@@ -8375,7 +8403,7 @@ tolower({expr})						*tolower()*
 toupper({expr})						*toupper()*
 		The result is a copy of the String given, with all lowercase
 		characters turned into uppercase (just like applying |gU| to
-		the string).
+		the string).  Returns an empty string on error.
 
 		Can also be used as a |method|: >
 			GetText()->toupper()
@@ -8388,6 +8416,8 @@ tr({src}, {fromstr}, {tostr})				*tr()*
 		and so on.  Exactly like the unix "tr" command.
 		This code also deals with multibyte characters properly.
 
+		Returns an empty string on error.
+
 		Examples: >
 			echo tr("hello there", "ht", "HT")
 <		returns "Hello THere" >
@@ -8410,6 +8440,8 @@ trim({text} [, {mask} [, {dir}]])				*trim()*
 			2	remove only at the end of {text}
 		When omitted both ends are trimmed.
 		This function deals with multibyte characters properly.
+		Returns an empty string on error.
+
 		Examples: >
 			echo trim("   some text ")
 <		returns "some text" >
@@ -8427,6 +8459,7 @@ trunc({expr})							*trunc()*
 		Return the largest integral value with magnitude less than or
 		equal to {expr} as a |Float| (truncate towards zero).
 		{expr} must evaluate to a |Float| or a |Number|.
+		Returns 0.0 if {expr} is not a |Float| or a |Number|.
 		Examples: >
 			echo trunc(1.456)
 <			1.0  >
@@ -8533,12 +8566,15 @@ uniq({list} [, {func} [, {dict}]])			*uniq()* *E882*
 <		The default compare function uses the string representation of
 		each item.  For the use of {func} and {dict} see |sort()|.
 
+		Returns zero if {list} is not a |List|.
+
 		Can also be used as a |method|: >
 			mylist->uniq()
 
 values({dict})						*values()*
 		Return a |List| with all the values of {dict}.  The |List| is
 		in arbitrary order.  Also see |items()| and |keys()|.
+		Returns zero if {dict} is not a |Dict|.
 
 		Can also be used as a |method|: >
 			mydict->values()
@@ -8667,7 +8703,7 @@ win_gettype([{nr}])					*win_gettype()*
 			"command"	command-line window |cmdwin|
 			(empty)		normal window
 			"loclist"	|location-list-window|
-			"popup"		popup window |popup|
+			"popup"		floating window |api-floatwin|
 			"preview"	preview window |preview-window|
 			"quickfix"	|quickfix-window|
 			"unknown"	window {nr} not found
@@ -8676,9 +8712,7 @@ win_gettype([{nr}])					*win_gettype()*
 		When {nr} is given return the type of this window by number or
 		|window-ID|.
 
-		Also see the 'buftype' option.  When running a terminal in a
-		popup window then 'buftype' is "terminal" and win_gettype()
-		returns "popup".
+		Also see the 'buftype' option.
 
 		Can also be used as a |method|: >
 			GetWinid()->win_gettype()
@@ -8717,6 +8751,8 @@ win_move_separator({nr}, {offset})			*win_move_separator()*
 		specified (e.g., as a consequence of maintaining
 		'winminwidth'). Returns TRUE if the window can be found and
 		FALSE otherwise.
+		This will fail for the rightmost window and a full-width
+		window, since it has no separator on the right.
 
 		Can also be used as a |method|: >
 			GetWinnr()->win_move_separator(offset)
diff --git a/runtime/doc/cmdline.txt b/runtime/doc/cmdline.txt
index 23a87505ad..e105b5e556 100644
--- a/runtime/doc/cmdline.txt
+++ b/runtime/doc/cmdline.txt
@@ -1136,8 +1136,8 @@ save the command-line history and read it back later.
 If the 'wildchar' option is set to <Tab>, and the command-line window is used
 for an Ex command, then two mappings will be added to use <Tab> for completion
 in the command-line window, like this: >
-	:imap <buffer> <Tab> <C-X><C-V>
-	:nmap <buffer> <Tab> a<C-X><C-V>
+	:inoremap <buffer> <Tab> <C-X><C-V>
+	:nnoremap <buffer> <Tab> a<C-X><C-V>
 Note that hitting <Tab> in Normal mode will do completion on the next
 character.  That way it works at the end of the line.
 If you don't want these mappings, disable them with: >
diff --git a/runtime/doc/map.txt b/runtime/doc/map.txt
index 59a5a63e16..2206d13053 100644
--- a/runtime/doc/map.txt
+++ b/runtime/doc/map.txt
@@ -345,9 +345,15 @@ Note:
   mapping is recursive.
 - 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.
-- In select-mode, |:map| and |:vmap| command mappings are executed in
-  visual-mode.  Use |:smap| to handle select-mode.
-
+- In Select mode, |:map| and |:vmap| command mappings are executed in
+  Visual mode.  Use |:smap| to handle Select mode differently.  One particular
+  edge case: >
+  	:vnoremap <C-K> <Esc>
+<  This ends Visual mode when in Visual mode, but in Select mode it does not
+  work, because Select mode is restored after executing the mapped keys.  You
+  need to use: >
+  	:snoremap <C-K> <Esc>
+<
 							*E5520*
 <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.
diff --git a/runtime/doc/pi_netrw.txt b/runtime/doc/pi_netrw.txt
index 2fe3d3d8e0..6f7b53722c 100644
--- a/runtime/doc/pi_netrw.txt
+++ b/runtime/doc/pi_netrw.txt
@@ -440,11 +440,11 @@ settings are described below, in |netrw-browser-options|, and in
 
  *g:netrw_use_errorwindow* =2: messages from netrw will use a popup window
 			     Move the mouse and pause to remove the popup window.
-			     (default value if popup windows are availble)
+			     (default value if popup windows are available)
 			 =1 : messages from netrw will use a separate one
 			      line window.  This window provides reliable
 			      delivery of messages.
-			     (default value if popup windows are not availble)
+			     (default value if popup windows are not available)
 			 =0 : messages from netrw will use echoerr ;
 			      messages don't always seem to show up this
 			      way, but one doesn't have to quit the window.
@@ -1198,7 +1198,7 @@ If there are marked files and/or directories, mb will add them to the bookmark
 list.
 
 								*netrw-:NetrwMB*
-Addtionally, one may use :NetrwMB to bookmark files or directories. >
+Additionally, one may use :NetrwMB to bookmark files or directories. >
 
 	:NetrwMB[!] [files/directories]