GNU bug report logs - #11571
24.0.97; doc string of `dired-get-subdir-min'

Previous Next

To add a comment to this bug, you must first unarchive it, by sending
a message to control AT debbugs.gnu.org, with unarchive 11571 in the body.
You can then email your comments to 11571 AT debbugs.gnu.org in the normal way.

Toggle the display of automated, internal messages from the tracker.

Message #5 received at submit <at> debbugs.gnu.org (full text, mbox):

From: "Drew Adams" <drew.adams <at> oracle.com>
To: <bug-gnu-emacs <at> gnu.org>
Subject: 24.0.97; doc string of `dired-get-subdir-min'
Date: Sun, 27 May 2012 14:37:35 -0700

These parts have nothing to do with this function per se, and should be
removed:
 
 "... If arg is nil, return nil.
  Error if arg is not nil and not a cons cell.  See also `cdr-safe'."
 
This is not the place to teach about cdr - this is misplaced zeal.  Just
say that the function returns the cdr of LIST.  If you want to add
something useful, say what that is, in terms of directories etc.  But do
not teach cdr and cons cells here.
 
See Info node `(elisp)Cons Cells' for a discussion of related basic
Lisp concepts such as cdr, car, cons cell and list.
 
In GNU Emacs 24.0.97.1 (i386-mingw-nt5.1.2600)
 of 2012-05-16 on MARVIN
Windowing system distributor `Microsoft Corp.', version 5.1.2600
Configured using:
 `configure --with-gcc (4.6) --no-opt --enable-checking --cflags
 -ID:/devel/emacs/libs/libXpm-3.5.8/include
 -ID:/devel/emacs/libs/libXpm-3.5.8/src
 -ID:/devel/emacs/libs/libpng-dev_1.4.3-1/include
 -ID:/devel/emacs/libs/zlib-dev_1.2.5-2/include
 -ID:/devel/emacs/libs/giflib-4.1.4-1/include
 -ID:/devel/emacs/libs/jpeg-6b-4/include
 -ID:/devel/emacs/libs/tiff-3.8.2-1/include
 -ID:/devel/emacs/libs/gnutls-3.0.9/include'
 

Message #8 received at 11571 <at> debbugs.gnu.org (full text, mbox):

From: "Drew Adams" <drew.adams <at> oracle.com>
To: <11571 <at> debbugs.gnu.org>
Subject: RE: bug#11571: 24.0.97; doc string of `dired-get-subdir-min'
Date: Sun, 27 May 2012 14:41:52 -0700

Actually, the real bug is that `dired-get-subdir-min' has no doc string, so the
doc string of `cdr' is used in its stead.  The whole point of defining and using
a separate function for this, instead of just coding with `cdr', is to enable
readers of the code - and a fortiori the doc - to think in terms of the data
structure of directories and not just abstract cons cells.  There should be doc
at the proper level of abstraction here.

Message #11 received at 11571 <at> debbugs.gnu.org (full text, mbox):

From: "Drew Adams" <drew.adams <at> oracle.com>
To: <11571 <at> debbugs.gnu.org>
Subject: RE: bug#11571: 24.0.97; doc string of `dired-get-subdir-min'
Date: Sun, 16 Sep 2012 16:49:33 -0700

ping

Message #14 received at 11571 <at> debbugs.gnu.org (full text, mbox):

From: Lars Ingebrigtsen <larsi <at> gnus.org>
To: "Drew Adams" <drew.adams <at> oracle.com>
Cc: 11571 <at> debbugs.gnu.org
Subject: Re: bug#11571: 24.0.97; doc string of `dired-get-subdir-min'
Date: Sat, 08 Feb 2014 19:59:19 -0800

"Drew Adams" <drew.adams <at> oracle.com> writes:

> Actually, the real bug is that `dired-get-subdir-min' has no doc string, so the
> doc string of `cdr' is used in its stead.  The whole point of defining and using
> a separate function for this, instead of just coding with `cdr', is to enable
> readers of the code - and a fortiori the doc - to think in terms of the data
> structure of directories and not just abstract cons cells.  There should be doc
> at the proper level of abstraction here.

Help says:

---
dired-get-subdir-min is an alias for `cdr' in `dired.el'.

(dired-get-subdir-min LIST)

Return the cdr of LIST.  If arg is nil, return nil.
Error if arg is not nil and not a cons cell.  See also `cdr-safe'.
---

I think that's fine.

However:

;; can't use macro,  must be redefinable for other alist format in dired-nstd.
(defalias 'dired-get-subdir-min 'cdr)

Which is kinda er.

I don't know what nstd is, and the function doesn't seem to be redefined
anywhere, so is this just legacy gunk?  Should `dired-get-subdir-min'
just be replaced by `cdr' in all the calling sites?

-- 
(domestic pets only, the antidote for overdose, milk.)
  bloggy blog http://lars.ingebrigtsen.no/

Message #17 received at 11571 <at> debbugs.gnu.org (full text, mbox):

From: Drew Adams <drew.adams <at> oracle.com>
To: Lars Ingebrigtsen <larsi <at> gnus.org>
Cc: 11571 <at> debbugs.gnu.org
Subject: RE: bug#11571: 24.0.97; doc string of `dired-get-subdir-min'
Date: Sun, 9 Feb 2014 14:25:27 -0800 (PST)

> > Actually, the real bug is that `dired-get-subdir-min' has no doc
> > string, so the doc string of `cdr' is used in its stead.  The
> > whole point of defining and using a separate function for this,
> > instead of just coding with `cdr', is to enable readers of the
> > code - and a fortiori the doc - to think in terms of the data
> > structure of directories and not just abstract cons cells.  There
> > should be doc at the proper level of abstraction here.
> 
> Help says:
> 
> ---
> dired-get-subdir-min is an alias for `cdr' in `dired.el'.
> (dired-get-subdir-min LIST)
> Return the cdr of LIST.  If arg is nil, return nil.
> Error if arg is not nil and not a cons cell.  See also `cdr-safe'.
> ---
> 
> I think that's fine.

No, it is not fine.  That doc is 100% unrelated to "dired",
"getting" something, "subdir", and "minimum".

If it were fine, then it would be even finer to get rid of this
function, with its supposedly descriptive name, and use just cdr.

If that is the fix you make, fine with me.  If you keep the
function then users deserve its doc to explain what it is about.
Clearly, it is not just "about" returning the cdr.  The function
is named, presumably, to suggest what it is for: its purpose or
behavior WRT DIRED AND SUBDIRS.

Hard to believe that when someone goes to the trouble of
spelling out in the bug report why better doc is needed here
you cannot read and understand that.

> However:
> 
> ;; can't use macro,  must be redefinable for other alist format in
> dired-nstd.
> (defalias 'dired-get-subdir-min 'cdr)
> 
> Which is kinda er.
> 
> I don't know what nstd is, and the function doesn't seem to be
> redefined anywhere, so is this just legacy gunk?  Should
> `dired-get-subdir-min' just be replaced by `cdr' in all the
> calling sites?

Yes, that can be the first question, if you want to get into it.
If you do not want to file a separate (code) bug for that, fine.
But if this function is kept then please document it properly.

Message #20 received at 11571 <at> debbugs.gnu.org (full text, mbox):

From: Stefan Kangas <stefan <at> marxist.se>
To: Lars Ingebrigtsen <larsi <at> gnus.org>
Cc: 11571 <at> debbugs.gnu.org, Drew Adams <drew.adams <at> oracle.com>
Subject: Re: bug#11571: 24.0.97; doc string of `dired-get-subdir-min'
Date: Fri, 01 Nov 2019 19:44:24 +0100

[Message part 1 (text/plain, inline)]

Lars Ingebrigtsen <larsi <at> gnus.org> writes:

> "Drew Adams" <drew.adams <at> oracle.com> writes:
>
>> Actually, the real bug is that `dired-get-subdir-min' has no doc string, so the
>> doc string of `cdr' is used in its stead.  The whole point of defining and using
>> a separate function for this, instead of just coding with `cdr', is to enable
>> readers of the code - and a fortiori the doc - to think in terms of the data
>> structure of directories and not just abstract cons cells.  There should be doc
>> at the proper level of abstraction here.
[...]
> ;; can't use macro,  must be redefinable for other alist format in dired-nstd.
> (defalias 'dired-get-subdir-min 'cdr)
>
> Which is kinda er.
>
> I don't know what nstd is, and the function doesn't seem to be redefined
> anywhere, so is this just legacy gunk?  Should `dired-get-subdir-min'
> just be replaced by `cdr' in all the calling sites?

From searching the web, I think dired-nstd is "dired nested", which
indeed seems to be some old, now non-existent stuff from Emacs 19 or
older.  See this for example:
https://www.cs.cmu.edu/cgi-bin/info2www?(dired.info)Dired%20Known%20Problems

I therefore think it's safe to obsolete this function, like in the below
patch.  Comments?

Best regards,
Stefan Kangas

[0001-Make-dired-get-subdir-min-obsolete.patch (text/x-diff, inline)]

From 1a6c799863380e5986f26a9c8fd9d3fc98241bb1 Mon Sep 17 00:00:00 2001
From: Stefan Kangas <stefankangas <at> gmail.com>
Date: Thu, 31 Oct 2019 02:39:20 +0100
Subject: [PATCH] Make dired-get-subdir-min obsolete

* lisp/dired.el (dired-get-subdir-min): Redefine as obsolete function
alias for 'cdr'.  (Bug#11571)
(dired-get-subdir, dired-get-subdir-max, dired-clear-alist)
(dired-next-subdir, dired-current-directory):
* lisp/dired-aux.el (dired-rename-subdir-2)
(dired-alist-sort, dired-insert-subdir-del)
(dired-insert-subdir-doupdate, dired-goto-subdir)
(dired-hide-subdir, dired-hide-all): Use 'cdr' instead of
the above obsolete function.
---
 lisp/dired-aux.el | 18 +++++++++---------
 lisp/dired.el     | 13 ++++++-------
 2 files changed, 15 insertions(+), 16 deletions(-)

diff --git a/lisp/dired-aux.el b/lisp/dired-aux.el
index b1521ecf01..7f690e7e72 100644
--- a/lisp/dired-aux.el
+++ b/lisp/dired-aux.el
@@ -1713,7 +1713,7 @@ dired-rename-subdir-2
     (let ((regexp (regexp-quote (directory-file-name dir)))
 	  (newtext (directory-file-name to))
 	  buffer-read-only)
-      (goto-char (dired-get-subdir-min elt))
+      (goto-char (cdr elt))
       ;; Update subdir headerline in buffer
       (if (not (looking-at dired-subdir-regexp))
 	  (error "%s not found where expected - dired-subdir-alist broken?"
@@ -2476,8 +2476,8 @@ dired-alist-sort
   (setq dired-subdir-alist
 	(sort dired-subdir-alist
 	      (lambda (elt1 elt2)
-		(> (dired-get-subdir-min elt1)
-		   (dired-get-subdir-min elt2))))))
+		(> (cdr elt1)
+		   (cdr elt2))))))
 
 (defun dired-kill-tree (dirname &optional remember-marks kill-root)
   "Kill all proper subdirs of DIRNAME, excluding DIRNAME itself.
@@ -2520,7 +2520,7 @@ dired-insert-subdir-newpos
 (defun dired-insert-subdir-del (element)
   ;; Erase an already present subdir (given by ELEMENT) from buffer.
   ;; Move to that buffer position.  Return a mark-alist.
-  (let ((begin-marker (dired-get-subdir-min element)))
+  (let ((begin-marker (cdr element)))
     (goto-char begin-marker)
     ;; Are at beginning of subdir (and inside it!).  Now determine its end:
     (goto-char (dired-subdir-max))
@@ -2551,7 +2551,7 @@ dired-insert-subdir-doupdate
   ;; BEG-END is the subdir-region (as list of begin and end).
   (if elt				; subdir was already present
       ;; update its position (should actually be unchanged)
-      (set-marker (dired-get-subdir-min elt) (point-marker))
+      (set-marker (cdr elt) (point-marker))
     (dired-alist-add dirname (point-marker)))
   ;; The hook may depend on the subdir-alist containing the just
   ;; inserted subdir, so run it after dired-alist-add:
@@ -2665,7 +2665,7 @@ dired-goto-subdir
   (setq dir (file-name-as-directory dir))
   (let ((elt (assoc dir dired-subdir-alist)))
     (and elt
-	 (goto-char (dired-get-subdir-min elt))
+	 (goto-char (cdr elt))
 	 ;; dired-subdir-hidden-p and dired-add-entry depend on point being
 	 ;; at \n after this function succeeds.
 	 (progn (end-of-line)
@@ -2763,7 +2763,7 @@ dired-hide-subdir
 	     (end-pos (1- (dired-get-subdir-max elt)))
 	     buffer-read-only)
 	;; keep header line visible, hide rest
-	(goto-char (dired-get-subdir-min elt))
+	(goto-char (cdr elt))
 	(end-of-line)
 	(if hidden-p
 	    (dired--unhide (point) end-pos)
@@ -2782,14 +2782,14 @@ dired-hide-all
       ;; hide
       (let ((pos (point-max)))		; pos of end of last directory
         (dolist (subdir dired-subdir-alist)
-	  (let ((start (dired-get-subdir-min subdir)) ; pos of prev dir
+	  (let ((start (cdr subdir)) ; pos of prev dir
 		(end (save-excursion
 		       (goto-char pos) ; current dir
 		       ;; we're somewhere on current dir's line
 		       (forward-line -1)
 		       (point))))
             (dired--hide start end))
-	  (setq pos (dired-get-subdir-min subdir))))))) ; prev dir gets current dir
+	  (setq pos (cdr subdir))))))) ; prev dir gets current dir
 
 ;;;###end dired-ins.el
 
diff --git a/lisp/dired.el b/lisp/dired.el
index 05789a3516..a94bf528c2 100644
--- a/lisp/dired.el
+++ b/lisp/dired.el
@@ -2857,21 +2857,20 @@ dired-get-subdir
     (let ((cur-dir (dired-current-directory)))
       (beginning-of-line)		; alist stores b-o-l positions
       (and (zerop (- (point)
-		     (dired-get-subdir-min (assoc cur-dir
+		     (cdr (assoc cur-dir
 						  dired-subdir-alist))))
 	   cur-dir))))
 
-;; can't use macro,  must be redefinable for other alist format in dired-nstd.
-(defalias 'dired-get-subdir-min 'cdr)
+(define-obsolete-function-alias 'dired-get-subdir-min 'cdr "27.1")
 
 (defun dired-get-subdir-max (elt)
   (save-excursion
-    (goto-char (dired-get-subdir-min elt))
+    (goto-char (cdr elt))
     (dired-subdir-max)))
 
 (defun dired-clear-alist ()
   (while dired-subdir-alist
-    (set-marker (dired-get-subdir-min (car dired-subdir-alist)) nil)
+    (set-marker (cdr (car dired-subdir-alist)) nil)
     (setq dired-subdir-alist (cdr dired-subdir-alist))))
 
 (defun dired-subdir-index (dir)
@@ -2895,7 +2894,7 @@ dired-next-subdir
     ;; nth with negative arg does not return nil but the first element
     (setq index (- (dired-subdir-index this-dir) arg))
     (setq pos (if (>= index 0)
-		  (dired-get-subdir-min (nth index dired-subdir-alist))))
+		  (cdr (nth index dired-subdir-alist))))
     (if pos
 	(progn
 	  (goto-char pos)
@@ -3116,7 +3115,7 @@ dired-current-directory
       (setq elt (car alist)
 	    dir (car elt)
 	    ;; use `<=' (not `<') as subdir line is part of subdir
-	    alist (if (<= (dired-get-subdir-min elt) here)
+	    alist (if (<= (cdr elt) here)
 		      nil		; found
 		    (cdr alist))))
     (if localp
-- 
2.20.1

Message #23 received at 11571 <at> debbugs.gnu.org (full text, mbox):

From: Drew Adams <drew.adams <at> oracle.com>
To: Stefan Kangas <stefan <at> marxist.se>, Lars Ingebrigtsen <larsi <at> gnus.org>
Cc: 11571 <at> debbugs.gnu.org
Subject: RE: bug#11571: 24.0.97; doc string of `dired-get-subdir-min'
Date: Fri, 1 Nov 2019 13:54:55 -0700 (PDT)

> I therefore think it's safe to obsolete this function, like in the
> below patch.  Comments?

It's OK by me.  Thx.
___

The use of cdr is clear enough, as long as you
understand what `dired-subdir-alist' is.

But that could be clearer. 

`C-h v dired-subdir-alist' says:

 Association list of subdirectories and their buffer positions.
 Each subdirectory has an element: (DIRNAME . STARTMARKER).
 ...

Directories don't have buffer positions.

It would be clearer to say "listed subdirectories".
It's not about subdirectories.  It's about those
subdirs that are listed in the Dired buffer, and
STARTMARKER is the buffer position where such a
_listing_ starts.

The buffer position of a subdirectory isn't clear.
The buffer position of a subdirectory listing is
clear.

Message #26 received at 11571 <at> debbugs.gnu.org (full text, mbox):

From: Lars Ingebrigtsen <larsi <at> gnus.org>
To: Stefan Kangas <stefan <at> marxist.se>
Cc: 11571 <at> debbugs.gnu.org, Drew Adams <drew.adams <at> oracle.com>
Subject: Re: bug#11571: 24.0.97; doc string of `dired-get-subdir-min'
Date: Sat, 02 Nov 2019 15:51:16 +0100

Stefan Kangas <stefan <at> marxist.se> writes:

> I therefore think it's safe to obsolete this function, like in the below
> patch.  Comments?

Looks good to me.

-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no

Message #29 received at 11571 <at> debbugs.gnu.org (full text, mbox):

From: Stefan Kangas <stefan <at> marxist.se>
To: Drew Adams <drew.adams <at> oracle.com>
Cc: Lars Ingebrigtsen <larsi <at> gnus.org>, 11571 <at> debbugs.gnu.org
Subject: Re: bug#11571: 24.0.97; doc string of `dired-get-subdir-min'
Date: Tue, 05 Nov 2019 16:09:32 +0100

Drew Adams <drew.adams <at> oracle.com> writes:

> The use of cdr is clear enough, as long as you
> understand what `dired-subdir-alist' is.
>
> But that could be clearer. 
>
> `C-h v dired-subdir-alist' says:
>
>  Association list of subdirectories and their buffer positions.
>  Each subdirectory has an element: (DIRNAME . STARTMARKER).
>  ...
>
> Directories don't have buffer positions.
>
> It would be clearer to say "listed subdirectories".
> It's not about subdirectories.  It's about those
> subdirs that are listed in the Dired buffer, and
> STARTMARKER is the buffer position where such a
> _listing_ starts.
>
> The buffer position of a subdirectory isn't clear.
> The buffer position of a subdirectory listing is
> clear.

FWIW, I think it's already clear enough, given that the value after
dired-maybe-insert-subdir will be something like:

    (("/home/skangas/wip/emacs/etc/" . #<marker at 3031 in emacs>)
     ("/home/skangas/wip/emacs/" . #<marker at 1 in emacs>))
    
I'm not against trying to make it even clearer though.

Do you have a suggestion for how to rewrite this text without going
over the recommended 67 character limit?

    Association list of subdirectories and their buffer positions.

The best I could come up with is this (exactly 67 characters):

    Alist of subdirectories and the buffer positions of their listings.

Best regards,
Stefan Kangas

Message #32 received at 11571 <at> debbugs.gnu.org (full text, mbox):

From: Drew Adams <drew.adams <at> oracle.com>
To: Stefan Kangas <stefan <at> marxist.se>
Cc: Lars Ingebrigtsen <larsi <at> gnus.org>, 11571 <at> debbugs.gnu.org
Subject: RE: bug#11571: 24.0.97; doc string of `dired-get-subdir-min'
Date: Tue, 5 Nov 2019 08:21:39 -0800 (PST)

> > It would be clearer to say "listed subdirectories".
> > It's not about subdirectories.  It's about those
> > subdirs that are listed in the Dired buffer, and
> > STARTMARKER is the buffer position where such a
> > _listing_ starts.
>  
> Do you have a suggestion for how to rewrite this text without going
> over the recommended 67 character limit?
>     Association list of subdirectories and their buffer positions.
> The best I could come up with is this (exactly 67 characters):
>     Alist of subdirectories and the buffer positions of their listings.

I already suggested it, at the beginning: "listed
subdirectories" instead of just "subdirectories".

To be even more precise, as it's not the listed subdirs
that are used in the alist, but their names:

 Alist of listed subdirectory names and their buffer positions.

However, the alist contains not only elements for the
listed subdirs but also an element for the listed main
dir.  The doc string is unclear about that.

This is clear, I think. And the lines are all less than
60 chars wide:

 Alist of listed directory names and their buffer positions.
 Alist elements have the form (DIRNAME . STARTMARKER), where
 DIRNAME is the listed absolute name of the directory and
 STARTMARKER is a marker at the beginning of DIRNAME.

 The elements are in reverse order of the listing.  If no
 subdirectories are listed then the alist contains only one
 element, for the listed directory.

That also makes clear that DIRNAME is an absolute file name,
and it is what is shown in the listing.  And it makes clear
what the "one element" is when there are no subdir listings. 

Message #35 received at 11571 <at> debbugs.gnu.org (full text, mbox):

From: Stefan Kangas <stefan <at> marxist.se>
To: Drew Adams <drew.adams <at> oracle.com>
Cc: Lars Ingebrigtsen <larsi <at> gnus.org>, 11571 <at> debbugs.gnu.org
Subject: Re: bug#11571: 24.0.97; doc string of `dired-get-subdir-min'
Date: Fri, 08 Nov 2019 14:30:59 +0100

[Message part 1 (text/plain, inline)]

Drew Adams <drew.adams <at> oracle.com> writes:

>> Do you have a suggestion for how to rewrite this text without going
>> over the recommended 67 character limit?
>>     Association list of subdirectories and their buffer positions.
>> The best I could come up with is this (exactly 67 characters):
>>     Alist of subdirectories and the buffer positions of their listings.
[...]
> However, the alist contains not only elements for the
> listed subdirs but also an element for the listed main
> dir.  The doc string is unclear about that.
>
> This is clear, I think. And the lines are all less than
> 60 chars wide:
>
>  Alist of listed directory names and their buffer positions.
>  Alist elements have the form (DIRNAME . STARTMARKER), where
>  DIRNAME is the listed absolute name of the directory and
>  STARTMARKER is a marker at the beginning of DIRNAME.
>
>  The elements are in reverse order of the listing.  If no
>  subdirectories are listed then the alist contains only one
>  element, for the listed directory.
>
> That also makes clear that DIRNAME is an absolute file name,
> and it is what is shown in the listing.  And it makes clear
> what the "one element" is when there are no subdir listings. 

Thanks, that's much better.  I've attached an updated patch with a
slightly different wording.  If there are no further comments or
objections, I intend to push this in a couple of days.

Best regards,
Stefan Kangas

[0001-Make-dired-get-subdir-min-obsolete.patch (text/x-diff, inline)]

From 181fea4507be10c80981ff7fd650f7d6b82de039 Mon Sep 17 00:00:00 2001
From: Stefan Kangas <stefankangas <at> gmail.com>
Date: Thu, 31 Oct 2019 02:39:20 +0100
Subject: [PATCH] Make dired-get-subdir-min obsolete

* lisp/dired.el (dired-get-subdir-min): Redefine as obsolete function
alias for 'cdr'.  (Bug#11571)
(dired-get-subdir, dired-get-subdir-max, dired-clear-alist)
(dired-next-subdir, dired-current-directory):
* lisp/dired-aux.el (dired-rename-subdir-2)
(dired-alist-sort, dired-insert-subdir-del)
(dired-insert-subdir-doupdate, dired-goto-subdir)
(dired-hide-subdir, dired-hide-all): Use 'cdr' instead of
the above obsolete function.
(dired-subdir-alist): Doc fix.
---
 lisp/dired-aux.el | 18 +++++++++---------
 lisp/dired.el     | 20 +++++++++++---------
 2 files changed, 20 insertions(+), 18 deletions(-)

diff --git a/lisp/dired-aux.el b/lisp/dired-aux.el
index 722d036e3f..184b507e1d 100644
--- a/lisp/dired-aux.el
+++ b/lisp/dired-aux.el
@@ -1728,7 +1728,7 @@ dired-rename-subdir-2
     (let ((regexp (regexp-quote (directory-file-name dir)))
 	  (newtext (directory-file-name to))
 	  buffer-read-only)
-      (goto-char (dired-get-subdir-min elt))
+      (goto-char (cdr elt))
       ;; Update subdir headerline in buffer
       (if (not (looking-at dired-subdir-regexp))
 	  (error "%s not found where expected - dired-subdir-alist broken?"
@@ -2491,8 +2491,8 @@ dired-alist-sort
   (setq dired-subdir-alist
 	(sort dired-subdir-alist
 	      (lambda (elt1 elt2)
-		(> (dired-get-subdir-min elt1)
-		   (dired-get-subdir-min elt2))))))
+                (> (cdr elt1)
+                   (cdr elt2))))))
 
 (defun dired-kill-tree (dirname &optional remember-marks kill-root)
   "Kill all proper subdirs of DIRNAME, excluding DIRNAME itself.
@@ -2535,7 +2535,7 @@ dired-insert-subdir-newpos
 (defun dired-insert-subdir-del (element)
   ;; Erase an already present subdir (given by ELEMENT) from buffer.
   ;; Move to that buffer position.  Return a mark-alist.
-  (let ((begin-marker (dired-get-subdir-min element)))
+  (let ((begin-marker (cdr element)))
     (goto-char begin-marker)
     ;; Are at beginning of subdir (and inside it!).  Now determine its end:
     (goto-char (dired-subdir-max))
@@ -2566,7 +2566,7 @@ dired-insert-subdir-doupdate
   ;; BEG-END is the subdir-region (as list of begin and end).
   (if elt				; subdir was already present
       ;; update its position (should actually be unchanged)
-      (set-marker (dired-get-subdir-min elt) (point-marker))
+      (set-marker (cdr elt) (point-marker))
     (dired-alist-add dirname (point-marker)))
   ;; The hook may depend on the subdir-alist containing the just
   ;; inserted subdir, so run it after dired-alist-add:
@@ -2680,7 +2680,7 @@ dired-goto-subdir
   (setq dir (file-name-as-directory dir))
   (let ((elt (assoc dir dired-subdir-alist)))
     (and elt
-	 (goto-char (dired-get-subdir-min elt))
+         (goto-char (cdr elt))
 	 ;; dired-subdir-hidden-p and dired-add-entry depend on point being
 	 ;; at \n after this function succeeds.
 	 (progn (end-of-line)
@@ -2778,7 +2778,7 @@ dired-hide-subdir
 	     (end-pos (1- (dired-get-subdir-max elt)))
 	     buffer-read-only)
 	;; keep header line visible, hide rest
-	(goto-char (dired-get-subdir-min elt))
+	(goto-char (cdr elt))
 	(end-of-line)
 	(if hidden-p
 	    (dired--unhide (point) end-pos)
@@ -2797,14 +2797,14 @@ dired-hide-all
       ;; hide
       (let ((pos (point-max)))		; pos of end of last directory
         (dolist (subdir dired-subdir-alist)
-	  (let ((start (dired-get-subdir-min subdir)) ; pos of prev dir
+          (let ((start (cdr subdir)) ; pos of prev dir
 		(end (save-excursion
 		       (goto-char pos) ; current dir
 		       ;; we're somewhere on current dir's line
 		       (forward-line -1)
 		       (point))))
             (dired--hide start end))
-	  (setq pos (dired-get-subdir-min subdir))))))) ; prev dir gets current dir
+          (setq pos (cdr subdir))))))) ; prev dir gets current dir
 
 ;;;###end dired-ins.el
 
diff --git a/lisp/dired.el b/lisp/dired.el
index 05789a3516..8939ea2d88 100644
--- a/lisp/dired.el
+++ b/lisp/dired.el
@@ -354,8 +354,11 @@ dired-re-dot
 
 ;; The subdirectory names in the next two lists are expanded.
 (defvar dired-subdir-alist nil
-  "Association list of subdirectories and their buffer positions.
-Each subdirectory has an element: (DIRNAME . STARTMARKER).
+  "Alist of listed subdirectories and their buffer positions.
+Alist elements have the form (DIRNAME . STARTMARKER), where
+DIRNAME is the absolute name of the directory and STARTMARKER is
+a marker at the beginning of DIRNAME.
+
 The order of elements is the reverse of the order in the buffer.
 In simple cases, this list contains one element.")
 
@@ -2857,21 +2860,20 @@ dired-get-subdir
     (let ((cur-dir (dired-current-directory)))
       (beginning-of-line)		; alist stores b-o-l positions
       (and (zerop (- (point)
-		     (dired-get-subdir-min (assoc cur-dir
+                     (cdr (assoc cur-dir
 						  dired-subdir-alist))))
 	   cur-dir))))
 
-;; can't use macro,  must be redefinable for other alist format in dired-nstd.
-(defalias 'dired-get-subdir-min 'cdr)
+(define-obsolete-function-alias 'dired-get-subdir-min 'cdr "27.1")
 
 (defun dired-get-subdir-max (elt)
   (save-excursion
-    (goto-char (dired-get-subdir-min elt))
+    (goto-char (cdr elt))
     (dired-subdir-max)))
 
 (defun dired-clear-alist ()
   (while dired-subdir-alist
-    (set-marker (dired-get-subdir-min (car dired-subdir-alist)) nil)
+    (set-marker (cdr (car dired-subdir-alist)) nil)
     (setq dired-subdir-alist (cdr dired-subdir-alist))))
 
 (defun dired-subdir-index (dir)
@@ -2895,7 +2897,7 @@ dired-next-subdir
     ;; nth with negative arg does not return nil but the first element
     (setq index (- (dired-subdir-index this-dir) arg))
     (setq pos (if (>= index 0)
-		  (dired-get-subdir-min (nth index dired-subdir-alist))))
+                  (cdr (nth index dired-subdir-alist))))
     (if pos
 	(progn
 	  (goto-char pos)
@@ -3116,7 +3118,7 @@ dired-current-directory
       (setq elt (car alist)
 	    dir (car elt)
 	    ;; use `<=' (not `<') as subdir line is part of subdir
-	    alist (if (<= (dired-get-subdir-min elt) here)
+	    alist (if (<= (cdr elt) here)
 		      nil		; found
 		    (cdr alist))))
     (if localp
-- 
2.20.1

Message #38 received at 11571 <at> debbugs.gnu.org (full text, mbox):

From: Drew Adams <drew.adams <at> oracle.com>
To: Stefan Kangas <stefan <at> marxist.se>
Cc: Lars Ingebrigtsen <larsi <at> gnus.org>, 11571 <at> debbugs.gnu.org
Subject: RE: bug#11571: 24.0.97; doc string of `dired-get-subdir-min'
Date: Fri, 8 Nov 2019 18:04:01 +0000 (UTC)

> Thanks, that's much better.  I've attached an updated patch with a
> slightly different wording.  If there are no further comments or
> objections, I intend to push this in a couple of days.

OK by me.  Thx.

Message #41 received at 11571 <at> debbugs.gnu.org (full text, mbox):

From: Stefan Kangas <stefan <at> marxist.se>
To: Drew Adams <drew.adams <at> oracle.com>
Cc: Lars Ingebrigtsen <larsi <at> gnus.org>, 11571 <at> debbugs.gnu.org
Subject: Re: bug#11571: 24.0.97; doc string of `dired-get-subdir-min'
Date: Sun, 10 Nov 2019 22:17:35 +0100

close 11571 27.1
thanks

Stefan Kangas <stefan <at> marxist.se> writes:

> If there are no further comments or objections, I intend to push
> this in a couple of days.

Now pushed to master as commit 0154e41b18.  Closing.

Best regards,
Stefan Kangas

Previous Next

GNU bug tracking system
Copyright (C) 1999 Darren O. Benham, 1997,2003 nCipher Corporation Ltd, 1994-97 Ian Jackson.