master 2ed502d: Add constants for shell command output buffer names

[Lars Ingebrigtsen]

branch: master
commit 2ed502d2a76e93ecd5366a6ec3926894e4fbe827
Author: Tino Calancha <tino.calancha@gmail.com>
Commit: Lars Ingebrigtsen <larsi@gnus.org>

    Add constants for shell command output buffer names
    
    Buffers `*Shell Command Output*' and `*Async Shell Command*'
    have been around since a long time; used across several libraries,
    they are de facto output buffers for shell commands.
    
    * lisp/simple.el (shell-command-buffer-name)
    (shell-command-buffer-name-async): New variables.
    * lisp/dired-aux.el
    * lisp/gnus/gnus-sum.el
    * lisp/gnus/gnus-win.el
    * lisp/ibuf-ext.el
    * lisp/net/tramp.el: Use them.
    
    * etc/NEWS (Changes in Emacs 28.1): Announce this change.
    
    * doc/emacs/misc.texi (Single Shell)
    * doc/misc/tramp.texi (Remote processes):
    Update manual (bug#39138).
---
 doc/emacs/misc.texi   | 19 +++++++++++--------
 doc/misc/tramp.texi   |  2 +-
 etc/NEWS              |  5 +++++
 lisp/dired-aux.el     |  6 +++---
 lisp/gnus/gnus-sum.el |  2 +-
 lisp/gnus/gnus-win.el |  2 +-
 lisp/ibuf-ext.el      |  6 +++---
 lisp/net/tramp.el     |  4 ++--
 lisp/simple.el        | 37 +++++++++++++++++++++++--------------
 9 files changed, 50 insertions(+), 33 deletions(-)

diff --git a/doc/emacs/misc.texi b/doc/emacs/misc.texi
index e7547eb..cb9fc61 100644
--- a/doc/emacs/misc.texi
+++ b/doc/emacs/misc.texi
@@ -724,13 +724,15 @@ See the Eshell Info manual, which is distributed with 
Emacs.
 
 @kindex M-!
 @findex shell-command
+@vindex shell-command-buffer-name
   @kbd{M-!} (@code{shell-command}) reads a line of text using the
 minibuffer and executes it as a shell command, in a subshell made just
 for that command.  Standard input for the command comes from the null
 device.  If the shell command produces any output, the output appears
-either in the echo area (if it is short), or in an Emacs buffer named
-@file{*Shell Command Output*}, displayed in another window (if the
-output is long).  The variables @code{resize-mini-windows} and
+either in the echo area (if it is short), or in an Emacs buffer,
+displayed in another window (if the output is long).  The name of
+this buffer is taken from the constant @code{shell-command-buffer-name}.
+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.
 
@@ -758,15 +760,16 @@ which is impossible to ignore.
 
 @kindex M-&
 @findex async-shell-command
+@vindex shell-command-buffer-name-async
   A shell command that ends in @samp{&} is executed
 @dfn{asynchronously}, and you can continue to use Emacs as it runs.
 You can also type @kbd{M-&} (@code{async-shell-command}) to execute a
 shell command asynchronously; this is exactly like calling @kbd{M-!}
 with a trailing @samp{&}, except that you do not need the @samp{&}.
-The default output buffer for asynchronous shell commands is named
-@samp{*Async Shell Command*}.  Emacs inserts the output into this
-buffer as it comes in, whether or not the buffer is visible in a
-window.
+The constant @code{shell-command-buffer-name-async} stores the name
+of the default output buffer for asynchronous shell commands.
+Emacs inserts the output into this buffer as it comes in,
+whether or not the buffer is visible in a window.
 
 @vindex async-shell-command-buffer
   If you want to run more than one asynchronous shell command at the
@@ -804,7 +807,7 @@ old region and replaces it with the output from the shell 
command.
 see what keys are in the buffer.  If the buffer contains a GnuPG key,
 type @kbd{C-x h M-| gpg @key{RET}} to feed the entire buffer contents
 to @command{gpg}.  This will output the list of keys to the
-@file{*Shell Command Output*} buffer.
+buffer named @code{shell-command-buffer-name}.
 
 @vindex shell-file-name
   The above commands use the shell specified by the variable
diff --git a/doc/misc/tramp.texi b/doc/misc/tramp.texi
index 56cd220..ae6fe3d 100644
--- a/doc/misc/tramp.texi
+++ b/doc/misc/tramp.texi
@@ -3379,7 +3379,7 @@ host.  Example:
 @end example
 
 @command{tail} command outputs continuously to the local buffer,
-@file{*Async Shell Command*}
+named @code{shell-command-buffer-name-async}
 
 @kbd{M-x auto-revert-tail-mode @key{RET}} runs similarly showing
 continuous output.
diff --git a/etc/NEWS b/etc/NEWS
index 9dffd0f..1e4fe47 100644
--- a/etc/NEWS
+++ b/etc/NEWS
@@ -80,6 +80,11 @@ useful on systems such as FreeBSD which ships only with 
"etc/termcap".
 
 * Changes in Emacs 28.1
 
++++
+** The new constants 'shell-command-buffer-name' and
+'shell-command-buffer-name-async' store the default buffer names
+for the output of shell commands.
+
 ** Support for '(box . SIZE)' 'cursor-type'.
 By default, 'box' cursor always has a filled box shape.  But if you
 specify 'cursor-type' to be '(box . SIZE)', the cursor becomes a hollow
diff --git a/lisp/dired-aux.el b/lisp/dired-aux.el
index 6587d03..84d8c36 100644
--- a/lisp/dired-aux.el
+++ b/lisp/dired-aux.el
@@ -688,7 +688,7 @@ are executed in the background on each file sequentially 
waiting
 for each command to terminate before running the next command.
 In shell syntax this means separating the individual commands with `;'.
 
-The output appears in the buffer `*Async Shell Command*'."
+The output appears in the buffer `shell-command-buffer-name-async'."
   (interactive
    (let ((files (dired-get-marked-files t current-prefix-arg nil nil t)))
      (list
@@ -727,7 +727,7 @@ it, write `*\"\"' in place of just `*'.  This is equivalent 
to just
 
 If COMMAND ends in `&', `;', or `;&', it is executed in the
 background asynchronously, and the output appears in the buffer
-`*Async Shell Command*'.  When operating on multiple files and COMMAND
+`shell-command-buffer-name-async'.  When operating on multiple files and 
COMMAND
 ends in `&', the shell command is executed on each file in parallel.
 However, when COMMAND ends in `;' or `;&' then commands are executed
 in the background on each file sequentially waiting for each command
@@ -735,7 +735,7 @@ to terminate before running the next command.  You can also 
use
 `dired-do-async-shell-command' that automatically adds `&'.
 
 Otherwise, COMMAND is executed synchronously, and the output
-appears in the buffer `*Shell Command Output*'.
+appears in the buffer `shell-command-buffer-name'.
 
 This feature does not try to redisplay Dired buffers afterward, as
 there's no telling what files COMMAND may have changed.
diff --git a/lisp/gnus/gnus-sum.el b/lisp/gnus/gnus-sum.el
index 719498a..4363860 100644
--- a/lisp/gnus/gnus-sum.el
+++ b/lisp/gnus/gnus-sum.el
@@ -12284,7 +12284,7 @@ no matter what the properties `:decode' and `:headers' 
are."
   (interactive (gnus-interactive "P\ny"))
   (require 'gnus-art)
   (let* ((articles (gnus-summary-work-articles n))
-        (result-buffer "*Shell Command Output*")
+        (result-buffer shell-command-buffer-name)
         (all-headers (not (memq sym '(nil r))))
         (gnus-save-all-headers (or all-headers gnus-save-all-headers))
         (raw (eq sym 'r))
diff --git a/lisp/gnus/gnus-win.el b/lisp/gnus/gnus-win.el
index 36b2835..baa3146 100644
--- a/lisp/gnus/gnus-win.el
+++ b/lisp/gnus/gnus-win.el
@@ -142,7 +142,7 @@ used to display Gnus windows."
     (pipe
      (vertical 1.0
               (summary 0.25 point)
-              ("*Shell Command Output*" 1.0)))
+              (shell-command-buffer-name 1.0)))
     (bug
      (vertical 1.0
               (if gnus-bug-create-help-buffer '("*Gnus Help Bug*" 0.5))
diff --git a/lisp/ibuf-ext.el b/lisp/ibuf-ext.el
index bfb9787..c9ca1f8 100644
--- a/lisp/ibuf-ext.el
+++ b/lisp/ibuf-ext.el
@@ -504,7 +504,7 @@ format.  See `ibuffer-update-saved-filters-format' and
   (ibuffer-forward-line 0))
 
 (defun ibuffer--maybe-erase-shell-cmd-output ()
-  (let ((buf (get-buffer "*Shell Command Output*")))
+  (let ((buf (get-buffer shell-command-buffer-name)))
     (when (and (buffer-live-p buf)
                (not shell-command-dont-erase-buffer)
                (not (zerop (buffer-size buf))))
@@ -517,7 +517,7 @@ format.  See `ibuffer-update-saved-filters-format' and
    :opstring "Shell command executed on"
    :before (ibuffer--maybe-erase-shell-cmd-output)
    :modifier-p nil)
-  (let ((out-buf (get-buffer-create "*Shell Command Output*")))
+  (let ((out-buf (get-buffer-create shell-command-buffer-name)))
     (with-current-buffer out-buf (goto-char (point-max)))
     (call-shell-region (point-min) (point-max)
                        command nil out-buf)))
@@ -542,7 +542,7 @@ format.  See `ibuffer-update-saved-filters-format' and
    :modifier-p nil)
   (let ((file (and (not (buffer-modified-p))
                    buffer-file-name))
-        (out-buf (get-buffer-create "*Shell Command Output*")))
+        (out-buf (get-buffer-create shell-command-buffer-name)))
     (unless (and file (file-exists-p file))
       (setq file
             (make-temp-file
diff --git a/lisp/net/tramp.el b/lisp/net/tramp.el
index d1b2935..fdf26f6 100644
--- a/lisp/net/tramp.el
+++ b/lisp/net/tramp.el
@@ -3815,8 +3815,8 @@ support symbolic links."
            (current-buffer))
           (t (get-buffer-create
               (if asynchronous
-                  "*Async Shell Command*"
-                "*Shell Command Output*")))))
+                  shell-command-buffer-name-async
+                shell-command-buffer-name)))))
         (error-buffer
          (cond
           ((bufferp error-buffer) error-buffer)
diff --git a/lisp/simple.el b/lisp/simple.el
index 2f92238..6c9584a 100644
--- a/lisp/simple.el
+++ b/lisp/simple.el
@@ -3369,6 +3369,14 @@ which is defined in the `warnings' library.\n")
     (setq buffer-undo-list nil)
     t))
 
+;;;; Shell commands
+
+(defconst shell-command-buffer-name "*Shell Command Output*"
+  "Name of the output buffer for shell commands.")
+
+(defconst shell-command-buffer-name-async "*Async Shell Command*"
+  "Name of the output buffer for asynchronous shell commands.")
+
 (defvar shell-command-history nil
   "History list for some commands that read shell commands.
 
@@ -3433,7 +3441,7 @@ to `shell-command-history'."
 (defcustom async-shell-command-buffer 'confirm-new-buffer
   "What to do when the output buffer is used by another shell command.
 This option specifies how to resolve the conflict where a new command
-wants to direct its output to the buffer `*Async Shell Command*',
+wants to direct its output to the buffer `shell-command-buffer-name-async',
 but this buffer is already taken by another running shell command.
 
 The value `confirm-kill-process' is used to ask for confirmation before
@@ -3585,14 +3593,14 @@ whose `car' is BUFFER."
 Like `shell-command', but adds `&' at the end of COMMAND
 to execute it asynchronously.
 
-The output appears in the buffer `*Async Shell Command*'.
+The output appears in the buffer `shell-command-buffer-name-async'.
 That buffer is in shell mode.
 
 You can configure `async-shell-command-buffer' to specify what to do
-when the `*Async Shell Command*' buffer is already taken by another
+when the `shell-command-buffer-name-async' buffer is already taken by another
 running shell command.  To run COMMAND without displaying the output
 in a window you can configure `display-buffer-alist' to use the action
-`display-buffer-no-window' for the buffer `*Async Shell Command*'.
+`display-buffer-no-window' for the buffer `shell-command-buffer-name-async'.
 
 In Elisp, you will often be better served by calling `start-process'
 directly, since it offers more control and does not impose the use of
@@ -3628,12 +3636,12 @@ If `shell-command-prompt-show-cwd' is non-nil, show the 
current
 directory in the prompt.
 
 If COMMAND ends in `&', execute it asynchronously.
-The output appears in the buffer `*Async Shell Command*'.
+The output appears in the buffer `shell-command-buffer-name-async'.
 That buffer is in shell mode.  You can also use
 `async-shell-command' that automatically adds `&'.
 
 Otherwise, COMMAND is executed synchronously.  The output appears in
-the buffer `*Shell Command Output*'.  If the output is short enough to
+the buffer `shell-command-buffer-name'.  If the output is short enough to
 display in the echo area (which is determined by the variables
 `resize-mini-windows' and `max-mini-window-height'), it is shown
 there, but it is nonetheless available in buffer `*Shell Command
@@ -3756,7 +3764,7 @@ impose the use of a shell (with its need to quote 
arguments)."
          (if (string-match "[ \t]*&[ \t]*\\'" command)
              ;; Command ending with ampersand means asynchronous.
               (let* ((buffer (get-buffer-create
-                              (or output-buffer "*Async Shell Command*")))
+                              (or output-buffer 
shell-command-buffer-name-async)))
                      (bname (buffer-name buffer))
                      (proc (get-buffer-process buffer))
                      (directory default-directory))
@@ -3908,7 +3916,7 @@ and are used only if a pop-up buffer is displayed."
                                      error-buffer display-error-buffer
                                      region-noncontiguous-p)
   "Execute string COMMAND in inferior shell with region as input.
-Normally display output (if any) in temp buffer `*Shell Command Output*';
+Normally display output (if any) in temp buffer `shell-command-buffer-name';
 Prefix arg means replace the region with it.  Return the exit code of
 COMMAND.
 
@@ -3927,7 +3935,7 @@ in the echo area or in a buffer.
 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 it is displayed in the buffer `*Shell Command Output*'.
+Otherwise it is displayed in the buffer `shell-command-buffer-name'.
 The output is available in that buffer in both cases.
 
 If there is output and an error, a message about the error
@@ -3937,7 +3945,7 @@ Optional fourth arg OUTPUT-BUFFER specifies where to put 
the
 command's output.  If the value is a buffer or buffer name,
 erase that buffer and insert the output there; a non-nil value of
 `shell-command-dont-erase-buffer' prevent to erase the buffer.
-If the value is nil, use the buffer `*Shell Command Output*'.
+If the value is nil, use the buffer `shell-command-buffer-name'.
 Any other non-nil value means to insert the output in the
 current buffer after START.
 
@@ -4006,7 +4014,7 @@ characters."
             (funcall region-insert-function output))
            (t
             (let ((buffer (get-buffer-create
-                           (or output-buffer "*Shell Command Output*"))))
+                           (or output-buffer shell-command-buffer-name))))
               (with-current-buffer buffer
                 (erase-buffer)
                 (funcall region-insert-function output))
@@ -4025,7 +4033,7 @@ characters."
                                            (list t error-file)
                                          t)))
             ;; It is rude to delete a buffer that the command is not using.
-            ;; (let ((shell-buffer (get-buffer "*Shell Command Output*")))
+            ;; (let ((shell-buffer (get-buffer shell-command-buffer-name)))
             ;;   (and shell-buffer (not (eq shell-buffer (current-buffer)))
             ;;          (kill-buffer shell-buffer)))
             ;; Don't muck with mark unless REPLACE says we should.
@@ -4033,12 +4041,13 @@ characters."
         ;; No prefix argument: put the output in a temp buffer,
         ;; replacing its entire contents.
         (let ((buffer (get-buffer-create
-                       (or output-buffer "*Shell Command Output*"))))
+                       (or output-buffer shell-command-buffer-name))))
           (set-buffer-major-mode buffer) ; Enable globalized modes (bug#38111)
           (unwind-protect
               (if (and (eq buffer (current-buffer))
                        (or (memq shell-command-dont-erase-buffer '(nil erase))
-                           (and (not (eq buffer (get-buffer "*Shell Command 
Output*")))
+                           (and (not (eq buffer (get-buffer
+                                                 shell-command-buffer-name)))
                                 (not (region-active-p)))))
                   ;; If the input is the same buffer as the output,
                   ;; delete everything but the specified region,