runtime(doc): Expand docs on :! vs. :term

fixes: #16071
closes: #16089

Signed-off-by: matveyt <matthewtarasov@yandex.ru>
Signed-off-by: Christian Brabandt <cb@256bit.org>

diff --git a/runtime/doc/tags b/runtime/doc/tags
index cdb642e3dc243d82fce1310713a7f46c9506eda7..f33988020841ddc2e575bee6e14144a38592a333 100644 (file)
--- a/runtime/doc/tags
+++ b/runtime/doc/tags
@@ -10643,6 +10643,7 @@ template        autocmd.txt     /*template*
 tempname()     builtin.txt     /*tempname()*
 term++close    terminal.txt    /*term++close*
 term++open     terminal.txt    /*term++open*
+term++shell    terminal.txt    /*term++shell*
 term-dependent-settings        term.txt        /*term-dependent-settings*
 term-list      syntax.txt      /*term-list*
 term.txt       term.txt        /*term.txt*
@@ -10723,6 +10724,7 @@ terminal-job-index      index.txt       /*terminal-job-index*
 terminal-key-codes     term.txt        /*terminal-key-codes*
 terminal-mouse term.txt        /*terminal-mouse*
 terminal-ms-windows    terminal.txt    /*terminal-ms-windows*
+terminal-nospecial     terminal.txt    /*terminal-nospecial*
 terminal-options       term.txt        /*terminal-options*
 terminal-output-codes  term.txt        /*terminal-output-codes*
 terminal-resizing      terminal.txt    /*terminal-resizing*

diff --git a/runtime/doc/terminal.txt b/runtime/doc/terminal.txt
index 593dec77c7b00fde372c8d7accd4cb6903b676e0..a0bfd6034ee5ce170c1f287875c4c271a964f1c8 100644 (file)
--- a/runtime/doc/terminal.txt
+++ b/runtime/doc/terminal.txt
@@ -1,4 +1,4 @@
-*terminal.txt* For Vim version 9.1.  Last change: 2024 Nov 19
+*terminal.txt* For Vim version 9.1.  Last change: 2024 Nov 23
 
 
                  VIM REFERENCE MANUAL    by Bram Moolenaar
@@ -197,6 +197,13 @@ Command syntax ~
                        if [command] is NONE no job is started, the pty of the
                        terminal can be used by a command like gdb.
 
+                                                       *terminal-nospecial*
+                       Vim itself only recognizes |cmdline-special|
+                       characters inside [command].  Everything else will be
+                       passed untouched.  When needed to expand wildcards,
+                       environment variables or other shell specials consider
+                       |term++shell| option.
+
                        If [command] is missing the default behavior is to
                        close the terminal when the shell exits.  This can be
                        changed with the ++noclose argument.
@@ -241,10 +248,16 @@ Command syntax ~
                                        no window will be used.
                        ++norestore     Do not include this terminal window
                                        in a session file.
+
+                                               *term++shell*
                        ++shell         Instead of executing {command}
                                        directly, use a shell, like with
                                        `:!command`             *E279*
                                        {only works on Unix and MS-Windows}
+                                       The resulting command will look like
+                                       'shell' 'shellcmdflag' [command]
+                                       Other options related to `:!command`
+                                       have no effect.
                        ++kill={how}    When trying to close the terminal
                                        window kill the job with {how}.  See
                                        |term_setkill()| for the values.

diff --git a/runtime/doc/various.txt b/runtime/doc/various.txt
index 5f0ad0635ce7d5e9f4bfd5dfe83c5c2f433d824d..0ebcd06841487cdac9070b9ad448a3413ea6aa60 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 Nov 12
+*various.txt*   For Vim version 9.1.  Last change: 2024 Nov 23
 
 
                  VIM REFERENCE MANUAL    by Bram Moolenaar
@@ -256,6 +256,17 @@ g8                 Print the hex values of the bytes used in the
 :!{cmd}                        Execute {cmd} with the shell.  See also the 'shell'
                        and 'shelltype' option.  For the filter command, see
                        |:range!|.
+
+                       Vim builds command line using options 'shell', 'shcf',
+                       'sxq' and 'shq' in the following order:
+                       `&sh &shcf &sxq &shq {cmd} &shq &sxq`
+                       So setting both 'sxq' and 'shq' is possible but rarely
+                       useful.  Additional escaping inside `{cmd}` may also
+                       be due to 'sxe' option.
+
+                       Also, all |cmdline-special| characters in {cmd} are
+                       replaced by Vim before passing them to shell.
+
                                                        *E34*
                        Any '!' in {cmd} is replaced with the previous
                        external command (see also 'cpoptions').  But not when
@@ -306,7 +317,10 @@ g8                 Print the hex values of the bytes used in the
                        CTRL-L or ":redraw!" if the command did display
                        something.  However, this depends on what the |t_ti|
                        and |t_te| termcap entries are set to.
-                       Also see |shell-window|.
+
+                       Hint: use |:terminal| command if you want to run {cmd}
+                       in Vim window.  `:term ++shell ++close {cmd}` could
+                       serve as close approximation to what `:!{cmd}` does.
 
                                                        *:!!*
 :!!                    Repeat last ":!{cmd}".