runtime(doc): clarify :silent usage for system()/systemlist()

When system() or systemlist() is called without :silent from a
statusline expression, autocommand, or timer callback, the terminal
is temporarily set to cooked mode, which re-enables ECHO on the tty.
If a terminal response (e.g. DECRPM for cursor blink mode) arrives
during this window, the tty driver echoes it to the screen, leaving
stray characters that require CTRL-L to remove.

This behavior was intentionally addressed in patch 7.4.427 by
skipping cooked mode when :silent is prepended.  However, the
documentation only mentioned this for system() and did not cover
systemlist() at all.  The guidance to use :silent in non-interactive
contexts (statusline, autocommands, timers) was also not explicit.

closes #19691

Signed-off-by: Yasuhiro Matsumoto <mattn.jp@gmail.com>
Signed-off-by: Christian Brabandt <cb@256bit.org>

diff --git a/runtime/doc/builtin.txt b/runtime/doc/builtin.txt
index 45072ab16c1e8cec01aa010ad05f28a7da9ac45d..21dc56c33d7452698266e6dd49549900c5ee3a4e 100644 (file)
--- a/runtime/doc/builtin.txt
+++ b/runtime/doc/builtin.txt
@@ -1,4 +1,4 @@
-*builtin.txt*  For Vim version 9.2.  Last change: 2026 Mar 13
+*builtin.txt*  For Vim version 9.2.  Last change: 2026 Mar 15
 
 
                  VIM REFERENCE MANUAL    by Bram Moolenaar
@@ -11713,7 +11713,11 @@ system({expr} [, {input}])                             *system()* *E677*
                When prepended by |:silent| the terminal will not be set to
                cooked mode.  This is meant to be used for commands that do
                not need the user to type.  It avoids stray characters showing
-               up on the screen which require |CTRL-L| to remove. >
+               up on the screen which require |CTRL-L| to remove.
+               When calling system() from a |statusline| expression, an
+               |autocommand| or a |timer| callback, you should use |:silent|
+               to avoid terminal responses (e.g. from cursor style queries)
+               being echoed on the screen. >
                        :silent let f = system('ls *.vim')
 <
                Note: Use |shellescape()| or |::S| with |expand()| or
@@ -11771,6 +11775,11 @@ systemlist({expr} [, {input}])                         *systemlist()*
 <
                Returns an empty string on error.
 
+               Like |system()|, prepend |:silent| when the command does not
+               need user interaction and is called from a |statusline|
+               expression, an |autocommand| or a |timer| callback.  See
+               |system()| for details.
+
                Can also be used as a |method|: >
                        :echo GetCmd()->systemlist()
 <