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

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

[Drew Adams]

Please consider saying in the doc string what it means to "keep" a file
name in the recent list.

The doc string goes into what it means to be a predicate, but it says
nothing, really, about what this option means/does, because it tells you
nothing about what "keeping" amounts to.

Also, a nit: when used as a noun phrase, "filename" should be "file
name".  (When used as an adjective before a noun phrase it should be
"file-name".  We use (should use) "filename" only in some function
etc. names, not in the doc.


In GNU Emacs 26.3 (build 1, x86_64-w64-mingw32)
 of 2019-08-29
Repository revision: 96dd0196c28bc36779584e47fffcca433c9309cd
Windowing system distributor `Microsoft Corp.', version 10.0.19044
Configured using:
 `configure --without-dbus --host=x86_64-w64-mingw32
 --without-compress-install 'CFLAGS=-O2 -static -g3''

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

[Eli Zaretskii]

> From: Drew Adams <drew.adams@oracle.com>
> Date: Sun, 1 Jan 2023 16:39:40 +0000
> 
> Please consider saying in the doc string what it means to "keep" a file
> name in the recent list.
> 
> The doc string goes into what it means to be a predicate, but it says
> nothing, really, about what this option means/does, because it tells you
> nothing about what "keeping" amounts to.

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.

> Also, a nit: when used as a noun phrase, "filename" should be "file
> name".  (When used as an adjective before a noun phrase it should be
> "file-name".  We use (should use) "filename" only in some function
> etc. names, not in the doc.

Noted.

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

[Drew Adams]

> > Please consider saying in the doc string what it 
> > means to "keep" a file name in the recent list.
> >
> > The doc string goes into what it means to be a
> > predicate, but it says nothing, really, about
> > what this option means/does, because it tells
> > you nothing about what "keeping" amounts to.
> 
> 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.

Following the code - e.g. the places where `recentf-keep-p'
is used, I can see that the use of `recentf-keep' differs
from the use of `recentf-exclude' (besides filtering in
instead of out) in that `recentf-keep' filtering happens
when you kill a buffer (via `recentf-track-closed-file')
or whether "cleanup" occurs.  That info is missing from
the option doc string.

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?

I think a user will wonder about this.  And in particular
I don't see anything in the doc string of `recentf-keep'
that speaks to it - nothing that makes you not wonder how
this differs from the use of option `recentf-exclude'
(besides filtering in the opposite sense).

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?

You can figure it out by either (1) looking at the code
or (2) checking _all_ of the doc to get a list of the
possible removal events/operations/occurrences, and
surmising that `recentf-keep' takes effect for all of
them.  But I don't see how you can figure it out just
by looking at the `recentf-keep' doc string.

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

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

[Eli Zaretskii]

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

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.

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

[Eli Zaretskii]

> From: Drew Adams <drew.adams@oracle.com>
> CC: "60470-done@debbugs.gnu.org" <60470-done@debbugs.gnu.org>
> Date: Mon, 2 Jan 2023 17:48:49 +0000
> 
> > > >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".

No, it says "kept in the recent list".  And what that list is should
be clear from the rest of the documentation of the mode.

Anyway, there's nothing else to discuss here, and the bug is already
closed.