vim-patch:c1b3984: runtime(doc): minor updates. (#29778)

closes: vim/vim#15280

https://github.com/vim/vim/commit/c1b3984a7b3cd6adcd1f43e558cb04fad1af3182

Co-authored-by: Shane Harper <shane@shaneharper.net>

7 files changed, 59 insertions, 46 deletions

diff --git a/runtime/doc/builtin.txt b/runtime/doc/builtin.txt
index 9c59dbf713..dbae18eca5 100644
--- a/runtime/doc/builtin.txt
+++ b/runtime/doc/builtin.txt
@@ -169,16 +169,17 @@ assert_equal({expected}, {actual} [, {msg}])                    *assert_equal()*
 		added to |v:errors| and 1 is returned.  Otherwise zero is
 		returned. |assert-return|
 		The error is in the form "Expected {expected} but got
-		{actual}".  When {msg} is present it is prefixed to that.
+		{actual}".  When {msg} is present it is prefixed to that, along
+		with the location of the assert when run from a script.
 
 		There is no automatic conversion, the String "4" is different
 		from the Number 4.  And the number 4 is different from the
 		Float 4.0.  The value of 'ignorecase' is not used here, case
 		always matters.
 		Example: >vim
-			assert_equal('foo', 'bar')
-<		Will result in a string to be added to |v:errors|:
-			test.vim line 12: Expected 'foo' but got 'bar' ~
+			call assert_equal('foo', 'bar', 'baz')
+<		Will add the following to |v:errors|:
+			test.vim line 12: baz: Expected 'foo' but got 'bar' ~
 
 assert_equalfile({fname-one}, {fname-two})                  *assert_equalfile()*
 		When the files {fname-one} and {fname-two} do not contain
@@ -240,7 +241,8 @@ assert_false({actual} [, {msg}])                                *assert_false()*
 		When {actual} is not false an error message is added to
 		|v:errors|, like with |assert_equal()|.
 		The error is in the form "Expected False but got {actual}".
-		When {msg} is present it is prepended to that.
+		When {msg} is present it is prepended to that, along
+		with the location of the assert when run from a script.
 		Also see |assert-return|.
 
 		A value is false when it is zero. When {actual} is not a
@@ -258,7 +260,8 @@ assert_match({pattern}, {actual} [, {msg}])                     *assert_match()*
 		When {pattern} does not match {actual} an error message is
 		added to |v:errors|.  Also see |assert-return|.
 		The error is in the form "Pattern {pattern} does not match
-		{actual}".  When {msg} is present it is prefixed to that.
+		{actual}".  When {msg} is present it is prefixed to that,
+		along with the location of the assert when run from a script.
 
 		{pattern} is used as with |expr-=~|: The matching is always done
 		like 'magic' was set and 'cpoptions' is empty, no matter what
@@ -298,7 +301,8 @@ assert_true({actual} [, {msg}])                                  *assert_true()*
 		Also see |assert-return|.
 		A value is |TRUE| when it is a non-zero number or |v:true|.
 		When {actual} is not a number or |v:true| the assert fails.
-		When {msg} is given it precedes the default message.
+		When {msg} is given it precedes the default message, along
+		with the location of the assert when run from a script.
 
 atan({expr})                                                            *atan()*
 		Return the principal value of the arc tangent of {expr}, in
@@ -4587,10 +4591,10 @@ matchadd({group}, {pattern} [, {priority} [, {id} [, {dict}]]])
 matchaddpos({group}, {pos} [, {priority} [, {id} [, {dict}]]])   *matchaddpos()*
 		Same as |matchadd()|, but requires a list of positions {pos}
 		instead of a pattern. This command is faster than |matchadd()|
-		because it does not require to handle regular expressions and
-		sets buffer line boundaries to redraw screen. It is supposed
-		to be used when fast match additions and deletions are
-		required, for example to highlight matching parentheses.
+		because it does not handle regular expressions and it sets
+		buffer line boundaries to redraw screen. It is supposed to be
+		used when fast match additions and deletions are required, for
+		example to highlight matching parentheses.
 							*E5030* *E5031*
 		{pos} is a list of positions.  Each position can be one of
 		these:
@@ -7630,8 +7634,8 @@ spellsuggest({word} [, {max} [, {capital}]])                    *spellsuggest()*
 
 split({string} [, {pattern} [, {keepempty}]])                          *split()*
 		Make a |List| out of {string}.  When {pattern} is omitted or
-		empty each white-separated sequence of characters becomes an
-		item.
+		empty each white space separated sequence of characters
+		becomes an item.
 		Otherwise the string is split where {pattern} matches,
 		removing the matched characters. 'ignorecase' is not used
 		here, add \c to ignore case. |/\c|
diff --git a/runtime/doc/eval.txt b/runtime/doc/eval.txt
index 7b4dba5a50..8e52b55bc7 100644
--- a/runtime/doc/eval.txt
+++ b/runtime/doc/eval.txt
@@ -2166,9 +2166,10 @@ text...
 				let lconst[0] = 2  " Error!
 				let lconst[1][0] = 'b'  " OK
 <							*E995*
-			|:const| does not allow to for changing a variable. >
+			It is an error to specify an existing variable with
+			:const. >
 				:let x = 1
-				:const x = 2  " Error!
+				:const x = 1  " Error!
 <							*E996*
 			Note that environment variables, option values and
 			register values cannot be used here, since they cannot
diff --git a/runtime/doc/gui.txt b/runtime/doc/gui.txt
index 104413ce0d..7e65ab6108 100644
--- a/runtime/doc/gui.txt
+++ b/runtime/doc/gui.txt
@@ -548,7 +548,7 @@ name and all existing submenus below it are affected.
 
 Examples for Menus					*menu-examples*
 
-Here is an example on how to add menu items with menu's!  You can add a menu
+Here is an example on how to add menu items with menus!  You can add a menu
 item for the keyword under the cursor.  The register "z" is used. >
 
   :nmenu Words.Add\ Var		wb"zye:menu! Words.<C-R>z <C-R>z<CR>
diff --git a/runtime/doc/quickfix.txt b/runtime/doc/quickfix.txt
index 7090694dc6..17c12e7a8d 100644
--- a/runtime/doc/quickfix.txt
+++ b/runtime/doc/quickfix.txt
@@ -1080,8 +1080,8 @@ commands can be combined to create a NewGrep command: >
 
 :vim[grep][!] {pattern} {file} ...
 			Like above, but instead of enclosing the pattern in a
-			non-ID character use a white-separated pattern.  The
-			pattern must start with an ID character.
+			non-ID character use a white space separated pattern.
+			The pattern must start with an ID character.
 			Example: >
 				:vimgrep Error *.c
 <
diff --git a/runtime/doc/various.txt b/runtime/doc/various.txt
index 1acd6941fd..9dd84ec4b0 100644
--- a/runtime/doc/various.txt
+++ b/runtime/doc/various.txt
@@ -28,8 +28,8 @@ CTRL-L			Clears and redraws the screen.  The redraw may happen
 :redr[aw][!]		Redraws pending screen updates now, or the entire
 			screen if "!" is included.  To CLEAR the screen use
 			|:mode| or |CTRL-L|.
-			Useful to update the screen during a script or
-			function (or a mapping if 'lazyredraw' set).
+			It can be used to redraw the screen in a script
+			or function (or a mapping if |'lazyredraw'| is set).
 			See also |nvim__redraw()|.
 
 						*:redraws* *:redrawstatus*
diff --git a/runtime/lua/vim/_meta/vimfn.lua b/runtime/lua/vim/_meta/vimfn.lua
index 750f16ef06..b68a16d014 100644
--- a/runtime/lua/vim/_meta/vimfn.lua
+++ b/runtime/lua/vim/_meta/vimfn.lua
@@ -203,16 +203,17 @@ function vim.fn.assert_beeps(cmd) end
 --- added to |v:errors| and 1 is returned.  Otherwise zero is
 --- returned. |assert-return|
 --- The error is in the form "Expected {expected} but got
---- {actual}".  When {msg} is present it is prefixed to that.
+--- {actual}".  When {msg} is present it is prefixed to that, along
+--- with the location of the assert when run from a script.
 ---
 --- There is no automatic conversion, the String "4" is different
 --- from the Number 4.  And the number 4 is different from the
 --- Float 4.0.  The value of 'ignorecase' is not used here, case
 --- always matters.
 --- Example: >vim
----   assert_equal('foo', 'bar')
---- <Will result in a string to be added to |v:errors|:
----   test.vim line 12: Expected 'foo' but got 'bar' ~
+---   call assert_equal('foo', 'bar', 'baz')
+--- <Will add the following to |v:errors|:
+---   test.vim line 12: baz: Expected 'foo' but got 'bar' ~
 ---
 --- @param expected any
 --- @param actual any
@@ -291,7 +292,8 @@ function vim.fn.assert_fails(cmd, error, msg, lnum, context) end
 --- When {actual} is not false an error message is added to
 --- |v:errors|, like with |assert_equal()|.
 --- The error is in the form "Expected False but got {actual}".
---- When {msg} is present it is prepended to that.
+--- When {msg} is present it is prepended to that, along
+--- with the location of the assert when run from a script.
 --- Also see |assert-return|.
 ---
 --- A value is false when it is zero. When {actual} is not a
@@ -319,7 +321,8 @@ function vim.fn.assert_inrange(lower, upper, actual, msg) end
 --- When {pattern} does not match {actual} an error message is
 --- added to |v:errors|.  Also see |assert-return|.
 --- The error is in the form "Pattern {pattern} does not match
---- {actual}".  When {msg} is present it is prefixed to that.
+--- {actual}".  When {msg} is present it is prefixed to that,
+--- along with the location of the assert when run from a script.
 ---
 --- {pattern} is used as with |expr-=~|: The matching is always done
 --- like 'magic' was set and 'cpoptions' is empty, no matter what
@@ -380,7 +383,8 @@ function vim.fn.assert_report(msg) end
 --- Also see |assert-return|.
 --- A value is |TRUE| when it is a non-zero number or |v:true|.
 --- When {actual} is not a number or |v:true| the assert fails.
---- When {msg} is given it precedes the default message.
+--- When {msg} is given it precedes the default message, along
+--- with the location of the assert when run from a script.
 ---
 --- @param actual any
 --- @param msg? any
@@ -5526,10 +5530,10 @@ function vim.fn.matchadd(group, pattern, priority, id, dict) end
 
 --- Same as |matchadd()|, but requires a list of positions {pos}
 --- instead of a pattern. This command is faster than |matchadd()|
---- because it does not require to handle regular expressions and
---- sets buffer line boundaries to redraw screen. It is supposed
---- to be used when fast match additions and deletions are
---- required, for example to highlight matching parentheses.
+--- because it does not handle regular expressions and it sets
+--- buffer line boundaries to redraw screen. It is supposed to be
+--- used when fast match additions and deletions are required, for
+--- example to highlight matching parentheses.
 ---           *E5030* *E5031*
 --- {pos} is a list of positions.  Each position can be one of
 --- these:
@@ -9067,8 +9071,8 @@ function vim.fn.spellbadword(sentence) end
 function vim.fn.spellsuggest(word, max, capital) end
 
 --- Make a |List| out of {string}.  When {pattern} is omitted or
---- empty each white-separated sequence of characters becomes an
---- item.
+--- empty each white space separated sequence of characters
+--- becomes an item.
 --- Otherwise the string is split where {pattern} matches,
 --- removing the matched characters. 'ignorecase' is not used
 --- here, add \c to ignore case. |/\c|
diff --git a/src/nvim/eval.lua b/src/nvim/eval.lua
index bbc78bc68e..7ca14693ef 100644
--- a/src/nvim/eval.lua
+++ b/src/nvim/eval.lua
@@ -301,16 +301,17 @@ M.funcs = {
       added to |v:errors| and 1 is returned.  Otherwise zero is
       returned. |assert-return|
       The error is in the form "Expected {expected} but got
-      {actual}".  When {msg} is present it is prefixed to that.
+      {actual}".  When {msg} is present it is prefixed to that, along
+      with the location of the assert when run from a script.
 
       There is no automatic conversion, the String "4" is different
       from the Number 4.  And the number 4 is different from the
       Float 4.0.  The value of 'ignorecase' is not used here, case
       always matters.
       Example: >vim
-      	assert_equal('foo', 'bar')
-      <Will result in a string to be added to |v:errors|:
-      	test.vim line 12: Expected 'foo' but got 'bar' ~
+      	call assert_equal('foo', 'bar', 'baz')
+      <Will add the following to |v:errors|:
+      	test.vim line 12: baz: Expected 'foo' but got 'bar' ~
 
     ]=],
     name = 'assert_equal',
@@ -411,7 +412,8 @@ M.funcs = {
       When {actual} is not false an error message is added to
       |v:errors|, like with |assert_equal()|.
       The error is in the form "Expected False but got {actual}".
-      When {msg} is present it is prepended to that.
+      When {msg} is present it is prepended to that, along
+      with the location of the assert when run from a script.
       Also see |assert-return|.
 
       A value is false when it is zero. When {actual} is not a
@@ -446,7 +448,8 @@ M.funcs = {
       When {pattern} does not match {actual} an error message is
       added to |v:errors|.  Also see |assert-return|.
       The error is in the form "Pattern {pattern} does not match
-      {actual}".  When {msg} is present it is prefixed to that.
+      {actual}".  When {msg} is present it is prefixed to that,
+      along with the location of the assert when run from a script.
 
       {pattern} is used as with |expr-=~|: The matching is always done
       like 'magic' was set and 'cpoptions' is empty, no matter what
@@ -531,7 +534,8 @@ M.funcs = {
       Also see |assert-return|.
       A value is |TRUE| when it is a non-zero number or |v:true|.
       When {actual} is not a number or |v:true| the assert fails.
-      When {msg} is given it precedes the default message.
+      When {msg} is given it precedes the default message, along
+      with the location of the assert when run from a script.
 
     ]=],
     name = 'assert_true',
@@ -6735,10 +6739,10 @@ M.funcs = {
     desc = [=[
       Same as |matchadd()|, but requires a list of positions {pos}
       instead of a pattern. This command is faster than |matchadd()|
-      because it does not require to handle regular expressions and
-      sets buffer line boundaries to redraw screen. It is supposed
-      to be used when fast match additions and deletions are
-      required, for example to highlight matching parentheses.
+      because it does not handle regular expressions and it sets
+      buffer line boundaries to redraw screen. It is supposed to be
+      used when fast match additions and deletions are required, for
+      example to highlight matching parentheses.
       					*E5030* *E5031*
       {pos} is a list of positions.  Each position can be one of
       these:
@@ -10786,8 +10790,8 @@ M.funcs = {
     base = 1,
     desc = [=[
       Make a |List| out of {string}.  When {pattern} is omitted or
-      empty each white-separated sequence of characters becomes an
-      item.
+      empty each white space separated sequence of characters
+      becomes an item.
       Otherwise the string is split where {pattern} matches,
       removing the matched characters. 'ignorecase' is not used
       here, add \c to ignore case. |/\c|