From: Eli Zaretskii Date: Sun, 9 Aug 2020 16:13:53 +0000 (+0300) Subject: Fix recently added documentation bits X-Git-Tag: emacs-28.0.90~6725 X-Git-Url: http://git.eshelyaron.com/gitweb/?a=commitdiff_plain;h=ec323389e75303c469b68a54b02bcd7123e2d60b;p=emacs.git 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. --- diff --git a/doc/emacs/misc.texi b/doc/emacs/misc.texi index cb9fc61f327..39aae87efa0 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 ae6fe3d9ea0..23221b6a7b8 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 8118272070e..e3d7ff0bef2 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 84d8c36f45f..69b175339ab 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 6c9584aaa39..4a774bc9b4d 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.