bug#60470: 26.3; Doc string of `recentf-keep'

[Drew Adams]

> > >the explanation of what "keeping" means.
> > FWIW, I don't see any such explanation, in any doc string.
> Here it is:
> 
>   List of regexps and predicates for filenames kept in the recent list.

That just says "kept" in place of "keep".  The point is
that "keep" can only be understood wrt some non-keeping,
some possibility of removal.  What's missing in the doc
about keeping is _what removal is being prevented_.

For `recentf-exclude', the doc is clear because you can
understand that the exclusion takes place when a file
name would otherwise be _added_ to the list.

But for `recentf-keep' there's nothing equivalent to
let you know what removals would otherwise occur.

It turns out that other than file names protected by
`recentf-keep', names are removed when you kill a buffer
and when "cleanup" occurs.

_That's the answer_, AFAICT.  I suggest that the doc
string say that, or that it refer to some other doc that
says that.  It's not obvious that there is any such
removal of names from the list.  Especially given option
`recentf-exclude', one can easily suppose that that's
all that governs what's in the list.

The only culling of the list that a user is otherwise
aware of is that the list is trimmed to the size of
option `recentf-max-saved-items'.  (The doc doesn't
say that oldest items are dropped, but that's a fair
guess.)

IOW, we don't really tell users about removal of some
file names during "cleanup" or when their buffers are
killed.  This is what I meant by saying that the
meaning of "keep" isn't specified.  It's the removals
that aren't specified.  Once you know what kinds of
removals can take place, "keep", meaning preventing
those removals, is clear.

Please consider trying to make clearer what removals
take place, and how users can control them.

> > Other than searching thus in the code, I see no way for a
> > user to know what "keep" means.  Does it refer to keeping
> > persistently, i.e., not removing when saving?  Does it
> > refer to keeping after the buffer for the file is killed?
> > When a "cleanup" occurs?  "Keep" in what way, wrt what?
> 
> Here's the answer:
>   (define-minor-mode recentf-mode
>     "Toggle keeping track of opened files (Recentf mode).
>   This mode maintains a list of recently opened files and makes it
>   easy to visit them.  The recent files list is automatically saved
>   across Emacs sessions.

I don't know why you show that.  Is it to show that we say
that the list is persisted?  See above - what's missing is
some doc about the culling of the list.

> There's also a short explanation in the user manual:
> 
>  If you enable Recentf mode, with ‘M-x recentf-mode’, Emacs maintains
>  a list of recently opened files.  To open a file from this list, use the
>  ‘M-x recentf-open’ command.  When this mode is enabled, the ‘File’ menu
>  will include a submenu that you can use to visit one of these files.
>  ‘M-x recentf-save-list’ saves the current ‘recentf-list’ to a file, and
>  ‘M-x recentf-edit-list’ edits it.

Doesn't seem relevant to the question I raised.

> > We give users two options for filtering the recentf list.
> > The doc string of one seems clear enough: it prevents
> > some file names _from being added_ to the list.  The
> > other doc string doesn't speak to the presumed _removal_
> > operations for which it prevents removal.  Its predicates
> > and regexps prevent removal of certain files - but what
> > is it that would otherwise cause their removal?
> 
> The original report didn't mention recentf-exclude.

Sorry.  Yes, that's central to the problem.  It's very
easy to think that that option alone controls what file
names will be in the list.  In fact, it controls what
names get _added_ to the list, but there is also list
culling.

To control names that get _culled_ from the list we have
option `recentf-keep'.

> Since you now add it to the issue, I've looked that up:
> 
>   (defcustom recentf-exclude nil
>     "List of regexps and predicates for filenames excluded from the
> recent list.
>   When a filename matches any of the regexps or satisfies any of the
>   predicates it is excluded from the recent list.
>   A predicate is a function that is passed a filename to check and that
>   must return non-nil to exclude it."
> 
> Sounds perfectly clear to me, and the difference between recentf-keep
> and recentf-exclude is also very clear.

See above.  Hopefully it clarifies the problem.  Yes,
"keep" prevents removals from the list.  It's removals
that aren't documented.