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

[Eli Zaretskii <eliz@gnu.org>]

> From: Drew Adams <drew.adams@oracle.com>
> CC: "60470-done@debbugs.gnu.org" <60470-done@debbugs.gnu.org>
> Date: Sun, 1 Jan 2023 22:31:55 +0000
> 
> > I've rad the doc string, and I see nothing wrong with it.  In
> > particular, I did find there the explanation of what "keeping" means.
> > 
> > So I'm closing this bug.
> 
> 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.

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

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.

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

> Would you mind pointing to the part of the doc string
> that you think explains what "keeping" means?  I really
> don't see it.

See above.