bug#11571: 24.0.97; doc string of `dired-get-subdir-min'

bug#11571: 24.0.97; doc string of `dired-get-subdir-min'

[Drew Adams]

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'
 

bug#11571: 24.0.97; doc string of `dired-get-subdir-min'

[Drew Adams]

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.

bug#11571: 24.0.97; doc string of `dired-get-subdir-min'

[Drew Adams]

ping

bug#11571: 24.0.97; doc string of `dired-get-subdir-min'

[Lars Ingebrigtsen]

"Drew Adams" <drew.adams@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/

bug#11571: 24.0.97; doc string of `dired-get-subdir-min'

[Drew Adams]

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

bug#11571: 24.0.97; doc string of `dired-get-subdir-min'

[Stefan Kangas]

[-- Attachment #1: Type: text/plain, Size: 1268 bytes --]

Lars Ingebrigtsen <larsi@gnus.org> writes:

> "Drew Adams" <drew.adams@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


[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: 0001-Make-dired-get-subdir-min-obsolete.patch --]
[-- Type: text/x-diff, Size: 5623 bytes --]

From 1a6c799863380e5986f26a9c8fd9d3fc98241bb1 Mon Sep 17 00:00:00 2001
From: Stefan Kangas <stefankangas@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

bug#11571: 24.0.97; doc string of `dired-get-subdir-min'

[Drew Adams]

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

bug#11571: 24.0.97; doc string of `dired-get-subdir-min'

[Lars Ingebrigtsen]

Stefan Kangas <stefan@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

bug#11571: 24.0.97; doc string of `dired-get-subdir-min'

[Stefan Kangas]

Drew Adams <drew.adams@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

bug#11571: 24.0.97; doc string of `dired-get-subdir-min'

[Drew Adams]

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

bug#11571: 24.0.97; doc string of `dired-get-subdir-min'

[Stefan Kangas]

[-- Attachment #1: Type: text/plain, Size: 1427 bytes --]

Drew Adams <drew.adams@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


[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: 0001-Make-dired-get-subdir-min-obsolete.patch --]
[-- Type: text/x-diff, Size: 6347 bytes --]

From 181fea4507be10c80981ff7fd650f7d6b82de039 Mon Sep 17 00:00:00 2001
From: Stefan Kangas <stefankangas@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

bug#11571: 24.0.97; doc string of `dired-get-subdir-min'

[Drew Adams]

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

bug#11571: 24.0.97; doc string of `dired-get-subdir-min'

[Stefan Kangas]

close 11571 27.1
thanks

Stefan Kangas <stefan@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