bug#63875: 26.3; Doc of `dired-guess-shell-alist-user'

bug#63875: 26.3; Doc of `dired-guess-shell-alist-user'

[Drew Adams]

The doc string doesn't say what REGEXP is, e.g., what it's intended to
match.  It should say that up front and explicitly.

Manual (dired-x) `Shell Command Guessing' sort of says it, if you read
carefully and guess a bit.

Please say explicitly that REGEXP is a regexp that's used to match file
names.  And say how the alist entries are used.  All that's said, so
far, is that this is a "User-defined alist of rules for suggested
commands."

Rules used how?  What does matching file names have to do with using a
command?  Again, the manual does say this somewhat, but not the doc
string.

The doc refers to `dired-guess-shell-alist-default', but the doc for
that variable doesn't explain anything, so it doesn't help with the
missing info for `dired-guess-shell-alist-user'.

FWIW, the comment in file dired-x.el that introduces these variables
describes them better than the doc in some ways: what they're for, how
they're used.

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.19045
Configured using:
 `configure --without-dbus --host=x86_64-w64-mingw32
 --without-compress-install 'CFLAGS=-O2 -static -g3''

bug#63875: 26.3; Doc of `dired-guess-shell-alist-user'

[Drew Adams]

Maybe say something similar to what oantolin says
in this Reddit post:

  "an alist that maps filename regexps to a list
   of commands you might want to apply to the file."

https://www.reddit.com/r/emacs/comments/13yrk5k/is_there_a_package_for_a_opening_a_menu_of_file/jmprpp2/

And maybe make clear that "shell command" here can
also mean any executable program.  (No shell need
be involved.)

bug#63875: 26.3; Doc of `dired-guess-shell-alist-user'

[Juri Linkov]

> Maybe say something similar to what oantolin says
> in this Reddit post:
>
>   "an alist that maps filename regexps to a list
>    of commands you might want to apply to the file."
>
> https://www.reddit.com/r/emacs/comments/13yrk5k/is_there_a_package_for_a_opening_a_menu_of_file/jmprpp2/

The request was:

  "I was thinking of something similar to OS file managers, where you can
  right-click a file and have operations relevant to the extension pop up."

So does it makes sense to add to the context menu in Dired a submenu
like this?

  "Open with ..." ->
    "Command 1"
    "Command 2"
    ...

bug#63875: 26.3; Doc of `dired-guess-shell-alist-user'

[Eli Zaretskii]

> From: Drew Adams <drew.adams@oracle.com>
> Date: Sat, 3 Jun 2023 16:08:11 +0000
> 
> The doc string doesn't say what REGEXP is, e.g., what it's intended to
> match.  It should say that up front and explicitly.

???The doc string says:

  Each element of this list looks like

      (REGEXP COMMAND...)

  COMMAND will be used if REGEXP matches the file to be processed.
  If several files are to be processed, REGEXP has to match all the
  files.

"REGEXP matches the file to be processed".  What else needs to be
said?

bug#63875: 26.3; Doc of `dired-guess-shell-alist-user'

[Drew Adams]

> > The doc string doesn't say what REGEXP is, e.g., what it's intended to
> > match.  It should say that up front and explicitly.
> 
> ???The doc string says:
> 
>   Each element of this list looks like
> 
>       (REGEXP COMMAND...)
> 
>   COMMAND will be used if REGEXP matches the file to be processed.
>   If several files are to be processed, REGEXP has to match all the
>   files.
> 
> "REGEXP matches the file to be processed".  What else needs to be
> said?

Apologies.  The bug report was from Emacs 26.  I see
now that the doc string was improved since then to
what you quote.

In Emacs 26, it says only this:

 Each element of this list looks like

     (REGEXP COMMAND...)

 where each COMMAND can either be a string or a Lisp
 expression that evaluates to a string.

Feel free to close the bug.  Thx.

bug#63875: 26.3; Doc of `dired-guess-shell-alist-user'

[Eli Zaretskii]

> From: Drew Adams <drew.adams@oracle.com>
> CC: "63875@debbugs.gnu.org" <63875@debbugs.gnu.org>
> Date: Sat, 3 Jun 2023 16:21:55 +0000
> 
> > > The doc string doesn't say what REGEXP is, e.g., what it's intended to
> > > match.  It should say that up front and explicitly.
> > 
> > ???The doc string says:
> > 
> >   Each element of this list looks like
> > 
> >       (REGEXP COMMAND...)
> > 
> >   COMMAND will be used if REGEXP matches the file to be processed.
> >   If several files are to be processed, REGEXP has to match all the
> >   files.
> > 
> > "REGEXP matches the file to be processed".  What else needs to be
> > said?
> 
> Apologies.  The bug report was from Emacs 26.  I see
> now that the doc string was improved since then to
> what you quote.
> 
> In Emacs 26, it says only this:
> 
>  Each element of this list looks like
> 
>      (REGEXP COMMAND...)
> 
>  where each COMMAND can either be a string or a Lisp
>  expression that evaluates to a string.
> 
> Feel free to close the bug.  Thx.

Closing.

bug#63875: 26.3; Doc of `dired-guess-shell-alist-user'

[Drew Adams]

> Feel free to close the bug.  Thx.

But it would be good, I think, to add that it's
not just about shell commands.  Some users will
not recognize that they can invoke executable
programs this way.

E.g., on MS Windows, users who never use anything
like a shell explicitly will nevertheless want to
know how to associate files (by name matches) with
applications, in Emacs.

bug#63875: 26.3; Doc of `dired-guess-shell-alist-user'

[Eli Zaretskii]

> From: Drew Adams <drew.adams@oracle.com>
> CC: "63875@debbugs.gnu.org" <63875@debbugs.gnu.org>
> Date: Sat, 3 Jun 2023 16:26:02 +0000
> 
> > Feel free to close the bug.  Thx.
> 
> But it would be good, I think, to add that it's
> not just about shell commands.  Some users will
> not recognize that they can invoke executable
> programs this way.

Shell commands are a super-set of executable programs, so I see no
reason to change anything here.  The variable is used to invoke
commands via a shell, so "shell command" is exactly right.

bug#63875: 26.3; Doc of `dired-guess-shell-alist-user'

[Drew Adams]

> > But it would be good, I think, to add that it's
> > not just about shell commands.  Some users will
> > not recognize that they can invoke executable
> > programs this way.
> 
> Shell commands are a super-set of executable programs, so I see no
> reason to change anything here.  The variable is used to invoke
> commands via a shell, so "shell command" is exactly right.

Yes, but many Emacs users won't know that.

Unless they're programmers or they are used to
GNU or Unix or Linux, some users won't guess
that they can use this user option to associate
applications (executable binaries) with file
names for Emacs.

MS Windows, for example, may know how to create
default file associations for programs invoked
normally (for Windows), but Emacs users on
Windows might well not guess that they can
associate files with programs for Emacs.

If you disagree that this is the case, fine.
But if you agree then maybe you'll consider
explicitly mentioning this use of the option.

bug#63875: 26.3; Doc of `dired-guess-shell-alist-user'

[Eli Zaretskii]

> From: Drew Adams <drew.adams@oracle.com>
> CC: "63875@debbugs.gnu.org" <63875@debbugs.gnu.org>
> Date: Sat, 3 Jun 2023 17:20:14 +0000
> 
> > > But it would be good, I think, to add that it's
> > > not just about shell commands.  Some users will
> > > not recognize that they can invoke executable
> > > programs this way.
> > 
> > Shell commands are a super-set of executable programs, so I see no
> > reason to change anything here.  The variable is used to invoke
> > commands via a shell, so "shell command" is exactly right.
> 
> Yes, but many Emacs users won't know that.

Why wouldn't they? we have a chapter named "Running Shell Commands
from Emacs" in the Emacs manual.  Typing "i shell commands RET" in
Info brings you there.

I think you see a problem where there is none.

bug#63875: 26.3; Doc of `dired-guess-shell-alist-user'

[Drew Adams]

> > > > But it would be good, I think, to add that it's
> > > > not just about shell commands.  Some users will
> > > > not recognize that they can invoke executable
> > > > programs this way.
> > >
> > > Shell commands are a super-set of executable programs, so I see no
> > > reason to change anything here.  The variable is used to invoke
> > > commands via a shell, so "shell command" is exactly right.
> >
> > Yes, but many Emacs users won't know that.
> 
> Why wouldn't they? we have a chapter named "Running Shell Commands
> from Emacs" in the Emacs manual.  Typing "i shell commands RET" in
> Info brings you there.
> 
> I think you see a problem where there is none.

Is that Emacs manual node linked from the
Dired-x manual page that describes the option?

Is it linked from the *Help* output for the option?

Else it's unlikely that most users reading the doc
for the option will search for "shell commands"
in the Emacs manual.

Most users have likely heard of shell commands,
but it's not at all obvious that nonprogrammers
etc. will realize that mention of shell commands
in a description of this option will likely be of
use to them for associating files with apps.

That's the purpose of this option.  It would be
far clearer, and far easier for doc maintainers
and users of the doc, to simply add a brief
sentence or phrase to indicate that "shell
commands" here covers programs in general.

I've said enough to get the point across.  If
you don't want to fix this because a user has
the ability to go to the Emacs manual from
the doc string or from the Dired-X manual, and
look up "shell command" in the Emacs manual,
fine.