GNU bug report logs - #76234
[PATCH] Prefix argument implies recursive for project-remember/forget-under

Previous Next

To add a comment to this bug, you must first unarchive it, by sending
a message to control AT debbugs.gnu.org, with unarchive 76234 in the body.
You can then email your comments to 76234 AT debbugs.gnu.org in the normal way.

Toggle the display of automated, internal messages from the tracker.

Message #5 received at submit <at> debbugs.gnu.org (full text, mbox):

From: Ship Mints <shipmints <at> gmail.com>
To: bug-gnu-emacs <at> gnu.org
Subject: [PATCH] Prefix argument implies recursive for
 project-remember/forget-under
Date: Wed, 12 Feb 2025 12:36:58 -0500

[Message part 1 (text/plain, inline)]

Specifying a universal prefix argument when invoking
'project-remember-projects-under' or 'project-forget-projects-under' now
imply recursive. This makes recursive interactive use easier.

-Stephane

[Message part 2 (text/html, inline)]

[0001-Prefix-argument-implies-recursive-for-project-rememb.patch (application/octet-stream, attachment)]

Message #8 received at 76234 <at> debbugs.gnu.org (full text, mbox):

From: Eli Zaretskii <eliz <at> gnu.org>
To: Ship Mints <shipmints <at> gmail.com>
Cc: 76234 <at> debbugs.gnu.org
Subject: Re: bug#76234: [PATCH] Prefix argument implies recursive for
 project-remember/forget-under
Date: Wed, 12 Feb 2025 21:46:15 +0200

> From: Ship Mints <shipmints <at> gmail.com>
> Date: Wed, 12 Feb 2025 12:36:58 -0500
> 
> Specifying a universal prefix argument when invoking 'project-remember-projects-under' or
> 'project-forget-projects-under' now imply recursive. This makes recursive interactive use easier.

Thanks, please wait for Dmitry to review.

> +*** Prefix argument implies recursive for remember/forget under.
> +Specifying a universal prefix argument when invoking
> +'project-remember-projects-under' or 'project-forget-projects-under' now
> +imply recursive.

The natural way of describing this kind of changes is the other way
around: starting with the command names, not with the prefix argument.
Like this:

  *** 'project-remember/forget-projects-under' can now work recursively.
  The commands 'project-remember-projects-under' and
  'project-forget-projects-under' now find projects in subdirectories,
  recursively, if invoked with a prefix argument.

>  (defun project-remember-projects-under (dir &optional recursive)
>    "Index all projects below a directory DIR.
> -If RECURSIVE is non-nil, recurse into all subdirectories to find
> -more projects.  After finishing, a message is printed summarizing
> -the progress.  The function returns the number of detected
> -projects."
> +If RECURSIVE is non-nil, or with a \\[universal-argument] prefix when
> +called, recurse into all subdirectories to find more projects.  After
> +finishing, a message is printed summarizing the progress.  The function
> +returns the number of detected projects."

This doc string "needs work", and uses passive voice unnecessarily.
Here's a rewording that should be closer to our conventions:

    Remember (i.e., index) projects in directory DIR.
  Interactively, prompt for DIR.
  Optional argument RECURSIVE, if non -nil (interactively, the
  prefix argument) means recurse into subdirectories of DIR to find
  more projects.
  Display a message at the end summarizing what was indexed.
  Return the number of indexed projects.

>  (defun project-forget-projects-under (dir &optional recursive)
>    "Forget all known projects below a directory DIR.
> -If RECURSIVE is non-nil, recurse into all subdirectories to
> -remove all known projects.  After finishing, a message is printed
> -summarizing the progress.  The function returns the number of
> -forgotten projects."
> +If RECURSIVE is non-nil, or with a \\[universal-argument] prefix when
> +called, recurse into all subdirectories to remove all known projects.
> +After finishing, a message is printed summarizing the progress.  The
> +function returns the number of forgotten projects."

Similarly here.

>    (interactive "DDirectory: \nP")
>    (let ((count 0))
> -    (if recursive
> +    (if (or recursive (consp current-prefix-arg))

Any reason why you use consp here (and in the other function)?  AFAIU,
the interactive form will automatically take care of setting the
second argument to the value of the raw prefix arg, so why would you
need to look at the value of current-prefix-arg and discard it if it
is not a cons cell?

Message #11 received at 76234 <at> debbugs.gnu.org (full text, mbox):

From: Ship Mints <shipmints <at> gmail.com>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: 76234 <at> debbugs.gnu.org
Subject: Re: bug#76234: [PATCH] Prefix argument implies recursive for
 project-remember/forget-under
Date: Wed, 12 Feb 2025 14:55:13 -0500

[Message part 1 (text/plain, inline)]

On Wed, Feb 12, 2025 at 2:46 PM Eli Zaretskii <eliz <at> gnu.org> wrote:

> > From: Ship Mints <shipmints <at> gmail.com>
> > Date: Wed, 12 Feb 2025 12:36:58 -0500
> >> +*** Prefix argument implies recursive for remember/forget under.
>
> +Specifying a universal prefix argument when invoking
> > +'project-remember-projects-under' or 'project-forget-projects-under' now
> > +imply recursive.
>
> The natural way of describing this kind of changes is the other way
> around: starting with the command names, not with the prefix argument.
> Like this:
>
>   *** 'project-remember/forget-projects-under' can now work recursively.
>   The commands 'project-remember-projects-under' and
>   'project-forget-projects-under' now find projects in subdirectories,
>   recursively, if invoked with a prefix argument.
>

I'll improve the language. They already did work recursively, but only when
invoked programmatically.

>  (defun project-remember-projects-under (dir &optional recursive)
> >    "Index all projects below a directory DIR.
> > -If RECURSIVE is non-nil, recurse into all subdirectories to find
> > -more projects.  After finishing, a message is printed summarizing
> > -the progress.  The function returns the number of detected
> > -projects."
> > +If RECURSIVE is non-nil, or with a \\[universal-argument] prefix when
> > +called, recurse into all subdirectories to find more projects.  After
> > +finishing, a message is printed summarizing the progress.  The function
> > +returns the number of detected projects."
>
> This doc string "needs work", and uses passive voice unnecessarily.
> Here's a rewording that should be closer to our conventions:
>
>     Remember (i.e., index) projects in directory DIR.
>   Interactively, prompt for DIR.
>   Optional argument RECURSIVE, if non -nil (interactively, the
>   prefix argument) means recurse into subdirectories of DIR to find
>   more projects.
>   Display a message at the end summarizing what was indexed.
>   Return the number of indexed projects.
>

Will do. I'd merely added the interactive detail to what was already there
vs. a wholesale rewrite.

>  (defun project-forget-projects-under (dir &optional recursive)
> >    "Forget all known projects below a directory DIR.
> > -If RECURSIVE is non-nil, recurse into all subdirectories to
> > -remove all known projects.  After finishing, a message is printed
> > -summarizing the progress.  The function returns the number of
> > -forgotten projects."
> > +If RECURSIVE is non-nil, or with a \\[universal-argument] prefix when
> > +called, recurse into all subdirectories to remove all known projects.
> > +After finishing, a message is printed summarizing the progress.  The
> > +function returns the number of forgotten projects."
>
> Similarly here.
>

Ditto.

>    (interactive "DDirectory: \nP")
> >    (let ((count 0))
> > -    (if recursive
> > +    (if (or recursive (consp current-prefix-arg))
>
> Any reason why you use consp here (and in the other function)?  AFAIU,
> the interactive form will automatically take care of setting the
> second argument to the value of the raw prefix arg, so why would you
> need to look at the value of current-prefix-arg and discard it if it
> is not a cons cell?
>

Habit. I'll change it to merely check for non-nil.

Thank you for the thoughtful feedback.

-Stephane

[Message part 2 (text/html, inline)]

Message #14 received at 76234 <at> debbugs.gnu.org (full text, mbox):

From: Ship Mints <shipmints <at> gmail.com>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: 76234 <at> debbugs.gnu.org
Subject: Re: bug#76234: [PATCH] Prefix argument implies recursive for
 project-remember/forget-under
Date: Wed, 12 Feb 2025 15:09:50 -0500

[Message part 1 (text/plain, inline)]

Updated patch attached with improved docs, etc.

On Wed, Feb 12, 2025 at 2:55 PM Ship Mints <shipmints <at> gmail.com> wrote:

> On Wed, Feb 12, 2025 at 2:46 PM Eli Zaretskii <eliz <at> gnu.org> wrote:
>
>> > From: Ship Mints <shipmints <at> gmail.com>
>> > Date: Wed, 12 Feb 2025 12:36:58 -0500
>> >> +*** Prefix argument implies recursive for remember/forget under.
>>
> > +Specifying a universal prefix argument when invoking
>> > +'project-remember-projects-under' or 'project-forget-projects-under'
>> now
>> > +imply recursive.
>>
>> The natural way of describing this kind of changes is the other way
>> around: starting with the command names, not with the prefix argument.
>> Like this:
>>
>>   *** 'project-remember/forget-projects-under' can now work recursively.
>>   The commands 'project-remember-projects-under' and
>>   'project-forget-projects-under' now find projects in subdirectories,
>>   recursively, if invoked with a prefix argument.
>>
>
> I'll improve the language. They already did work recursively, but only
> when invoked programmatically.
>
> >  (defun project-remember-projects-under (dir &optional recursive)
>> >    "Index all projects below a directory DIR.
>> > -If RECURSIVE is non-nil, recurse into all subdirectories to find
>> > -more projects.  After finishing, a message is printed summarizing
>> > -the progress.  The function returns the number of detected
>> > -projects."
>> > +If RECURSIVE is non-nil, or with a \\[universal-argument] prefix when
>> > +called, recurse into all subdirectories to find more projects.  After
>> > +finishing, a message is printed summarizing the progress.  The function
>> > +returns the number of detected projects."
>>
>> This doc string "needs work", and uses passive voice unnecessarily.
>> Here's a rewording that should be closer to our conventions:
>>
>>     Remember (i.e., index) projects in directory DIR.
>>   Interactively, prompt for DIR.
>>   Optional argument RECURSIVE, if non -nil (interactively, the
>>   prefix argument) means recurse into subdirectories of DIR to find
>>   more projects.
>>   Display a message at the end summarizing what was indexed.
>>   Return the number of indexed projects.
>>
>
> Will do. I'd merely added the interactive detail to what was already there
> vs. a wholesale rewrite.
>
> >  (defun project-forget-projects-under (dir &optional recursive)
>> >    "Forget all known projects below a directory DIR.
>> > -If RECURSIVE is non-nil, recurse into all subdirectories to
>> > -remove all known projects.  After finishing, a message is printed
>> > -summarizing the progress.  The function returns the number of
>> > -forgotten projects."
>> > +If RECURSIVE is non-nil, or with a \\[universal-argument] prefix when
>> > +called, recurse into all subdirectories to remove all known projects.
>> > +After finishing, a message is printed summarizing the progress.  The
>> > +function returns the number of forgotten projects."
>>
>> Similarly here.
>>
>
> Ditto.
>
> >    (interactive "DDirectory: \nP")
>> >    (let ((count 0))
>> > -    (if recursive
>> > +    (if (or recursive (consp current-prefix-arg))
>>
>> Any reason why you use consp here (and in the other function)?  AFAIU,
>> the interactive form will automatically take care of setting the
>> second argument to the value of the raw prefix arg, so why would you
>> need to look at the value of current-prefix-arg and discard it if it
>> is not a cons cell?
>>
>
> Habit. I'll change it to merely check for non-nil.
>
> Thank you for the thoughtful feedback.
>
> -Stephane
>

[Message part 2 (text/html, inline)]

[0001-Prefix-argument-implies-recursive-for-project-rememb.patch (application/octet-stream, attachment)]

Message #17 received at 76234 <at> debbugs.gnu.org (full text, mbox):

From: Dmitry Gutov <dmitry <at> gutov.dev>
To: Ship Mints <shipmints <at> gmail.com>, 76234 <at> debbugs.gnu.org
Subject: Re: bug#76234: [PATCH] Prefix argument implies recursive for
 project-remember/forget-under
Date: Wed, 12 Feb 2025 22:14:51 +0200

Hi!

On 12/02/2025 19:36, Ship Mints wrote:
> Specifying a universal prefix argument when invoking 'project-remember- 
> projects-under' or 'project-forget-projects-under' now imply recursive. 
> This makes recursive interactive use easier.

Are you sure that this doesn't work already? The "P" at the end of the 
(interactive ...) spec means that the value of the prefix goes into the 
last argument of the function, which is RECURSIVE.

Both project-remember-projects-under and project-forget-projects-under 
use this instruction.

Message #20 received at 76234 <at> debbugs.gnu.org (full text, mbox):

From: Ship Mints <shipmints <at> gmail.com>
To: Dmitry Gutov <dmitry <at> gutov.dev>
Cc: 76234 <at> debbugs.gnu.org
Subject: Re: bug#76234: [PATCH] Prefix argument implies recursive for
 project-remember/forget-under
Date: Wed, 12 Feb 2025 15:20:50 -0500

[Message part 1 (text/plain, inline)]

You're right. I missed the "P" suffix! The elisp "Using Interactive"
documentation doesn't actually say a suffix works, it mentions only a P
prefix.

Perhaps if it's okay with you, I'll just update the docstrings (and
eliminate NEWS)?

On Wed, Feb 12, 2025 at 3:14 PM Dmitry Gutov <dmitry <at> gutov.dev> wrote:

> Hi!
>
> On 12/02/2025 19:36, Ship Mints wrote:
> > Specifying a universal prefix argument when invoking 'project-remember-
> > projects-under' or 'project-forget-projects-under' now imply recursive.
> > This makes recursive interactive use easier.
>
> Are you sure that this doesn't work already? The "P" at the end of the
> (interactive ...) spec means that the value of the prefix goes into the
> last argument of the function, which is RECURSIVE.
>
> Both project-remember-projects-under and project-forget-projects-under
> use this instruction.
>

[Message part 2 (text/html, inline)]

Message #23 received at 76234 <at> debbugs.gnu.org (full text, mbox):

From: Dmitry Gutov <dmitry <at> gutov.dev>
To: Ship Mints <shipmints <at> gmail.com>
Cc: 76234 <at> debbugs.gnu.org
Subject: Re: bug#76234: [PATCH] Prefix argument implies recursive for
 project-remember/forget-under
Date: Wed, 12 Feb 2025 22:22:11 +0200

On 12/02/2025 22:20, Ship Mints wrote:
> You're right. I missed the "P" suffix! The elisp "Using Interactive" 
> documentation doesn't actually say a suffix works, it mentions only a P 
> prefix.
> 
> Perhaps if it's okay with you, I'll just update the docstrings (and 
> eliminate NEWS)?

Sounds good.

Message #26 received at 76234 <at> debbugs.gnu.org (full text, mbox):

From: Ship Mints <shipmints <at> gmail.com>
To: Dmitry Gutov <dmitry <at> gutov.dev>
Cc: 76234 <at> debbugs.gnu.org
Subject: Re: bug#76234: [PATCH] Prefix argument implies recursive for
 project-remember/forget-under
Date: Wed, 12 Feb 2025 15:39:20 -0500

[Message part 1 (text/plain, inline)]

Docstrings-only patch attached. The interactive spec had a newline in it so
it's not really a P suffix. More coffee.

On Wed, Feb 12, 2025 at 3:22 PM Dmitry Gutov <dmitry <at> gutov.dev> wrote:

> On 12/02/2025 22:20, Ship Mints wrote:
> > You're right. I missed the "P" suffix! The elisp "Using Interactive"
> > documentation doesn't actually say a suffix works, it mentions only a P
> > prefix.
> >
> > Perhaps if it's okay with you, I'll just update the docstrings (and
> > eliminate NEWS)?
>
> Sounds good.
>

[Message part 2 (text/html, inline)]

[0001-Prefix-argument-implies-recursive-for-project-rememb.patch (application/octet-stream, attachment)]

Message #29 received at 76234 <at> debbugs.gnu.org (full text, mbox):

From: Ship Mints <shipmints <at> gmail.com>
To: Dmitry Gutov <dmitry <at> gutov.dev>
Cc: 76234 <at> debbugs.gnu.org
Subject: Re: bug#76234: [PATCH] Prefix argument implies recursive for
 project-remember/forget-under
Date: Wed, 12 Feb 2025 15:46:16 -0500

[Message part 1 (text/plain, inline)]

I think I need to adjust the commit log. One more coming.

On Wed, Feb 12, 2025 at 3:39 PM Ship Mints <shipmints <at> gmail.com> wrote:

> Docstrings-only patch attached. The interactive spec had a newline in it
> so it's not really a P suffix. More coffee.
>
> On Wed, Feb 12, 2025 at 3:22 PM Dmitry Gutov <dmitry <at> gutov.dev> wrote:
>
>> On 12/02/2025 22:20, Ship Mints wrote:
>> > You're right. I missed the "P" suffix! The elisp "Using Interactive"
>> > documentation doesn't actually say a suffix works, it mentions only a P
>> > prefix.
>> >
>> > Perhaps if it's okay with you, I'll just update the docstrings (and
>> > eliminate NEWS)?
>>
>> Sounds good.
>>
>

[Message part 2 (text/html, inline)]

Message #32 received at 76234 <at> debbugs.gnu.org (full text, mbox):

From: Ship Mints <shipmints <at> gmail.com>
To: Dmitry Gutov <dmitry <at> gutov.dev>
Cc: 76234 <at> debbugs.gnu.org
Subject: Re: bug#76234: [PATCH] Prefix argument implies recursive for
 project-remember/forget-under
Date: Wed, 12 Feb 2025 15:48:34 -0500

[Message part 1 (text/plain, inline)]

On Wed, Feb 12, 2025 at 3:46 PM Ship Mints <shipmints <at> gmail.com> wrote:

> I think I need to adjust the commit log. One more coming.
>
> On Wed, Feb 12, 2025 at 3:39 PM Ship Mints <shipmints <at> gmail.com> wrote:
>
>> Docstrings-only patch attached. The interactive spec had a newline in it
>> so it's not really a P suffix. More coffee.
>>
>> On Wed, Feb 12, 2025 at 3:22 PM Dmitry Gutov <dmitry <at> gutov.dev> wrote:
>>
>>> On 12/02/2025 22:20, Ship Mints wrote:
>>> > You're right. I missed the "P" suffix! The elisp "Using Interactive"
>>> > documentation doesn't actually say a suffix works, it mentions only a
>>> P
>>> > prefix.
>>> >
>>> > Perhaps if it's okay with you, I'll just update the docstrings (and
>>> > eliminate NEWS)?
>>>
>>> Sounds good.
>>>
>>

[Message part 2 (text/html, inline)]

[0001-Prefix-argument-implies-recursive-for-project-rememb.patch (application/octet-stream, attachment)]

Message #35 received at 76234 <at> debbugs.gnu.org (full text, mbox):

From: Dmitry Gutov <dmitry <at> gutov.dev>
To: Ship Mints <shipmints <at> gmail.com>
Cc: 76234 <at> debbugs.gnu.org
Subject: Re: bug#76234: [PATCH] Prefix argument implies recursive for
 project-remember/forget-under
Date: Thu, 13 Feb 2025 02:17:16 +0200

On 12/02/2025 22:48, Ship Mints wrote:
>  From 97c6473833215f882c8ffed0814e4b2263503085 Mon Sep 17 00:00:00 2001 
> From: shipmints <shipmints <at> gmail.com> Date: Wed, 12 Feb 2025 12:34:13 
> -0500 Subject: [PATCH] Prefix argument implies recursive for project- 
> remember/forget-under

Thanks, I've taken most of the proposal but tried to keep the orginal 
terms. Also avoided saying "index" because it can imply indexing the 
contents of the project as well (such as the lists of files, which we 
don't cache).

Check this out: 
https://git.savannah.gnu.org/cgit/emacs.git/commit/?id=6077bbfc3d4a4aa042b364d31dd681e9f7ab7f30

Message #38 received at 76234 <at> debbugs.gnu.org (full text, mbox):

From: Ship Mints <shipmints <at> gmail.com>
To: Dmitry Gutov <dmitry <at> gutov.dev>
Cc: 76234 <at> debbugs.gnu.org
Subject: Re: bug#76234: [PATCH] Prefix argument implies recursive for
 project-remember/forget-under
Date: Wed, 12 Feb 2025 19:25:12 -0500

[Message part 1 (text/plain, inline)]

LGTM, thanks

On Wed, Feb 12, 2025 at 7:17 PM Dmitry Gutov <dmitry <at> gutov.dev> wrote:

> On 12/02/2025 22:48, Ship Mints wrote:
> >  From 97c6473833215f882c8ffed0814e4b2263503085 Mon Sep 17 00:00:00 2001
> > From: shipmints <shipmints <at> gmail.com> Date: Wed, 12 Feb 2025 12:34:13
> > -0500 Subject: [PATCH] Prefix argument implies recursive for project-
> > remember/forget-under
>
> Thanks, I've taken most of the proposal but tried to keep the orginal
> terms. Also avoided saying "index" because it can imply indexing the
> contents of the project as well (such as the lists of files, which we
> don't cache).
>
> Check this out:
>
> https://git.savannah.gnu.org/cgit/emacs.git/commit/?id=6077bbfc3d4a4aa042b364d31dd681e9f7ab7f30
>

[Message part 2 (text/html, inline)]

Message #43 received at 76234-done <at> debbugs.gnu.org (full text, mbox):

From: Dmitry Gutov <dmitry <at> gutov.dev>
To: Ship Mints <shipmints <at> gmail.com>
Cc: 76234-done <at> debbugs.gnu.org
Subject: Re: bug#76234: [PATCH] Prefix argument implies recursive for
 project-remember/forget-under
Date: Thu, 13 Feb 2025 02:30:08 +0200

On 13/02/2025 02:25, Ship Mints wrote:
> LGTM, thanks

Marking as resolved.

Message #46 received at 76234 <at> debbugs.gnu.org (full text, mbox):

From: Eli Zaretskii <eliz <at> gnu.org>
To: Ship Mints <shipmints <at> gmail.com>
Cc: dmitry <at> gutov.dev, 76234 <at> debbugs.gnu.org
Subject: Re: bug#76234: [PATCH] Prefix argument implies recursive for
 project-remember/forget-under
Date: Thu, 13 Feb 2025 08:10:18 +0200

> Cc: 76234 <at> debbugs.gnu.org
> From: Ship Mints <shipmints <at> gmail.com>
> Date: Wed, 12 Feb 2025 15:48:34 -0500
> 
> From 97c6473833215f882c8ffed0814e4b2263503085 Mon Sep 17 00:00:00 2001
> From: shipmints <shipmints <at> gmail.com>
> Date: Wed, 12 Feb 2025 12:34:13 -0500
> Subject: [PATCH] Prefix argument implies recursive for
>  project-remember/forget-under
> 
> * lisp/progmodes/project.el:
> (project-remember-projects-under project-forget-projects-under):
> Amend docstring to include a prefix argument implies recursive.

One other nit: once the bug number is known (which it is starting from
the second submission), please always include the bug reference in the
commit log message.  This makes the job of the person who installs
your changes easier, because instead of just "git am", he/she needs to
run "git commit --amend" to fix the log message (if he/she remembers
doing that).

References to bug numbers in log messages are important because the
bug discussions include important information that will be needed
years later if someone wants to understand better why we made a
change.

Thanks.

Message #49 received at 76234 <at> debbugs.gnu.org (full text, mbox):

From: Eli Zaretskii <eliz <at> gnu.org>
To: Dmitry Gutov <dmitry <at> gutov.dev>
Cc: shipmints <at> gmail.com, 76234 <at> debbugs.gnu.org
Subject: Re: bug#76234: [PATCH] Prefix argument implies recursive for
 project-remember/forget-under
Date: Thu, 13 Feb 2025 09:28:01 +0200

> Cc: 76234 <at> debbugs.gnu.org
> Date: Thu, 13 Feb 2025 02:17:16 +0200
> From: Dmitry Gutov <dmitry <at> gutov.dev>
> 
> On 12/02/2025 22:48, Ship Mints wrote:
> >  From 97c6473833215f882c8ffed0814e4b2263503085 Mon Sep 17 00:00:00 2001 
> > From: shipmints <shipmints <at> gmail.com> Date: Wed, 12 Feb 2025 12:34:13 
> > -0500 Subject: [PATCH] Prefix argument implies recursive for project- 
> > remember/forget-under
> 
> Thanks, I've taken most of the proposal but tried to keep the orginal 
> terms. Also avoided saying "index" because it can imply indexing the 
> contents of the project as well (such as the lists of files, which we 
> don't cache).
> 
> Check this out: 
> https://git.savannah.gnu.org/cgit/emacs.git/commit/?id=6077bbfc3d4a4aa042b364d31dd681e9f7ab7f30

IMO, this:

  +Display a message at the end summarizing what was found.
  +Return the number of detected projects."

contrasts strangely with this:

  +Display a message at the end summarizing what was forgotten.
  +Return the number of forgotten projects."

If we say "forgotten" in the latter case, why do we say "found" (and
not, for example, "remembered" or "new" or "added") in the former?
Doesn't the latter case also "find" projects?

That's one reason why in my proposal I used "indexed".

Also, this:

  Remember projects below a directory DIR.

is in contrast with this:

  Forget all known projects below a directory DIR.

Why doesn't the former say "all the projects", but the latter does?

And a final nit: should we somehow explain in the doc string what it
means to "remember" and to "forget" in this context?

Message #52 received at 76234 <at> debbugs.gnu.org (full text, mbox):

From: Dmitry Gutov <dmitry <at> gutov.dev>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: shipmints <at> gmail.com, 76234 <at> debbugs.gnu.org
Subject: Re: bug#76234: [PATCH] Prefix argument implies recursive for
 project-remember/forget-under
Date: Fri, 14 Feb 2025 05:58:38 +0200

On 13/02/2025 09:28, Eli Zaretskii wrote:

>> Check this out:
>> https://git.savannah.gnu.org/cgit/emacs.git/commit/?id=6077bbfc3d4a4aa042b364d31dd681e9f7ab7f30
> 
> IMO, this:
> 
>    +Display a message at the end summarizing what was found.
>    +Return the number of detected projects."
> 
> contrasts strangely with this:
> 
>    +Display a message at the end summarizing what was forgotten.
>    +Return the number of forgotten projects."
> 
> If we say "forgotten" in the latter case, why do we say "found" (and
> not, for example, "remembered" or "new" or "added") in the former?
> Doesn't the latter case also "find" projects?

It wouldn't include the project that were found in the second scan but 
weren't "known" previously.

Probably a minor distinction, but that's my reasoning for this anyway.

Perhaps we could change it from "number of forgotten project" to "number 
of projects we forgot"? Subtle difference.

> That's one reason why in my proposal I used "indexed".
> 
> Also, this:
> 
>    Remember projects below a directory DIR.
> 
> is in contrast with this:
> 
>    Forget all known projects below a directory DIR.
> 
> Why doesn't the former say "all the projects", but the latter does?

Good question, I think the latter should not have "all" as well. I think 
"all" implies the recursive search, at least in some readings.

> And a final nit: should we somehow explain in the doc string what it
> means to "remember" and to "forget" in this context?

Not sure, but we could say that it means adding to and removing from the 
"known projects list".

Message #55 received at 76234 <at> debbugs.gnu.org (full text, mbox):

From: Eli Zaretskii <eliz <at> gnu.org>
To: Dmitry Gutov <dmitry <at> gutov.dev>
Cc: shipmints <at> gmail.com, 76234 <at> debbugs.gnu.org
Subject: Re: bug#76234: [PATCH] Prefix argument implies recursive for
 project-remember/forget-under
Date: Fri, 14 Feb 2025 10:30:05 +0200

> Date: Fri, 14 Feb 2025 05:58:38 +0200
> Cc: shipmints <at> gmail.com, 76234 <at> debbugs.gnu.org
> From: Dmitry Gutov <dmitry <at> gutov.dev>
> 
> On 13/02/2025 09:28, Eli Zaretskii wrote:
> 
> > IMO, this:
> > 
> >    +Display a message at the end summarizing what was found.
> >    +Return the number of detected projects."
> > 
> > contrasts strangely with this:
> > 
> >    +Display a message at the end summarizing what was forgotten.
> >    +Return the number of forgotten projects."
> > 
> > If we say "forgotten" in the latter case, why do we say "found" (and
> > not, for example, "remembered" or "new" or "added") in the former?
> > Doesn't the latter case also "find" projects?
> 
> It wouldn't include the project that were found in the second scan but 
> weren't "known" previously.

So you mean the number of previously-known projects that will no
longer be known?

In that case, should the doc string for project-remember say something
like "the number of newly-remembered projects"?

> > Also, this:
> > 
> >    Remember projects below a directory DIR.
> > 
> > is in contrast with this:
> > 
> >    Forget all known projects below a directory DIR.
> > 
> > Why doesn't the former say "all the projects", but the latter does?
> 
> Good question, I think the latter should not have "all" as well. I think 
> "all" implies the recursive search, at least in some readings.

And maybe "below" should be "in", so as not to hint on recursive
descent?

> > And a final nit: should we somehow explain in the doc string what it
> > means to "remember" and to "forget" in this context?
> 
> Not sure, but we could say that it means adding to and removing from the 
> "known projects list".

I think adding the reference to the list would be good.

Message #58 received at 76234 <at> debbugs.gnu.org (full text, mbox):

From: Dmitry Gutov <dmitry <at> gutov.dev>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: shipmints <at> gmail.com, 76234 <at> debbugs.gnu.org
Subject: Re: bug#76234: [PATCH] Prefix argument implies recursive for
 project-remember/forget-under
Date: Mon, 17 Feb 2025 05:27:56 +0200

On 14/02/2025 10:30, Eli Zaretskii wrote:
>> Date: Fri, 14 Feb 2025 05:58:38 +0200
>> Cc: shipmints <at> gmail.com, 76234 <at> debbugs.gnu.org
>> From: Dmitry Gutov <dmitry <at> gutov.dev>
>>
>> On 13/02/2025 09:28, Eli Zaretskii wrote:
>>
>>> IMO, this:
>>>
>>>     +Display a message at the end summarizing what was found.
>>>     +Return the number of detected projects."
>>>
>>> contrasts strangely with this:
>>>
>>>     +Display a message at the end summarizing what was forgotten.
>>>     +Return the number of forgotten projects."
>>>
>>> If we say "forgotten" in the latter case, why do we say "found" (and
>>> not, for example, "remembered" or "new" or "added") in the former?
>>> Doesn't the latter case also "find" projects?
>>
>> It wouldn't include the project that were found in the second scan but
>> weren't "known" previously.
> 
> So you mean the number of previously-known projects that will no
> longer be known?

Yep.

> In that case, should the doc string for project-remember say something
> like "the number of newly-remembered projects"?

Sure.

>>> Also, this:
>>>
>>>     Remember projects below a directory DIR.
>>>
>>> is in contrast with this:
>>>
>>>     Forget all known projects below a directory DIR.
>>>
>>> Why doesn't the former say "all the projects", but the latter does?
>>
>> Good question, I think the latter should not have "all" as well. I think
>> "all" implies the recursive search, at least in some readings.
> 
> And maybe "below" should be "in", so as not to hint on recursive
> descent?

In my reading these mean the same (as opposed to "directly below"), but 
if it helps from your POV - very good.

>>> And a final nit: should we somehow explain in the doc string what it
>>> means to "remember" and to "forget" in this context?
>>
>> Not sure, but we could say that it means adding to and removing from the
>> "known projects list".
> 
> I think adding the reference to the list would be good.

Hmm, I'm not sure what would be a good approach which would not restate 
something already obvious from the text a second time. We could abolish 
both verbs from the docstring ("remember" and "forget"), saying instead 
"add to known projects" and "remove from known projects" - but the 
result would be longer on multiple lines. Longer text can be inherently 
less clear.

Previous Next

GNU bug tracking system
Copyright (C) 1999 Darren O. Benham, 1997,2003 nCipher Corporation Ltd, 1994-97 Ian Jackson.