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

From: Drew Adams <[email-masked]>
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.