Subject: bug#62126: 26.3; Doc of `dired-do(-async)-shell-command': mention `dired-guess-shell-command'

From: Drew Adams <[email-masked]>
Date: Sun, 12 Mar 2023 15:59:22 +0000

> > Thanks; I missed that.
> >
> > > Actually, I see that in Emacs 26.3 as well, so I'm not sure why you
> > > didn't.  Maybe you didn't mention all the commands you had in mind?
> >
> > Where do you see it in 26.3?  I didn't find it there.
> > I don't see it there in either of those doc strings.
> > I don't see it in the Emacs manual, where those
> > commands are doc'd (or anywhere else).  I don't see
> > it in the Elisp manual.  But I haven't had any coffee
> > yet this morning...
> 
> Maybe this is a misunderstanding.  How about if you show the doc
> strings of the offending functions and tell explicitly what is missing
> from them?

This is present in 27.2 and missing in Emacs 26.3:

  'dired-guess-shell-alist-default' and
  'dired-guess-shell-alist-user' are consulted when the user is
  prompted for the shell command to use interactively.
______

Emacs 27.2:

dired-do-shell-command is an autoloaded interactive compiled Lisp
function in 'dired-aux.el'.

It is bound to !, X, <menu-bar> <operate> <command>.

(dired-do-shell-command COMMAND &optional ARG FILE-LIST)

  Probably introduced at or before Emacs version 21.1.

Run a shell command COMMAND on the marked files.
If no files are marked or a numeric prefix arg is given,
the next ARG files are used.  Just C-u means the current file.
The prompt mentions the file(s) or the marker, as appropriate.

If there is a '*' in COMMAND, surrounded by whitespace, this runs
COMMAND just once with the entire file list substituted there.

If there is no '*', but there is a '?' in COMMAND, surrounded by
whitespace, or a '`?`' this runs COMMAND on each file
individually with the file name substituted for '?' or '`?`'.

Otherwise, this runs COMMAND on each file individually with the
file name added at the end of COMMAND (separated by a space).

'*' and '?' when not surrounded by whitespace nor '`' have no special
significance for 'dired-do-shell-command', and are passed through
normally to the shell, but you must confirm first.

If you want to use '*' as a shell wildcard with whitespace around
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
'*Async Shell Command*'.  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 Output*'.

This feature does not try to redisplay Dired buffers afterward, as
there's no telling what files COMMAND may have changed.
Type l to redisplay the marked files.

When COMMAND runs, its working directory is the top-level directory
of the Dired buffer, so output files usually are created there
instead of in a subdir.

In a noninteractive call (from Lisp code), you must specify
the list of file names explicitly with the FILE-LIST argument, which
can be produced by 'dired-get-marked-files', for example.

'dired-guess-shell-alist-default' and
'dired-guess-shell-alist-user' are consulted when the user is
prompted for the shell command to use interactively.

________________

Emacs 26.3:

dired-do-shell-command is an interactive autoloaded compiled Lisp
function in 'dired-aux.el'.

It is bound to !, X, <menu-bar> <operate> <command>.

(dired-do-shell-command COMMAND &optional ARG FILE-LIST)

Run a shell command COMMAND on the marked files.
If no files are marked or a numeric prefix arg is given,
the next ARG files are used.  Just C-u means the current file.
The prompt mentions the file(s) or the marker, as appropriate.

If there is a '*' in COMMAND, surrounded by whitespace, this runs
COMMAND just once with the entire file list substituted there.

If there is no '*', but there is a '?' in COMMAND, surrounded by
whitespace, or a '`?`' this runs COMMAND on each file
individually with the file name substituted for '?' or '`?`'.

Otherwise, this runs COMMAND on each file individually with the
file name added at the end of COMMAND (separated by a space).

'*' and '?' when not surrounded by whitespace nor '`' have no special
significance for 'dired-do-shell-command', and are passed through
normally to the shell, but you must confirm first.

If you want to use '*' as a shell wildcard with whitespace around
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
'*Async Shell Command*'.  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 Output*'.

This feature does not try to redisplay Dired buffers afterward, as
there's no telling what files COMMAND may have changed.
Type l to redisplay the marked files.

When COMMAND runs, its working directory is the top-level directory
of the Dired buffer, so output files usually are created there
instead of in a subdir.

In a noninteractive call (from Lisp code), you must specify
the list of file names explicitly with the FILE-LIST argument, which
can be produced by 'dired-get-marked-files', for example.