Subject: Re: bug#79042: 29.4; dired-get-marked-files docstring is incorrect

From: Eli Zaretskii <[email-masked]>
Date: Sat, 19 Jul 2025 13:06:36 +0300

> Cc: "[email-masked]" <[email-masked]>
> From: Sean McAfee <[email-masked]>
> Date: Fri, 18 Jul 2025 12:01:20 -0700
> 
> On Fri, Jul 18, 2025 at 9:27 AM Drew Adams <[email-masked]> wrote:
> 
>  >> It's not a doc bug, it's a product bug - a regression
>  >> introduced in Emacs 29.  In prior versions it works
>  >> as the doc says: (dired-get-marked-files nil 'marked)
>  >> returns the file name on the current line.
>  >
>  > Wait, so dired-get-marked-files isn't supposed to be able to 
>  > distinguish between a single explicitly marked file and no files 
>  > being marked?  But that's information that I need.
>  > How do I get it, if not with dired-get-marked-files?

You could call dired-get-marked-files with nil ARG and then with ARG
equal to 'marked', and compare the results.

>  Mea culpa.  I shouldn't have said the Emacs 29+ behavior
>  of recognizing a special `marked' value for ARG is a bug.
>  (It's maybe not the best way to allow that behavior, but
>  it's OK.)
> 
> I understood, I'm just astonished that the current behavior is
> considered a bug, since it seems so useful.  Is there a
> compelling reason not to allow dired-get-marked-files to
> return nil when no files are explicitly marked, when it's
> given a special distinguished value for ARG?  It's a
> pattern that's used in many other places.

The previous behavior wasn't a bug.  The new special value of 'marked'
was introduced in support of the new user option
dired-mouse-drag-files, which needs to distinguish between the two
cases.  Since the special value 'marked' is new in Emacs 29, and used
only in a couple of places, I don't understand why you are saying that
it's "a pattern that's used in many other places".  How could that be
true?  Is there perhaps a misunderstanding here?  What are the
specific practical problems you encountered with this new feature?

Your original report said:

> For context, I was looking for a way to get a list of marked files, or
> nil if no files are explicitly marked.  The docstring for
> dired-get-marked-files does not admit such a usage, but it actually is
> possible, as described above.

This is explicitly possible using this new value.  So I'm not sure
what other issues did you have in this regard.

In any case, I've updated (on the emacs-30 release branch) the doc
strings of the relevant functions with the effect of the special value
'marked'.  I think this is all we need to do in this bug.