Fix shell-command-dont-erase-buffer feature

* lisp/simple.el (shell-command-dont-erase-buffer):
The default, nil, is backward compatible, i.e. it erases the buffer
only if the output buffer is not the current one; the new value 'erase
always erases the output buffer.
Update docstring.

(shell-command-save-pos-or-erase):
Add optional arg output-to-current-buffer.
Rename it so that it's not internal.  All callers updated.

(shell-command-set-point-after-cmd): Rename it so that it's not internal.
All callers updated.
Adjust it to cover a side case.

(shell-command): Adjust logic to match the specification (Bug#39067).
Enable the feature when the output buffer is the current one.

(shell-command-on-region): Little tweak to follow
`shell-command-dont-erase-buffer' specification.

* test/lisp/simple-tests.el (with-shell-command-dont-erase-buffer):
Add helper macro.
(simple-tests-shell-command-39067)
(simple-tests-shell-command-dont-erase-buffer): Add tests.

* doc/emacs/misc.texi (Single Shell): Update manual.

* etc/NEWS (Single shell commands): Announce the change.

1 files changed, 8 insertions, 6 deletions

diff --git a/doc/emacs/misc.texi b/doc/emacs/misc.texi
index ab3318c4a24..6b95b12a846 100644
--- a/doc/emacs/misc.texi
+++ b/doc/emacs/misc.texi
@@ -826,12 +826,14 @@ the output buffer.  But if you change the value of the variable
 inserted into a buffer of that name.
 
 @vindex shell-command-dont-erase-buffer
-  By default, the output buffer is erased between shell commands.
-If you change the value of the variable
-@code{shell-command-dont-erase-buffer} to a non-@code{nil} value,
-the output buffer is not erased.  This variable also controls where to
-set the point in the output buffer after the command completes; see the
-documentation of the variable for details.
+  By default, the output buffer is erased between shell commands, except
+when the output goes to the current buffer.  If you change the value
+of the option @code{shell-command-dont-erase-buffer} to @code{erase},
+then the output buffer is always erased.  Any other non-@code{nil}
+value prevents to erase the output buffer.
+
+This option also controls where to set the point in the output buffer
+after the command completes; see the documentation of the option for details.
 
 @node Interactive Shell
 @subsection Interactive Subshell