Improve documentation of 'shell-command-dont-erase-buffer'

* doc/emacs/misc.texi (Single Shell):
* lisp/simple.el (shell-command, shell-command-on-region):
Document that non-nil value of 'shell-command-dont-erase-buffer'
affects what is displayed in the echo area after the command.
(Bug#61100)

2 files changed, 12 insertions, 0 deletions

diff --git a/doc/emacs/misc.texi b/doc/emacs/misc.texi
index e2764c34482..80a1b3f55ed 100644
--- a/doc/emacs/misc.texi
+++ b/doc/emacs/misc.texi
@@ -751,6 +751,8 @@ Command Output*"} (@code{shell-command-buffer-name}) buffer (if the
 output is long).  The variables @code{resize-mini-windows} and
 @code{max-mini-window-height} (@pxref{Minibuffer Edit}) control when
 Emacs should consider the output to be too long for the echo area.
+Note that customizing @code{shell-command-dont-erase-buffer},
+described below, can affect what is displayed in the echo area.
 
   For instance, one way to decompress a file named @file{foo.gz} is to
 type @kbd{M-! gunzip foo.gz @key{RET}}.  That shell command normally
@@ -867,6 +869,10 @@ Restores the position of point as it was before inserting the
 shell-command output.
 @end table
 
+Note that if this option is non-@code{nil}, the output shown in the
+echo area could be from more than just the last command, since the
+echo area just displays a portion of the output buffer.
+
 In case the output buffer is not the current buffer, shell command
 output is appended at the end of this buffer.
 
diff --git a/lisp/simple.el b/lisp/simple.el
index aaad3217982..861fe193fb8 100644
--- a/lisp/simple.el
+++ b/lisp/simple.el
@@ -4547,6 +4547,9 @@ If the output is short enough to display in the echo area
 \(determined by the variable `max-mini-window-height' if
 `resize-mini-windows' is non-nil), it is shown there.
 Otherwise, the buffer containing the output is displayed.
+Note that if `shell-command-dont-erase-buffer' is non-nil,
+the echo area could display more than just the output of the
+last command.
 
 If there is output and an error, and you did not specify \"insert it
 in the current buffer\", a message about the error goes at the end
@@ -4829,6 +4832,9 @@ If the output is short enough to display in the echo area
 `resize-mini-windows' is non-nil), it is shown there.
 Otherwise it is displayed in the buffer named by `shell-command-buffer-name'.
 The output is available in that buffer in both cases.
+Note that if `shell-command-dont-erase-buffer' is non-nil,
+the echo area could display more than just the output of the
+last command.
 
 If there is output and an error, a message about the error
 appears at the end of the output.