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 cdb642e..f339880 100644
--- a/runtime/doc/tags
+++ b/runtime/doc/tags
@@ -10643,6 +10643,7 @@
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-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 593dec7..a0bfd60 100644
--- 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 @@
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 @@
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 5f0ad06..0ebcd06 100644
--- 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 @@
:!{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 @@
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}".