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

From: Drew Adams <[email-masked]>
Date: Fri, 18 Jul 2025 21:08:12 +0000

> I understood, I'm just astonished that the current behavior
> is considered a bug, since it seems so useful.

As I said, I mistakenly said this new (>= Emacs 29)
behavior is a bug.  As you said at the outset, the
`dired-get-marked-files' doc could/should be updated
to reflect this new behavior.  Other functions that
use `dired-map-over-marks' might also need to have
their doc updated for the ARG description.

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

I gave a reason why I think it hasn't bothered to
allow that: existing uses of `dired-get-marked-files'
are for _commands_ where it's a _feature_ to pick up
the file name on the current line if ARG isn't an
integer and no lines are explicitly marked.  (And of
course those existing commands haven't provided an
interactive way to get an ARG value of `marked'.)

In sum, I think the doc of `dired-get-marked-files'
was based on its behavior, which was based on the
existing uses of it, which was by commands that had
no particular use for the ARG=`marked' behavior and
provided no way to get such a value interactively.

It's _possible_ that `dired-map-over-marks' was
changed without a lot of thought about all of its
existing or possible new uses.  I don't know.

With Emacs 29 changing `dired-map-over-marks' to
recognize ARG = `marked', the behavior of functions
that use that macro also changes (unless they get
changed to call `dired-map-over-marks' differently).
One such function is `dired-get-marked-files'.

Other functions also use `dired-map-over-marks', in 
`dired.el', `dired-aux.el', `dired-x.el', `ediff.el',
`message.el', and `image-dired-dired.el.  Someone
fixing the doc of `dired-get-marked-files' for this
bug could check their doc strings as well.  (And
similarly for functions that use such functions, if
their own doc describes the same ARG.)

___

FWIW (only related as another change to ARG behavior):

In my own code (Dired+), if argument ARG of 
`dired-get-marked-files' is a cons (e.g. from using
`C-u' with a command that calls it) then it returns
_all_ files, ignoring any marks, as follows:

 If ARG is a cons with element 16, 64, or 256, corresponding to
  `C-u C-u', `C-u C-u C-u', or `C-u C-u C-u C-u', then use all files
  in the Dired buffer, where:
    16 includes NO directories (including `.' and `..')
    64 includes directories EXCEPT `.' and `..'
   256 includes ALL directories (including `.' and `..')

(This is implemented by the Dired+ version of
`dired-map-over-marks'.)

IMO, being able to _keep a set of markings_ and act
on all files is an important, and common, use case.

And now, because of the Emacs 29 `dired-map-over-marks'
change, it has a new possibility: passing it an ARG of
`marked' from Lisp.  (I haven't given users a way to do
that interactively, and probably won't.)