Commit: runtime(doc): Improve documentation of the ..= assignment operator

[Christian Brabandt]

runtime(doc): Improve documentation of the ..= assignment operator

Commit: https://github.com/vim/vim/commit/b6f9d38f9607d837b45d905f58dc0199f79414dc
Author: Doug Kearns <dougk...@gmail.com>
Date: Wed Sep 24 18:00:16 2025 +0000

runtime(doc): Improve documentation of the ..= assignment operator

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

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

closes: #18380

Signed-off-by: Doug Kearns <dougk...@gmail.com>
Signed-off-by: Christian Brabandt <c...@256bit.org>

diff --git a/runtime/doc/builtin.txt b/runtime/doc/builtin.txt
index 2e9535e65..54dfb27c9 100644
--- a/runtime/doc/builtin.txt
+++ b/runtime/doc/builtin.txt
@@ -1,4 +1,4 @@
-*builtin.txt* For Vim version 9.1. Last change: 2025 Sep 22
+*builtin.txt* For Vim version 9.1. Last change: 2025 Sep 24


VIM REFERENCE MANUAL by Bram Moolenaar
@@ -12661,7 +12661,7 @@ winbufnr({nr}) The result is a Number, which is the number of the buffer
window is returned.
When window {nr} doesn't exist, -1 is returned.
Example: >
- :echo "The file in the current window is " . bufname(winbufnr(0))
+ :echo "The file in the current window is " .. bufname(winbufnr(0))
<
Can also be used as a |method|: >
FindWindow()->winbufnr()->bufname()
diff --git a/runtime/doc/cmdline.txt b/runtime/doc/cmdline.txt
index f5a54b784..88a4e1336 100644
--- a/runtime/doc/cmdline.txt
+++ b/runtime/doc/cmdline.txt
@@ -1,4 +1,4 @@
-*cmdline.txt* For Vim version 9.1. Last change: 2025 Sep 23
+*cmdline.txt* For Vim version 9.1. Last change: 2025 Sep 24


VIM REFERENCE MANUAL by Bram Moolenaar
@@ -1161,7 +1161,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": >
@@ -1443,7 +1443,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
diff --git a/runtime/doc/eval.txt b/runtime/doc/eval.txt
index 0dc0c52b4..d9819ce74 100644
--- a/runtime/doc/eval.txt
+++ b/runtime/doc/eval.txt
@@ -1,4 +1,4 @@
-*eval.txt* For Vim version 9.1. Last change: 2025 Sep 15
+*eval.txt* For Vim version 9.1. Last change: 2025 Sep 24


VIM REFERENCE MANUAL by Bram Moolenaar
@@ -3138,9 +3138,12 @@ declarations and assignments do not use a command. |vim9-declaration|
set and an environment variable that is empty.

: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 "=".
+ `.=` is not supported with Vim script version 2 and
+ later, see |vimscript-version|.

:let @{reg-name} = {expr1} *:let-register* *:let-@*
Write the result of the expression {expr1} in register
@@ -3157,8 +3160,11 @@ declarations and assignments do not use a command. |vim9-declaration|
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}.
+ `.=` is not supported with Vim script version 2 and
+ later, see |vimscript-version|.

:let &{option-name} = {expr1} *:let-option* *:let-&*
Set option {option-name} to the result of the
@@ -3176,8 +3182,11 @@ declarations and assignments do not use a command. |vim9-declaration|
a terminal key code, there is no error.

:let &{option-name} .= {expr1}
+:let &{option-name} ..= {expr1}
For a string option: Append {expr1} to the value.
Does not insert a comma like |:set+=|.
+ `.=` is not supported with Vim script version 2 and
+ later, see |vimscript-version|.

:let &{option-name} += {expr1}
:let &{option-name} -= {expr1}
@@ -3185,18 +3194,25 @@ declarations and assignments do not use a command. |vim9-declaration|
{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|.
+ `.=` is not supported with Vim script version 2 and
+ later, see |vimscript-version|.

: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|.
+ `.=` is not supported with Vim script version 2 and
+ later, see |vimscript-version|.
+
*E1093* *E1537* *E1538* *E1535*
:let [{name1}, {name2}, ...] = {expr1} *:let-unpack* *E687* *E688*
{expr1} must evaluate to a |List| or a |Tuple|. The
@@ -3217,15 +3233,18 @@ declarations and assignments do not use a command. |vim9-declaration|
:echo x
< The result is [0, 2].

-:let [{name1}, {name2}, ...] .= {expr1}
:let [{name1}, {name2}, ...] += {expr1}
:let [{name1}, {name2}, ...] -= {expr1}
:let [{name1}, {name2}, ...] *= {expr1}
:let [{name1}, {name2}, ...] /= {expr1}
:let [{name1}, {name2}, ...] %= {expr1}
+:let [{name1}, {name2}, ...] .= {expr1}
+:let [{name1}, {name2}, ...] ..= {expr1}
Like above, but append, add, subtract, multiply,
divide, or modulo the value for each |List| or |Tuple|
item.
+ `.=` is not supported with Vim script version 2 and
+ later, see |vimscript-version|.

:let [{name}, ..., ; {lastname}] = {expr1} *E452*
Like |:let-unpack| above, but the |List| or |Tuple|
@@ -3237,11 +3256,14 @@ declarations and assignments do not use a command. |vim9-declaration|
:let [a, b; rest] = ["aval", "bval", 3, 4]
:let [a, b; rest] = ("aval", "bval", 3, 4)
<
-:let [{name}, ..., ; {lastname}] .= {expr1}
:let [{name}, ..., ; {lastname}] += {expr1}
:let [{name}, ..., ; {lastname}] -= {expr1}
+:let [{name}, ..., ; {lastname}] .= {expr1}
+:let [{name}, ..., ; {lastname}] ..= {expr1}
Like above, but append/add/subtract the value for each
|List| item.
+ `.=` is not supported with Vim script version 2 and
+ later, see |vimscript-version|.

*:let=<<* *:let-heredoc*
*E990* *E991* *E172* *E221* *E1145*
@@ -4145,7 +4167,7 @@ exception most recently caught as long it is not finished.

:function! Caught()
: if v:exception != ""
- : echo 'Caught "' . v:exception .. '" in ' .. v:throwpoint
+ : echo 'Caught "' .. v:exception .. '" in ' .. v:throwpoint
: else
: echo 'Nothing caught'
: endif
diff --git a/runtime/doc/filetype.txt b/runtime/doc/filetype.txt
index 4b2cbc84f..4052afbce 100644
--- a/runtime/doc/filetype.txt
+++ b/runtime/doc/filetype.txt
@@ -1,4 +1,4 @@
-*filetype.txt* For Vim version 9.1. Last change: 2025 Aug 10
+*filetype.txt* For Vim version 9.1. Last change: 2025 Sep 24


VIM REFERENCE MANUAL by Bram Moolenaar
@@ -763,7 +763,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.
diff --git a/runtime/doc/pattern.txt b/runtime/doc/pattern.txt
index 51280317a..d72657488 100644
--- a/runtime/doc/pattern.txt
+++ b/runtime/doc/pattern.txt
@@ -1,4 +1,4 @@
-*pattern.txt* For Vim version 9.1. Last change: 2025 Aug 21
+*pattern.txt* For Vim version 9.1. Last change: 2025 Sep 24


VIM REFERENCE MANUAL by Bram Moolenaar
@@ -966,7 +966,7 @@ $ At end of pattern or in front of "\|", "\)" or "
" ('magic' on):
the cursor moves the display isn't updated for this change. An update
is done when using the |CTRL-L| command (the whole screen is updated).
Example, to highlight the line where the cursor currently is: >
- :exe '/\%' . line(".") . 'l'
+ :exe '/\%' .. line(".") .. 'l'
< Alternatively use: >
/\%.l
< When 'hlsearch' is set and you move the cursor around and make changes
diff --git a/runtime/doc/quickfix.txt b/runtime/doc/quickfix.txt
index 02a1a663e..906e98a16 100644
--- a/runtime/doc/quickfix.txt
+++ b/runtime/doc/quickfix.txt
@@ -1,4 +1,4 @@
-*quickfix.txt* For Vim version 9.1. Last change: 2025 Aug 27
+*quickfix.txt* For Vim version 9.1. Last change: 2025 Sep 24


VIM REFERENCE MANUAL by Bram Moolenaar
@@ -1418,7 +1418,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 = {
@@ -1449,7 +1449,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)
@@ -1462,7 +1462,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)
diff --git a/runtime/doc/usr_40.txt b/runtime/doc/usr_40.txt
index b8dfae6b7..a3869fb7c 100644
--- a/runtime/doc/usr_40.txt
+++ b/runtime/doc/usr_40.txt
@@ -1,4 +1,4 @@
-*usr_40.txt* For Vim version 9.1. Last change: 2022 Jun 23
+*usr_40.txt* For Vim version 9.1. Last change: 2025 Sep 24

VIM USER MANUAL - by Bram Moolenaar

@@ -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