master ec32338: Fix recently added documentation bits

[Eli Zaretskii]

branch: master
commit ec323389e75303c469b68a54b02bcd7123e2d60b
Author: Eli Zaretskii <eliz@gnu.org>
Commit: Eli Zaretskii <eliz@gnu.org>

    Fix recently added documentation bits
    
    * lisp/simple.el (async-shell-command-buffer)
    (async-shell-command, shell-command, shell-command-on-region):
    * lisp/dired-aux.el (dired-do-async-shell-command)
    (dired-do-shell-command):
    * doc/misc/tramp.texi (Remote processes):
    * doc/emacs/misc.texi (Single Shell):
    * etc/NEWS: Fix wording and punctuation of recently added
    documentation.
---
 doc/emacs/misc.texi |  2 +-
 doc/misc/tramp.texi |  4 ++--
 etc/NEWS            | 15 +++++++++------
 lisp/dired-aux.el   | 18 +++++++++---------
 lisp/simple.el      | 49 ++++++++++++++++++++++++++++---------------------
 5 files changed, 49 insertions(+), 39 deletions(-)

diff --git a/doc/emacs/misc.texi b/doc/emacs/misc.texi
index cb9fc61..39aae87 100644
--- a/doc/emacs/misc.texi
+++ b/doc/emacs/misc.texi
@@ -807,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
-buffer named @code{shell-command-buffer-name}.
+buffer whose name is the value of @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 ae6fe3d..23221b6 100644
--- a/doc/misc/tramp.texi
+++ b/doc/misc/tramp.texi
@@ -3378,8 +3378,8 @@ host.  Example:
 @end group
 @end example
 
-@command{tail} command outputs continuously to the local buffer,
-named @code{shell-command-buffer-name-async}
+@command{tail} command outputs continuously to the local buffer whose
+name is the value of the variable @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 8118272..e3d7ff0 100644
--- a/etc/NEWS
+++ b/etc/NEWS
@@ -81,9 +81,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
+** New variables that hold default buffer names for shell output.
+The new constants 'shell-command-buffer-name' and
 'shell-command-buffer-name-async' store the default buffer names
-for the output of shell commands.
+for the output of, respectively, synchronous and async shell
+commands.
 
 ** Support for '(box . SIZE)' 'cursor-type'.
 By default, 'box' cursor always has a filled box shape.  But if you
@@ -201,6 +203,7 @@ as a data list rather than as a piece of code.
 
 ** Calendar
 
++++
 *** New variable 'calendar-use-numeric-time-zones' to use numeric time zones.
 If non-nil, functions that display time zones (like the 'S' command in
 calendar mode that displays the sunrise time) will display time zones
@@ -233,12 +236,12 @@ their 'default-directory' under VC.
 Bookmark locations can refer to VC directory buffers.
 
 ---
-*** New user option 'vc-hg-create-bookmark' controls whether a bookmark
-or branch will be created when you invoke 'C-u C-x v s' ('vc-create-tag').
+*** New user option 'vc-hg-create-bookmark'.
+It controls whether a bookmark or branch will be created when you
+invoke 'C-u C-x v s' ('vc-create-tag').
 
 ---
-*** 'vc-hg' now uses 'hg summary' command to populate extra 'vc-dir'
-headers.
+*** 'vc-hg' now uses 'hg summary' to populate extra 'vc-dir' headers.
 
 
 ** Gnus
diff --git a/lisp/dired-aux.el b/lisp/dired-aux.el
index 84d8c36..69b1753 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 `shell-command-buffer-name-async'."
+The output appears in the buffer named by `shell-command-buffer-name-async'."
   (interactive
    (let ((files (dired-get-marked-files t current-prefix-arg nil nil t)))
      (list
@@ -726,16 +726,16 @@ it, write `*\"\"' in place of just `*'.  This is 
equivalent to just
 `*' in the shell, but avoids Dired's special handling.
 
 If COMMAND ends in `&', `;', or `;&', it is executed in the
-background asynchronously, and the output appears in the buffer
-`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
-to terminate before running the next command.  You can also use
-`dired-do-async-shell-command' that automatically adds `&'.
+background asynchronously, and the output appears in the buffer named
+by `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 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-buffer-name'.
+appears in the buffer named by `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/simple.el b/lisp/simple.el
index 6c9584a..4a774bc 100644
--- a/lisp/simple.el
+++ b/lisp/simple.el
@@ -3441,8 +3441,9 @@ 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 `shell-command-buffer-name-async',
-but this buffer is already taken by another running shell command.
+wants to direct its output to the buffer whose name is stored
+in `shell-command-buffer-name-async', but that buffer is already
+taken by another running shell command.
 
 The value `confirm-kill-process' is used to ask for confirmation before
 killing the already running process and running a new process
@@ -3593,14 +3594,18 @@ whose `car' is BUFFER."
 Like `shell-command', but adds `&' at the end of COMMAND
 to execute it asynchronously.
 
-The output appears in the buffer `shell-command-buffer-name-async'.
-That buffer is in shell mode.
+The output appears in the buffer whose name is stored in the
+variable `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 `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 `shell-command-buffer-name-async'.
+when the buffer specified by `shell-command-buffer-name-async' 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 given by
+`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
@@ -3636,16 +3641,18 @@ 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 `shell-command-buffer-name-async'.
-That buffer is in shell mode.  You can also use
-`async-shell-command' that automatically adds `&'.
+The output appears in the buffer whose name is specified
+by `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-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
-Output*' even though that buffer is not automatically displayed.
+the buffer named by `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 named by
+`shell-command-buffer-name' even though that buffer is not
+automatically displayed.
 
 To specify a coding system for converting non-ASCII characters
 in the shell command output, use \\[universal-coding-system-argument] \
@@ -3916,9 +3923,9 @@ 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-buffer-name';
-Prefix arg means replace the region with it.  Return the exit code of
-COMMAND.
+Normally display output (if any) in temp buffer specified
+by `shell-command-buffer-name'; prefix arg means replace the region
+with it.  Return the exit code of COMMAND.
 
 To specify a coding system for converting non-ASCII characters
 in the input and output to the shell command, use 
\\[universal-coding-system-argument]
@@ -3935,7 +3942,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-buffer-name'.
+Otherwise it is displayed in the buffer named by `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
@@ -3945,7 +3952,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-buffer-name'.
+If the value is nil, use the buffer specified by `shell-command-buffer-name'.
 Any other non-nil value means to insert the output in the
 current buffer after START.