vim-patch:d1caa941d876

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

Cherry-pick error E452 from patch v8.2.0486.

7 files changed, 50 insertions, 24 deletions

diff --git a/runtime/doc/change.txt b/runtime/doc/change.txt
index 0f2ffa487c..5671a29356 100644
--- a/runtime/doc/change.txt
+++ b/runtime/doc/change.txt
@@ -1402,7 +1402,7 @@ text.  Put it in your autoload directory, e.g. ~/.vim/autoload/format.vim: >
   func! format#Format()
     " only reformat on explicit gq command
     if mode() != 'n'
-      " fall back to Vims internal reformatting
+      " fall back to Vim's internal reformatting
       return 1
     endif
     let lines = getline(v:lnum, v:lnum + v:count - 1)
diff --git a/runtime/doc/eval.txt b/runtime/doc/eval.txt
index 8558493520..c14af9001c 100644
--- a/runtime/doc/eval.txt
+++ b/runtime/doc/eval.txt
@@ -4446,10 +4446,11 @@ getcompletion({pat}, {type} [, {filtered}])		*getcompletion()*
 
 							*getcurpos()*
 getcurpos()	Get the position of the cursor.  This is like getpos('.'), but
-		includes an extra item in the list:
-		    [bufnum, lnum, col, off, curswant] ~
- 		The "curswant" number is the preferred column when moving the
+		includes an extra "curswant" in the list:
+		    [0, lnum, col, off, curswant] ~
+		The "curswant" number is the preferred column when moving the
 		cursor vertically.  Also see |getpos()|.
+		The first "bufnum" item is always zero.
 
  		This can be used to save and restore the cursor position: >
  			let save_cursor = getcurpos()
@@ -7790,18 +7791,10 @@ settagstack({nr}, {dict} [, {action}])			*settagstack()*
 
 		Returns zero for success, -1 for failure.
 
-		Examples:
-		    Set current index of the tag stack to 4: >
-			call settagstack(1005, {'curidx' : 4})
-
-<		    Empty the tag stack of window 3: >
+		Examples (for more examples see |tagstack-examples||):
+		    Empty the tag stack of window 3: >
 			call settagstack(3, {'items' : []})
 
-<		    Push a new item onto the tag stack: >
-			let pos = [bufnr('myfile.txt'), 10, 1, 0]
-			let newtag = [{'tagname' : 'mytag', 'from' : pos}]
-			call settagstack(2, {'items' : newtag}, 'a')
-
 <		    Save and restore the tag stack: >
 			let stack = gettagstack(1003)
 			" do something else
@@ -9581,8 +9574,8 @@ It is allowed to define another function inside a function body.
 You can provide default values for positional named arguments.  This makes
 them optional for function calls.  When a positional argument is not
 specified at a call, the default expression is used to initialize it.
-This only works for functions declared with |function|, not for lambda
-expressions |expr-lambda|.
+This only works for functions declared with |function|, not for
+lambda expressions |expr-lambda|.
 
 Example: >
   function Something(key, value = 10)
@@ -9611,9 +9604,10 @@ Example that does NOT work: >
   :function NoGood(first = a:second, second = 10)
   :endfunction
 <
-When not using "...", the number of arguments in a function call must be equal
-to the number of mandatory named arguments.  When using "...", the number of
-arguments may be larger.
+When not using "...", the number of arguments in a function call must be at
+least equal to the number of mandatory named arguments.  When using "...", the
+number of arguments may be larger than the total of mandatory and optional
+arguments.
 
 							*local-variables*
 Inside a function local variables can be used.  These will disappear when the
@@ -9943,7 +9937,7 @@ This does NOT work: >
 			Like above, but append/add/subtract the value for each
 			|List| item.
 
-:let [{name}, ..., ; {lastname}] = {expr1}
+:let [{name}, ..., ; {lastname}] = {expr1}				*E452*
 			Like |:let-unpack| above, but the |List| may have more
 			items than there are names.  A list of the remaining
 			items is assigned to {lastname}.  If there are no
diff --git a/runtime/doc/help.txt b/runtime/doc/help.txt
index 52a66c9df5..e3ddb5f687 100644
--- a/runtime/doc/help.txt
+++ b/runtime/doc/help.txt
@@ -30,7 +30,7 @@ Get specific help:  It is possible to go directly to whatever you want help
 		    help entries for "word".
 		    Or use ":helpgrep word". |:helpgrep|
 
-  Getting started:  Do the Vim tutor, a 20 minute interactive training for the
+  Getting started:  Do the Vim tutor, a 30-minute interactive course for the
 		    basic commands, see |vimtutor|.
 		    Read the user manual from start to end: |usr_01.txt|
 
@@ -40,7 +40,7 @@ through the help of many others.  See |credits|.
 						*doc-file-list* *Q_ct*
 BASIC:
 |quickref|	Overview of the most common commands you will use
-|tutor|		20 minutes training course for beginners
+|tutor|		30-minute interactive course for beginners
 |copying|	About copyrights
 |iccf|		Helping poor children in Uganda
 |sponsor|	Sponsor Vim development, become a registered Vim user
diff --git a/runtime/doc/insert.txt b/runtime/doc/insert.txt
index 60807821c7..006d5a933d 100644
--- a/runtime/doc/insert.txt
+++ b/runtime/doc/insert.txt
@@ -143,6 +143,8 @@ CTRL-R CTRL-R {register}			*i_CTRL-R_CTRL-R*
 		you also want to avoid these, use CTRL-R CTRL-O, see below.
 		The '.' register (last inserted text) is still inserted as
 		typed.
+		After this command, the '.' register contains the text from
+		the register as if it was inserted by typing it.
 
 CTRL-R CTRL-O {register}			*i_CTRL-R_CTRL-O*
 		Insert the contents of a register literally and don't
@@ -152,6 +154,9 @@ CTRL-R CTRL-O {register}			*i_CTRL-R_CTRL-O*
 		Does not replace characters!
 		The '.' register (last inserted text) is still inserted as
 		typed.
+		After this command, the '.' register contains the command
+		typed and not the text. I.e., the literals "^R^O" and not the
+		text from the register.
 
 CTRL-R CTRL-P {register}			*i_CTRL-R_CTRL-P*
 		Insert the contents of a register literally and fix the
@@ -159,6 +164,9 @@ CTRL-R CTRL-P {register}			*i_CTRL-R_CTRL-P*
 		Does not replace characters!
 		The '.' register (last inserted text) is still inserted as
 		typed.
+		After this command, the '.' register contains the command
+		typed and not the text. I.e., the literals "^R^P" and not the
+		text from the register.
 
 						*i_CTRL-T*
 CTRL-T		Insert one shiftwidth of indent at the start of the current
diff --git a/runtime/doc/tagsrch.txt b/runtime/doc/tagsrch.txt
index 240765fa2d..859c68cd36 100644
--- a/runtime/doc/tagsrch.txt
+++ b/runtime/doc/tagsrch.txt
@@ -179,6 +179,29 @@ commands explained above the tag stack will look like this:
 The |gettagstack()| function returns the tag stack of a specified window. The
 |settagstack()| function modifies the tag stack of a window.
 
+							*tagstack-examples*
+Write to the tag stack just like `:tag` but with a user-defined
+jumper#jump_to_tag function: >
+	" Store where we're jumping from before we jump.
+	let tag = expand('<cword>')
+	let pos = [bufnr()] + getcurpos()[1:]
+	let item = {'bufnr': pos[0], 'from': pos, 'tagname': tag}
+	if jumper#jump_to_tag(tag)
+		" Jump was successful, write previous location to tag stack.
+		let winid = win_getid()
+		let stack = gettagstack(winid)
+		let stack['items'] = [item]
+		call settagstack(winid, stack, 't')
+	endif
+<
+Set current index of the tag stack to 4: >
+	call settagstack(1005, {'curidx' : 4})
+<
+Push a new item onto the tag stack: >
+	let pos = [bufnr('myfile.txt'), 10, 1, 0]
+	let newtag = [{'tagname' : 'mytag', 'from' : pos}]
+	call settagstack(2, {'items' : newtag}, 'a')
+<
 							*E73*
 When you try to use the tag stack while it doesn't contain anything you will
 get an error message.
diff --git a/runtime/doc/usr_22.txt b/runtime/doc/usr_22.txt
index 7c78146056..56fe5ada2b 100644
--- a/runtime/doc/usr_22.txt
+++ b/runtime/doc/usr_22.txt
@@ -84,7 +84,7 @@ browser.  This is what you get: >
      	 a................Hiding Files or Directories................|netrw-a|
      	 mb...............Bookmarking a Directory....................|netrw-mb|
      	 gb...............Changing to a Bookmarked Directory.........|netrw-gb|
-     	 c................Make Browsing Directory The Current Dir....|netrw-c|
+     	 cd...............Make Browsing Directory The Current Dir....|netrw-c|
      	 d................Make A New Directory.......................|netrw-d|
      	 D................Deleting Files or Directories..............|netrw-D|
      	 <c-h>............Edit File/Directory Hiding List............|netrw-ctrl-h|
@@ -121,7 +121,7 @@ The following normal-mode commands may be used to control the browser display:
 
 As a sampling of extra normal-mode commands:
 
-	c		Change Vim's notion of the current directory to be
+	cd		Change Vim's notion of the current directory to be
 			the same as the browser directory.  (see
 			|g:netrw_keepdir| to control this, too)
 	R		Rename the file or directory under the cursor; a
diff --git a/runtime/doc/vim_diff.txt b/runtime/doc/vim_diff.txt
index 90953a4721..2c39fdb53c 100644
--- a/runtime/doc/vim_diff.txt
+++ b/runtime/doc/vim_diff.txt
@@ -505,6 +505,7 @@ Test functions:
   test_null_blob()
   test_null_channel()
   test_null_dict()
+  test_null_function()
   test_null_job()
   test_null_list()
   test_null_partial()