vim-patch:b6f9d38: runtime(doc): Improve documentation of the ..= assignment operator (#35916)

Explicitly mention the "..=" compound assignment operator everywhere
".=" is documented.

Convert some uses of "." and ".=" in the examples to ".." and "..=",
respectively.

closes: vim/vim#18380

b6f9d38f96

Cherry-pick a change to eval.txt from patch 9.1.1232.

Co-authored-by: Doug Kearns <dougkearns@gmail.com>

runtime/doc/cmdline.txt

@@ -1078,7 +1078,7 @@ These modifiers can be given, in this order:
 	:S	Escape special characters for use with a shell command (see
 		|shellescape()|). Must be the last one. Examples: >
 		    :!dir <cfile>:S
-		    :call system('chmod +w -- ' . expand('%:S'))
+		    :call system('chmod +w -- ' .. expand('%:S'))
 
 Examples, when the file name is "src/version.c", current dir
 "/home/mool/vim": >
@@ -1360,7 +1360,7 @@ the `CmdlineLeavePre` autocmd from the next section): >
 		\ Grep call <SID>VisitFile()
 
 	func s:Grep(arglead, cmdline, cursorpos)
-	  if match(&grepprg, '\$\*') == -1 | let &grepprg .= ' $*' | endif
+	  if match(&grepprg, '\$\*') == -1 | let &grepprg ..= ' $*' | endif
 	  let cmd = substitute(&grepprg, '\$\*', shellescape(escape(a:arglead, '\')), '')
 	  return len(a:arglead) > 1 ? systemlist(cmd) : []
 	endfunc

runtime/doc/filetype.txt

@@ -722,7 +722,7 @@ Otherwise, for the defined variable "g:ftplugin_java_source_path", the local
 value of the 'path' option will be further modified by prefixing the value of
 the variable, e.g.: >
 	let g:ftplugin_java_source_path = $JDK_SRC_PATH
-	let &l:path = g:ftplugin_java_source_path . ',' . &l:path
+	let &l:path = g:ftplugin_java_source_path .. ',' .. &l:path
 <
 and the "gf" command can be used on a fully-qualified type to look for a file
 in the "path" and to try to load it.

runtime/doc/quickfix.txt

@@ -1440,7 +1440,7 @@ declares an only parameter of type string and puts to use a command equivalent
 of |:make|, and assigning its |Funcref| to the selected key.  For example:
 >vim
 	function! GenericPostCompilerCommand(arguments) abort
-		execute 'make ' . a:arguments
+		execute 'make ' .. a:arguments
 	endfunction
 
 	let g:spotbugs_properties = {
@@ -1471,7 +1471,7 @@ that will arrange for "PostCompilerActionExecutor" to be invoked; and then run
 	function! GenericPreCompilerCommand(arguments) abort
 		if !exists('g:spotbugs_compilation_done')
 			doautocmd java_spotbugs_post User
-			execute 'make ' . a:arguments
+			execute 'make ' .. a:arguments
 			" only run doautocmd when :make was synchronous
 			" see note below
 			doautocmd java_spotbugs_post ShellCmdPost " XXX: (a)
@@ -1484,7 +1484,7 @@ that will arrange for "PostCompilerActionExecutor" to be invoked; and then run
 	function! GenericPreCompilerTestCommand(arguments) abort
 		if !exists('g:spotbugs_test_compilation_done')
 			doautocmd java_spotbugs_post User
-			execute 'make ' . a:arguments
+			execute 'make ' .. a:arguments
 			" only run doautocmd when :make was synchronous
 			" see note below
 			doautocmd java_spotbugs_post ShellCmdPost " XXX: (b)

runtime/doc/usr_40.txt

@@ -597,7 +597,7 @@ EXECUTING AUTOCOMMANDS
 It is possible to trigger an autocommand by pretending an event has occurred.
 This is useful to have one autocommand trigger another one.  Example: >
 
-	:autocmd BufReadPost *.new  execute "doautocmd BufReadPost " . expand("<afile>:r")
+	:autocmd BufReadPost *.new  execute "doautocmd BufReadPost " .. expand("<afile>:r")
 
 This defines an autocommand that is triggered when a new file has been edited.
 The file name must end in ".new".  The ":execute" command uses expression

runtime/doc/vimeval.txt

@@ -1921,6 +1921,7 @@ This does NOT work: >
 			Set environment variable {env-name} to the result of
 			the expression {expr1}.  The type is always String.
 :let ${env-name} .= {expr1}
+:let ${env-name} ..= {expr1}
 			Append {expr1} to the environment variable {env-name}.
 			If the environment variable didn't exist yet this
 			works like "=".
@@ -1940,6 +1941,7 @@ This does NOT work: >
 			that would match everywhere.
 
 :let @{reg-name} .= {expr1}
+:let @{reg-name} ..= {expr1}
 			Append {expr1} to register {reg-name}.  If the
 			register was empty it's like setting it to {expr1}.
 
@@ -1954,6 +1956,7 @@ This does NOT work: >
 				:let &path = &path .. ',/usr/local/include'
 
 :let &{option-name} .= {expr1}
+:let &{option-name} ..= {expr1}
 			For a string option: Append {expr1} to the value.
 			Does not insert a comma like |:set+=|.
 
@@ -1963,16 +1966,18 @@ This does NOT work: >
 			{expr1}.
 
 :let &l:{option-name} = {expr1}
-:let &l:{option-name} .= {expr1}
 :let &l:{option-name} += {expr1}
 :let &l:{option-name} -= {expr1}
+:let &l:{option-name} .= {expr1}
+:let &l:{option-name} ..= {expr1}
 			Like above, but only set the local value of an option
 			(if there is one).  Works like |:setlocal|.
 
 :let &g:{option-name} = {expr1}
-:let &g:{option-name} .= {expr1}
 :let &g:{option-name} += {expr1}
 :let &g:{option-name} -= {expr1}
+:let &g:{option-name} .= {expr1}
+:let &g:{option-name} ..= {expr1}
 			Like above, but only set the global value of an option
 			(if there is one).  Works like |:setglobal|.
 
@@ -1995,11 +2000,15 @@ This does NOT work: >
 				:echo x
 <			The result is [0, 2].
 
-:let [{name1}, {name2}, ...] .= {expr1}
 :let [{name1}, {name2}, ...] += {expr1}
 :let [{name1}, {name2}, ...] -= {expr1}
-			Like above, but append/add/subtract the value for each
+`:let [{name1}, {name2}, ...] *= {expr1}`
-			|List| item.
+:let [{name1}, {name2}, ...] /= {expr1}
+:let [{name1}, {name2}, ...] %= {expr1}
+:let [{name1}, {name2}, ...] .= {expr1}
+:let [{name1}, {name2}, ...] ..= {expr1}
+			Like above, but add, subtract, multiply, divide,
+			modulo, or append the value for each |List| item.
 
 :let [{name}, ..., ; {lastname}] = {expr1}				*E452*
 			Like |:let-unpack| above, but the |List| may have more
@@ -2009,10 +2018,11 @@ This does NOT work: >
 			Example: >
 				:let [a, b; rest] = ["aval", "bval", 3, 4]
 <
-:let [{name}, ..., ; {lastname}] .= {expr1}
 :let [{name}, ..., ; {lastname}] += {expr1}
 :let [{name}, ..., ; {lastname}] -= {expr1}
-			Like above, but append/add/subtract the value for each
+:let [{name}, ..., ; {lastname}] .= {expr1}
+:let [{name}, ..., ; {lastname}] ..= {expr1}
+			Like above, but add/subtract/append the value for each
 			|List| item.
 
 						*:let=<<* *:let-heredoc*