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 <dougkearns@gmail.com>
Signed-off-by: Christian Brabandt <cb@256bit.org>

diff --git a/runtime/doc/builtin.txt b/runtime/doc/builtin.txt
index 2e9535e650d11160cdee9e3b45ea17f2a6ba191b..54dfb27c9a126c29161d19ea059694291dcce204 100644 (file)
--- 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 f5a54b784d833aaa9dc9a5a248a6f6114e8d3898..88a4e13368963bade62527109773004463c12503 100644 (file)
--- 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 0dc0c52b4c5a81519cb76145577490de8d5dab3a..d9819ce74ec3f285dd1b9534793d27c0ecff8ae3 100644 (file)
--- 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 4b2cbc84f9402955d2e8ffad62a0d4b9d0512158..4052afbce1f7428be0ca60af683d88b335c1e4e4 100644 (file)
--- 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 51280317abb4ea17e3924bd25558b350a70b2aa5..d726574885dc41b97f1d5a171e33f9a92ac649cd 100644 (file)
--- 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 "\n" ('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 02a1a663e3afa3ef6426896559f10ec3a536fd2a..906e98a16fa547550afd184fed31a236b17c5a5c 100644 (file)
--- 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 b8dfae6b7828257ee897517390d83bcf11a086df..a3869fb7cfe8554350be35514e36295d7c22efb7 100644 (file)
--- 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