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

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

[Drew Adams]

It would help if the doc of these commands (and others that use
`dired-read-shell-command') mentioned that if `dired-x' is loaded then
they make use of option `dired-guess-shell-command' to guess an
appropriate default value (command).

To find this out now, users need to check the implementations of such
commands, see that they call `dired-read-shell-command', and check the
doc of that function.

In GNU Emacs 26.3 (build 1, x86_64-w64-mingw32)
 of 2019-08-29
Repository revision: 96dd0196c28bc36779584e47fffcca433c9309cd
Windowing system distributor `Microsoft Corp.', version 10.0.19044
Configured using:
 `configure --without-dbus --host=x86_64-w64-mingw32
 --without-compress-install 'CFLAGS=-O2 -static -g3''

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

[Eli Zaretskii]

> From: Drew Adams <drew.adams@oracle.com>
> Date: Sat, 11 Mar 2023 17:58:10 +0000
> 
> It would help if the doc of these commands (and others that use
> `dired-read-shell-command') mentioned that if `dired-x' is loaded then
> they make use of option `dired-guess-shell-command' to guess an
> appropriate default value (command).

It already does, in Emacs 27 and later.

Closing.

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

[Eli Zaretskii]

> Resent-To: bug-gnu-emacs@gnu.org
> Cc: 62126-done@debbugs.gnu.org
> Date: Sun, 12 Mar 2023 10:42:06 +0200
> From: Eli Zaretskii <eliz@gnu.org>
> 
> > From: Drew Adams <drew.adams@oracle.com>
> > Date: Sat, 11 Mar 2023 17:58:10 +0000
> > 
> > It would help if the doc of these commands (and others that use
> > `dired-read-shell-command') mentioned that if `dired-x' is loaded then
> > they make use of option `dired-guess-shell-command' to guess an
> > appropriate default value (command).
> 
> It already does, in Emacs 27 and later.

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?

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

[Drew Adams]

> > > It would help if the doc of these commands (and others that use
> > > `dired-read-shell-command') mentioned that if `dired-x' is loaded then
> > > they make use of option `dired-guess-shell-command' to guess an
> > > appropriate default value (command).
> >
> > It already does, in Emacs 27 and later.

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...

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

[Eli Zaretskii]

> From: Drew Adams <drew.adams@oracle.com>
> CC: "62126@debbugs.gnu.org" <62126@debbugs.gnu.org>
> Date: Sun, 12 Mar 2023 15:07:44 +0000
> 
> > > > It would help if the doc of these commands (and others that use
> > > > `dired-read-shell-command') mentioned that if `dired-x' is loaded then
> > > > they make use of option `dired-guess-shell-command' to guess an
> > > > appropriate default value (command).
> > >
> > > It already does, in Emacs 27 and later.
> 
> 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?

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

[Drew Adams]

> > 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.

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

[Eli Zaretskii]

> From: Drew Adams <drew.adams@oracle.com>
> CC: "62126@debbugs.gnu.org" <62126@debbugs.gnu.org>
> Date: Sun, 12 Mar 2023 15:59:22 +0000
> 
> 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.

OK, so this closes the issue, right?

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

[Drew Adams]

> > 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.
> 
> OK, so this closes the issue, right?

Sure.