runtime(doc): clarify the use of filters and external commands

related: #16044

Signed-off-by: Christian Brabandt <cb@256bit.org>

diff --git a/runtime/doc/change.txt b/runtime/doc/change.txt
index 785f4accae0453398ee6715758bf98388134b06f..e4366551d68e199600ffe94c113e2bcc2b200d8f 100644 (file)
--- a/runtime/doc/change.txt
+++ b/runtime/doc/change.txt
@@ -1,4 +1,4 @@
-*change.txt*    For Vim version 9.1.  Last change: 2024 Oct 07
+*change.txt*    For Vim version 9.1.  Last change: 2024 Nov 12
 
 
                  VIM REFERENCE MANUAL    by Bram Moolenaar
@@ -586,6 +586,8 @@ comment (starting with '"') after the `:!` command.
                        program {filter} (for {Visual} see |Visual-mode|).
 
 :{range}![!]{filter} [!][arg]                          *:range!*
+                       For executing external commands see |:!|
+
                        Filter {range} lines through the external program
                        {filter}.  Vim replaces the optional bangs with the
                        latest given command and appends the optional [arg].

diff --git a/runtime/doc/usr_10.txt b/runtime/doc/usr_10.txt
index 4ffd235562bac9733b393c2748673249762f313d..29ccd9f887943f6e9acec30d29c7f9e2163089c0 100644 (file)
--- a/runtime/doc/usr_10.txt
+++ b/runtime/doc/usr_10.txt
@@ -1,4 +1,4 @@
-*usr_10.txt*   For Vim version 9.1.  Last change: 2019 Nov 22
+*usr_10.txt*   For Vim version 9.1.  Last change: 2024 Nov 12
 
                     VIM USER MANUAL - by Bram Moolenaar
 
@@ -736,6 +736,11 @@ The "!!" command filters the current line through a filter.  In Unix the "date"
 command prints the current time and date.  "!!date<Enter>" replaces the current
 line with the output of "date".  This is useful to add a timestamp to a file.
 
+Note: There is a difference between "!cmd" (e.g. using it without any file
+range) and "{range}!cmd".  While the former will simply execute the external
+command and Vim will show the output, the latter will filter {range}lines
+through the filter and replace that range by the result of the filter command.
+See |:!| and |:range!| for details.
 
 WHEN IT DOESN'T WORK
 

diff --git a/runtime/doc/various.txt b/runtime/doc/various.txt
index 4c267941d76eb7b804e5ea88fa06379e884eebe6..5f0ad0635ce7d5e9f4bfd5dfe83c5c2f433d824d 100644 (file)
--- a/runtime/doc/various.txt
+++ b/runtime/doc/various.txt
@@ -1,4 +1,4 @@
-*various.txt*   For Vim version 9.1.  Last change: 2024 Oct 05
+*various.txt*   For Vim version 9.1.  Last change: 2024 Nov 12
 
 
                  VIM REFERENCE MANUAL    by Bram Moolenaar
@@ -254,7 +254,8 @@ g8                  Print the hex values of the bytes used in the
 
                                                        *:!cmd* *:!*
 :!{cmd}                        Execute {cmd} with the shell.  See also the 'shell'
-                       and 'shelltype' option.
+                       and 'shelltype' option.  For the filter command, see
+                       |:range!|.
                                                        *E34*
                        Any '!' in {cmd} is replaced with the previous
                        external command (see also 'cpoptions').  But not when