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

From: Sean McAfee <[email-masked]>
Date: Thu, 17 Jul 2025 13:47:01 -0700

Visit a directory with Dired, move to any file, and execute
the following code with eval-expression:

  (dired-get-marked-files nil 'marked)

It returns nil, even though the docstring for dired-get-marked-files
says "If ARG is any other [ie, not an integer] non-nil value, return
the current file name."  This is because the ARG argument is
passed to dired-map-over-marks, which interprets the symbol
"marked" in this way.

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.

In GNU Emacs 29.4 (build 1, x86_64-pc-linux-gnu, GTK+ Version 3.24.41,
 cairo version 1.18.0) of 2025-01-29 built on system76-pc Windowing
 system distributor 'The X.Org Foundation', version 11.0.12302006 System
 Description: Ubuntu 24.04.1 LTS

Configured using:
 'configure --with-json --with-tree-sitter'

Configured features:
CAIRO DBUS FREETYPE GIF GLIB GMP GNUTLS GSETTINGS HARFBUZZ JPEG JSON
LIBSELINUX LIBXML2 MODULES NOTIFY INOTIFY PDUMPER PNG RSVG SECCOMP SOUND
SQLITE3 THREADS TIFF TOOLKIT_SCROLL_BARS TREE_SITTER WEBP X11 XDBE XIM
XINPUT2 XPM GTK3 ZLIB

Important settings:
  value of $LC_MONETARY: en_US.UTF-8
  value of $LC_NUMERIC: en_US.UTF-8
  value of $LC_TIME: en_US.UTF-8
  value of $LANG: en_US.UTF-8
  value of $XMODIFIERS: @im=ibus
  locale-coding-system: utf-8-unix

Major mode: ELisp/l

Minor modes in effect:
  recentf-mode: t
  emms-mode-line-mode: t
  emms-playing-time-display-mode: t
  emms-playing-time-mode: t
  volatile-highlights-mode: t
  projectile-mode: t
  elisp-slime-nav-mode: t
  global-git-commit-mode: t
  magit-auto-revert-mode: t
  shell-dirtrack-mode: t
  global-flycheck-mode: t
  flycheck-mode: t
  minibuffer-depth-indicate-mode: t
  ido-vertical-mode: t
  global-undo-tree-mode: t
  undo-tree-mode: t
  paredit-mode: t
  override-global-mode: t
  desktop-save-mode: t
  winner-mode: t
  electric-pair-mode: t
  savehist-mode: t
  ido-everywhere: t
  tooltip-mode: t
  global-eldoc-mode: t
  eldoc-mode: t
  show-paren-mode: t
  electric-indent-mode: t
  mouse-wheel-mode: t
  global-prettify-symbols-mode: t
  prettify-symbols-mode: t
  menu-bar-mode: t
  file-name-shadow-mode: t
  global-font-lock-mode: t
  font-lock-mode: t
  blink-cursor-mode: t
  buffer-read-only: t
  line-number-mode: t
  transient-mark-mode: t
  auto-composition-mode: t
  auto-encryption-mode: t
  auto-compression-mode: t

Load-path shadows:
~/emacs/ack hides /home/mcafee/.emacs.d/elpa/ack-1.11/ack
/home/mcafee/.emacs.d/elpa/git-commit-20240123.1358/git-commit hides
/home/mcafee/.emacs.d/elpa/magit-20241223.2133/git-commit
/home/mcafee/.emacs.d/elpa/transient-20241224.2234/transient hides
/usr/local/share/emacs/29.4/lisp/transient
/home/mcafee/.emacs.d/elpa/bind-key-20230203.2004/bind-key hides
/usr/local/share/emacs/29.4/lisp/use-package/bind-key
/home/mcafee/.emacs.d/elpa/use-package-20230426.2324/use-package-ensure
hides /usr/local/share/emacs/29.4/lisp/use-package/use-package-ensure
/home/mcafee/.emacs.d/elpa/use-package-20230426.2324/use-package-lint hides
/usr/local/share/emacs/29.4/lisp/use-package/use-package-lint
/home/mcafee/.emacs.d/elpa/use-package-20230426.2324/use-package-core hides
/usr/local/share/emacs/29.4/lisp/use-package/use-package-core
/home/mcafee/.emacs.d/elpa/use-package-20230426.2324/use-package hides
/usr/local/share/emacs/29.4/lisp/use-package/use-package
/home/mcafee/.emacs.d/elpa/use-package-20230426.2324/use-package-bind-key
hides /usr/local/share/emacs/29.4/lisp/use-package/use-package-bind-key
/home/mcafee/.emacs.d/elpa/use-package-20230426.2324/use-package-jump hides
/usr/local/share/emacs/29.4/lisp/use-package/use-package-jump
/home/mcafee/.emacs.d/elpa/use-package-20230426.2324/use-package-diminish
hides /usr/local/share/emacs/29.4/lisp/use-package/use-package-diminish
/home/mcafee/.emacs.d/elpa/use-package-20230426.2324/use-package-delight
hides /usr/local/share/emacs/29.4/lisp/use-package/use-package-delight
~/emacs/japanese hides /usr/local/share/emacs/29.4/lisp/language/japanese
~/emacs/chinese hides /usr/local/share/emacs/29.4/lisp/language/chinese

Features:
(shadow mail-extr emacsbug pulse misearch multi-isearch shortdoc
help-fns radix-tree executable recentf tree-widget conf-mode view vc-git
org-bullets org-element org-persist org-id org-refile avl-tree oc-basic
ol-eww eww xdg url-queue mm-url ol-rmail ol-mhe ol-irc ol-info ol-gnus
nnselect gnus-art mm-uu mml2015 mm-view mml-smime smime gnutls dig
gnus-sum shr pixel-fill kinsoku url-file svg gnus-group gnus-undo
gnus-start gnus-dbus gnus-cloud nnimap nnmail mail-source utf7 nnoo
parse-time gnus-spec gnus-int gnus-range gnus-win ol-docview doc-view
jka-compr image-mode exif ol-bibtex bibtex iso8601 ol-bbdb ol-w3m ol-doi
org-link-doi raku-detect org ob ob-tangle ob-ref ob-lob ob-table ob-exp
org-macro org-src ob-comint org-pcomplete org-list org-footnote
org-faces org-entities noutline outline ob-emacs-lisp ob-core ob-eval
org-cycle org-table ol org-fold org-fold-core org-keys oc org-loaddefs
cal-menu calendar cal-loaddefs org-version org-compat org-macs
gnus-dired dired-launch emms-idapi-browser emms-idapi
emms-idapi-musicbrainz emms-mpris dbus emms-librefm-stream xml
emms-librefm-scrobbler emms-playlist-limit emms-i18n emms-history
emms-score emms-stream-info emms-metaplaylist-mode emms-bookmarks
emms-cue emms-mode-line-icon emms-browser sort emms-volume
emms-volume-sndioctl emms-volume-mixerctl emms-volume-pulse
emms-volume-amixer emms-playlist-sort emms-last-played emms-player-xine
emms-player-mpd tq emms-lyrics emms-url emms-streams emms-show-all
emms-tag-editor emms-tag-tracktag emms-mark emms-mode-line emms-cache
emms-info-native emms-info-native-spc emms-info-native-mp3
emms-info-native-ogg emms-info-native-opus emms-info-native-flac
emms-info-native-vorbis bindat emms-info-exiftool emms-info-tinytag
emms-info-metaflac emms-info-opusinfo emms-info-ogginfo
emms-info-mp3info emms-playlist-mode emms-player-vlc emms-player-mpv
emms-playing-time emms-info emms-later-do emms-player-mplayer
emms-player-simple emms-source-playlist emms-source-file locate
emms-setup emms emms-compat treesit-auto xref-js2 vc vc-dispatcher
js2-mode js c-ts-common treesit cc-mode cc-fonts cc-guess cc-menus
cc-cmds cc-styles cc-align cc-engine cc-vars cc-defs dired-filter f
dired-hacks-utils dired-aux dired-x shell-pop term disp-table ehelp
beginend volatile-highlights iedit iedit-lib
mc-hide-unmatched-lines-mode mc-mark-more tagedit s sgml-mode facemenu
dom mc-cycle-cursors multiple-cursors-core rect dtrt-indent advice
projectile lisp-mnt grep ibuf-ext ibuffer ibuffer-loaddefs
elisp-slime-nav etags fileloop generator xref project magit-submodule
magit-blame magit-stash magit-reflog magit-bisect magit-push magit-pull
magit-fetch magit-clone magit-remote magit-commit magit-sequence
magit-notes magit-worktree magit-tag magit-merge magit-branch
magit-reset magit-files magit-refs magit-status magit magit-repos
magit-apply magit-wip magit-log which-func imenu magit-diff smerge-mode
diff-mode git-commit log-edit message sendmail yank-media puny dired
dired-loaddefs rfc822 mml mml-sec epa epg rfc6068 epg-config mm-decode
mm-bodies mm-encode mail-parse rfc2231 rfc2047 rfc2045 ietf-drums
mailabbrev gmm-utils mailheader pcvs-util add-log magit-core
magit-autorevert autorevert filenotify magit-margin magit-transient
magit-process with-editor shell pcomplete server magit-mode transient
benchmark magit-git magit-base magit-section format-spec cursor-sensor
crm compat compat-30 ido-completing-read+ memoize cus-edit pp cus-load
icons minibuf-eldef flycheck find-func diminish gnus nnheader gnus-util
time-date mail-utils range mm-util mail-prsvr wid-edit autoinsert misc
sanityinc-tomorrow-blue-theme color-theme-sanityinc-tomorrow color
mb-depth files-x ido-vertical-mode undo-tree diff queue ack derived
compile text-property-search paredit edmacro kmacro dash cl-extra
help-mode use-package use-package-ensure use-package-delight
use-package-diminish use-package-bind-key bind-key easy-mmode
use-package-core desktop frameset finder-inf winner elec-pair savehist
hippie-exp comint ansi-osc ansi-color ring thingatpt ido cl
color-theme-sanityinc-tomorrow-autoloads dired-filter-autoloads
dired-launch-autoloads dired-ranger-autoloads
dired-hacks-utils-autoloads dtrt-indent-autoloads emms-autoloads
expand-region-autoloads f-autoloads fix-word flycheck-autoloads
git-link-autoloads git-timemachine-autoloads haskell-mode-autoloads
helm-autoloads helm-core-autoloads async-autoloads magit-autoloads pcase
magit-section-autoloads markdown-mode-autoloads
multiple-cursors-autoloads nov-autoloads paredit-autoloads
projectile-autoloads rx shell-pop-autoloads transient-autoloads
treesit-auto-autoloads volatile-highlights-autoloads wfnames-autoloads
with-editor-autoloads info compat-autoloads js2-mode-autoloads
yasnippet-autoloads package browse-url url url-proxy url-privacy
url-expand url-methods url-history url-cookie generate-lisp-file
url-domsuf url-util mailcap url-handlers url-parse auth-source cl-seq
eieio eieio-core cl-macs password-cache json subr-x map byte-opt gv
bytecomp byte-compile url-vars cl-loaddefs cl-lib rmc iso-transl tooltip
cconv eldoc paren electric uniquify ediff-hook vc-hooks lisp-float-type
elisp-mode mwheel term/x-win x-win term/common-win x-dnd tool-bar dnd
fontset image regexp-opt fringe tabulated-list replace newcomment
text-mode lisp-mode prog-mode register page tab-bar menu-bar rfn-eshadow
isearch easymenu timer select scroll-bar mouse jit-lock font-lock syntax
font-core term/tty-colors frame minibuffer nadvice seq simple cl-generic
indonesian philippine cham georgian utf-8-lang misc-lang vietnamese
tibetan thai tai-viet lao korean japanese eucjp-ms cp51932 hebrew greek
romanian slovak czech european ethiopic indian cyrillic chinese
composite emoji-zwj charscript charprop case-table epa-hook
jka-cmpr-hook help abbrev obarray oclosure cl-preloaded button loaddefs
theme-loaddefs faces cus-face macroexp files window text-properties
overlay sha1 md5 base64 format env code-pages mule custom widget keymap
hashtable-print-readable backquote threads dbusbind inotify
dynamic-setting system-font-setting font-render-setting cairo
move-toolbar gtk x-toolkit xinput2 x multi-tty make-network-process
emacs)

Memory information:
((conses 16 1036589 83243)
 (symbols 48 50195 11)
 (strings 32 279255 11680)
 (string-bytes 1 7740814)
 (vectors 16 101791)
 (vector-slots 8 1879206 240753)
 (floats 8 572 113)
 (intervals 56 52623 352)
 (buffers 984 71))