GNU bug report logs - #72915
Docstrings of add-hook and remove-hook improvement?

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 72915 in the body.
You can then email your comments to 72915 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: Tomas Nordin <tomasn <at> posteo.net>
To: bug-gnu-emacs <at> gnu.org
Subject: Docstrings of add-hook and remove-hook improvement?
Date: Sat, 31 Aug 2024 12:36:22 +0000

Hello List

In bug#70820 August 14, Stefan mentions that it is a common confusion to
think of the functions in a hook as hooks. It got my attention because I
belong to the confused ones every second year or so adding or removing
functions from a hook.

I suggest the provided patch as a small improvement of the function
documentation of add-hook and remove-hook. Maybe it doesn't mitigate the
confusion mentioned that much, but it seem to align better with the
manual as I read it.

What do you think?

In add-hook doc, lift up the paragraph about HOOK and FUNCTION and
remove the mention about first setting the HOOK to nil. I think that is
something internal to the add-hook function and not relevant to the
programmer calling the add-hook function? And then say that the
resulting hook will be a list both when the HOOK symbol is void or a
single function.

In remove-hook, stick to the notion that a hook contain functions to
run, not hooks.

This notion though is a bit confusing in relation to the names of those
functions, but that's another story I guess.

The following on top of emacs-30.

diff --git a/lisp/subr.el b/lisp/subr.el
index 28ba30f584e..e60c4119c60 100644
--- a/lisp/subr.el
+++ b/lisp/subr.el
@@ -2090,6 +2090,10 @@ add-hook
   "Add to the value of HOOK the function FUNCTION.
 FUNCTION is not added if already present.
 
+HOOK should be a symbol.  If HOOK is void, or if HOOK's value is a
+single function, it is changed to a list of functions (containing only
+FUNCTION in the void case).
+
 The place where the function is added depends on the DEPTH
 parameter.  DEPTH defaults to 0.  By convention, it should be
 a number between -100 and 100 where 100 means that the function
@@ -2108,10 +2112,6 @@ add-hook
 buffer-local value.  That acts as a flag to run the hook
 functions of the global value as well as in the local value.
 
-HOOK should be a symbol.  If HOOK is void, it is first set to
-nil.  If HOOK's value is a single function, it is changed to a
-list of functions.
-
 FUNCTION may be any valid function, but it's recommended to use a
 function symbol and not a lambda form.  Using a symbol will
 ensure that the function is not re-added if the function is
@@ -2179,7 +2179,7 @@ remove-hook
   "Remove from the value of HOOK the function FUNCTION.
 HOOK should be a symbol, and FUNCTION may be any valid function.  If
 FUNCTION isn't the value of HOOK, or, if FUNCTION doesn't appear in the
-list of hooks to run in HOOK, then nothing is done.  See `add-hook'.
+list of functions to run in HOOK, then nothing is done.  See `add-hook'.
 
 The optional third argument, LOCAL, if non-nil, says to modify
 the hook's buffer-local value rather than its default value.

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

From: Stefan Kangas <stefankangas <at> gmail.com>
To: Tomas Nordin <tomasn <at> posteo.net>, 72915 <at> debbugs.gnu.org
Subject: Re: bug#72915: Docstrings of add-hook and remove-hook improvement?
Date: Sat, 31 Aug 2024 15:35:44 -0700

Tomas Nordin <tomasn <at> posteo.net> writes:

> diff --git a/lisp/subr.el b/lisp/subr.el
> index 28ba30f584e..e60c4119c60 100644
> --- a/lisp/subr.el
> +++ b/lisp/subr.el
> @@ -2090,6 +2090,10 @@ add-hook
>    "Add to the value of HOOK the function FUNCTION.
>  FUNCTION is not added if already present.
>
> +HOOK should be a symbol.  If HOOK is void, or if HOOK's value is a
> +single function, it is changed to a list of functions (containing only
> +FUNCTION in the void case).
> +
>  The place where the function is added depends on the DEPTH
>  parameter.  DEPTH defaults to 0.  By convention, it should be
>  a number between -100 and 100 where 100 means that the function
> @@ -2108,10 +2112,6 @@ add-hook
>  buffer-local value.  That acts as a flag to run the hook
>  functions of the global value as well as in the local value.
>
> -HOOK should be a symbol.  If HOOK is void, it is first set to
> -nil.  If HOOK's value is a single function, it is changed to a
> -list of functions.
> -
>  FUNCTION may be any valid function, but it's recommended to use a
>  function symbol and not a lambda form.  Using a symbol will
>  ensure that the function is not re-added if the function is
> @@ -2179,7 +2179,7 @@ remove-hook
>    "Remove from the value of HOOK the function FUNCTION.
>  HOOK should be a symbol, and FUNCTION may be any valid function.  If
>  FUNCTION isn't the value of HOOK, or, if FUNCTION doesn't appear in the
> -list of hooks to run in HOOK, then nothing is done.  See `add-hook'.
> +list of functions to run in HOOK, then nothing is done.  See `add-hook'.
>
>  The optional third argument, LOCAL, if non-nil, says to modify
>  the hook's buffer-local value rather than its default value.

LGTM.

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

From: Eli Zaretskii <eliz <at> gnu.org>
To: Tomas Nordin <tomasn <at> posteo.net>, Stefan Monnier <monnier <at> iro.umontreal.ca>
Cc: 72915 <at> debbugs.gnu.org
Subject: Re: bug#72915: Docstrings of add-hook and remove-hook improvement?
Date: Sun, 01 Sep 2024 07:57:00 +0300

> From: Tomas Nordin <tomasn <at> posteo.net>
> Date: Sat, 31 Aug 2024 12:36:22 +0000
> 
> The following on top of emacs-30.
> 
> diff --git a/lisp/subr.el b/lisp/subr.el
> index 28ba30f584e..e60c4119c60 100644
> --- a/lisp/subr.el
> +++ b/lisp/subr.el
> @@ -2090,6 +2090,10 @@ add-hook
>    "Add to the value of HOOK the function FUNCTION.
>  FUNCTION is not added if already present.
>  
> +HOOK should be a symbol.  If HOOK is void, or if HOOK's value is a
> +single function, it is changed to a list of functions (containing only
> +FUNCTION in the void case).
> +
>  The place where the function is added depends on the DEPTH
>  parameter.  DEPTH defaults to 0.  By convention, it should be
>  a number between -100 and 100 where 100 means that the function
> @@ -2108,10 +2112,6 @@ add-hook
>  buffer-local value.  That acts as a flag to run the hook
>  functions of the global value as well as in the local value.
>  
> -HOOK should be a symbol.  If HOOK is void, it is first set to
> -nil.  If HOOK's value is a single function, it is changed to a
> -list of functions.
> -

Is the bit about setting HOOK to nil incorrect?  Because the new text
drops that part.

>    "Remove from the value of HOOK the function FUNCTION.
>  HOOK should be a symbol, and FUNCTION may be any valid function.  If
>  FUNCTION isn't the value of HOOK, or, if FUNCTION doesn't appear in the
> -list of hooks to run in HOOK, then nothing is done.  See `add-hook'.
> +list of functions to run in HOOK, then nothing is done.  See `add-hook'.

"list of functions to run in HOOK" is ambiguous wrt what "in HOOK"
refers to.  I would rephrase:

  If FUNCTION is not the value of HOOK and is not a member of the list
  that is the value of HOOK, do nothing.

(This also avoids passive tense and clarifies the wording in other
aspects.)

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

From: Stefan Kangas <stefankangas <at> gmail.com>
To: Eli Zaretskii <eliz <at> gnu.org>, Tomas Nordin <tomasn <at> posteo.net>, 
 Stefan Monnier <monnier <at> iro.umontreal.ca>
Cc: 72915 <at> debbugs.gnu.org
Subject: Re: bug#72915: Docstrings of add-hook and remove-hook improvement?
Date: Sun, 1 Sep 2024 00:15:17 -0700

Eli Zaretskii <eliz <at> gnu.org> writes:

>> From: Tomas Nordin <tomasn <at> posteo.net>
>> Date: Sat, 31 Aug 2024 12:36:22 +0000
>>
>> The following on top of emacs-30.
>>
>> diff --git a/lisp/subr.el b/lisp/subr.el
>> index 28ba30f584e..e60c4119c60 100644
>> --- a/lisp/subr.el
>> +++ b/lisp/subr.el
>> @@ -2090,6 +2090,10 @@ add-hook
>>    "Add to the value of HOOK the function FUNCTION.
>>  FUNCTION is not added if already present.
>>
>> +HOOK should be a symbol.  If HOOK is void, or if HOOK's value is a
>> +single function, it is changed to a list of functions (containing only
>> +FUNCTION in the void case).
>> +
>>  The place where the function is added depends on the DEPTH
>>  parameter.  DEPTH defaults to 0.  By convention, it should be
>>  a number between -100 and 100 where 100 means that the function
>> @@ -2108,10 +2112,6 @@ add-hook
>>  buffer-local value.  That acts as a flag to run the hook
>>  functions of the global value as well as in the local value.
>>
>> -HOOK should be a symbol.  If HOOK is void, it is first set to
>> -nil.  If HOOK's value is a single function, it is changed to a
>> -list of functions.
>> -
>
> Is the bit about setting HOOK to nil incorrect?  Because the new text
> drops that part.

It makes no difference if HOOK is "first" set to nil from the POV of the
end user, I think.  The end result is that HOOK will be a list of
functions.

IOW, the point here is that `add-hook` will work even if HOOK is void,
and that aspect is preserved in the above change.

>
>>    "Remove from the value of HOOK the function FUNCTION.
>>  HOOK should be a symbol, and FUNCTION may be any valid function.  If
>>  FUNCTION isn't the value of HOOK, or, if FUNCTION doesn't appear in the
>> -list of hooks to run in HOOK, then nothing is done.  See `add-hook'.
>> +list of functions to run in HOOK, then nothing is done.  See `add-hook'.
>
> "list of functions to run in HOOK" is ambiguous wrt what "in HOOK"
> refers to.  I would rephrase:
>
>   If FUNCTION is not the value of HOOK and is not a member of the list
>   that is the value of HOOK, do nothing.

While the original is not ideal, I don't find this to be an improvement.
Sorry.  I'd suggest trying to reformulate it again, to make it more
direct and avoid repeating the phrase "the value of".

The wording in the manual is probably all that is needed here:

    This function removes FUNCTION from the hook variable HOOK.

In other words, we either get to assume that the user knows what a hook
is, or we can point the user to the relevant manual section to read
about it.

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

From: Stefan Kangas <stefankangas <at> gmail.com>
To: Eli Zaretskii <eliz <at> gnu.org>, Tomas Nordin <tomasn <at> posteo.net>, 
 Stefan Monnier <monnier <at> iro.umontreal.ca>
Cc: 72915 <at> debbugs.gnu.org
Subject: Re: bug#72915: Docstrings of add-hook and remove-hook improvement?
Date: Sun, 1 Sep 2024 00:18:38 -0700

Stefan Kangas <stefankangas <at> gmail.com> writes:

> The wording in the manual is probably all that is needed here:
>
>     This function removes FUNCTION from the hook variable HOOK.

BTW.  Here's another idea:

    If HOOK is a list of functions, remove FUNCTION from that list.

    If HOOK is equal to FUNCTION, set HOOK to nil.

    Otherwise do nothing.

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

From: Stefan Monnier <monnier <at> iro.umontreal.ca>
To: Stefan Kangas <stefankangas <at> gmail.com>
Cc: Eli Zaretskii <eliz <at> gnu.org>, Tomas Nordin <tomasn <at> posteo.net>,
 72915 <at> debbugs.gnu.org
Subject: Re: bug#72915: Docstrings of add-hook and remove-hook improvement?
Date: Sun, 01 Sep 2024 10:17:43 -0400

>> The wording in the manual is probably all that is needed here:
>>
>>     This function removes FUNCTION from the hook variable HOOK.
>
> BTW.  Here's another idea:
>
>     If HOOK is a list of functions, remove FUNCTION from that list.
>
>     If HOOK is equal to FUNCTION, set HOOK to nil.
>
>     Otherwise do nothing.

Nit pick: a hook *is* not a function or a list of functions.
It only *holds* such things.


        Stefan

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

From: Stefan Monnier <monnier <at> iro.umontreal.ca>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: Tomas Nordin <tomasn <at> posteo.net>, 72915 <at> debbugs.gnu.org
Subject: Re: bug#72915: Docstrings of add-hook and remove-hook improvement?
Date: Sun, 01 Sep 2024 10:34:19 -0400

>> -HOOK should be a symbol.  If HOOK is void, it is first set to
>> -nil.  If HOOK's value is a single function, it is changed to a
>> -list of functions.
> Is the bit about setting HOOK to nil incorrect?  Because the new text
> drops that part.

That's an internal detail that's not observable to the caller anyway.

>>    "Remove from the value of HOOK the function FUNCTION.
>>  HOOK should be a symbol, and FUNCTION may be any valid function.  If
>>  FUNCTION isn't the value of HOOK, or, if FUNCTION doesn't appear in the
>> -list of hooks to run in HOOK, then nothing is done.  See `add-hook'.
>> +list of functions to run in HOOK, then nothing is done.  See `add-hook'.
>
> "list of functions to run in HOOK" is ambiguous wrt what "in HOOK"
> refers to.  I would rephrase:
>
>   If FUNCTION is not the value of HOOK and is not a member of the list
>   that is the value of HOOK, do nothing.

Maybe we can simplify the wording a bit by focusing less about whether
the hook's value is a function or a list of functions, and talking about
the "sequence" or "set" of functions (which can be represented by
a list of functions or a function)?

Something like:

      "Remove FUNCTION from HOOK's functions.
    HOOK should be a symbol, and FUNCTION may be any valid function.
    Does nothing if HOOK does not currently contain FUNCTION.
    Compares functions with `equal`, which means that it can be
    slow if FUNCTION is not a symbol.  See `add-hook'.



- Stefan

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

From: Tomas Nordin <tomasn <at> posteo.net>
To: Stefan Kangas <stefankangas <at> gmail.com>, Eli Zaretskii <eliz <at> gnu.org>,
 Stefan Monnier <monnier <at> iro.umontreal.ca>
Cc: 72915 <at> debbugs.gnu.org
Subject: Re: bug#72915: Docstrings of add-hook and remove-hook improvement?
Date: Sun, 01 Sep 2024 15:47:36 +0000

Stefan Kangas <stefankangas <at> gmail.com> writes:

> Stefan Kangas <stefankangas <at> gmail.com> writes:
>
>> The wording in the manual is probably all that is needed here:
>>
>>     This function removes FUNCTION from the hook variable HOOK.
>
> BTW.  Here's another idea:
>
>     If HOOK is a list of functions, remove FUNCTION from that list.
>
>     If HOOK is equal to FUNCTION, set HOOK to nil.
>
>     Otherwise do nothing.

I like that, adjusted maybe to respect Stefan M's nitpick:

If HOOK's value is a list of functions, remove FUNCTION from that list.
If HOOK's value is FUNCTION, set HOOK to nil.
Otherwise do nothing.

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

From: Stefan Kangas <stefankangas <at> gmail.com>
To: Tomas Nordin <tomasn <at> posteo.net>, Eli Zaretskii <eliz <at> gnu.org>, 
 Stefan Monnier <monnier <at> iro.umontreal.ca>
Cc: 72915 <at> debbugs.gnu.org
Subject: Re: bug#72915: Docstrings of add-hook and remove-hook improvement?
Date: Sat, 14 Sep 2024 09:31:41 -0400

Tomas Nordin <tomasn <at> posteo.net> writes:

> Stefan Kangas <stefankangas <at> gmail.com> writes:
>
>> Stefan Kangas <stefankangas <at> gmail.com> writes:
>>
>>> The wording in the manual is probably all that is needed here:
>>>
>>>     This function removes FUNCTION from the hook variable HOOK.
>>
>> BTW.  Here's another idea:
>>
>>     If HOOK is a list of functions, remove FUNCTION from that list.
>>
>>     If HOOK is equal to FUNCTION, set HOOK to nil.
>>
>>     Otherwise do nothing.
>
> I like that, adjusted maybe to respect Stefan M's nitpick:
>
> If HOOK's value is a list of functions, remove FUNCTION from that list.
> If HOOK's value is FUNCTION, set HOOK to nil.
> Otherwise do nothing.

Stefan M, does Tomas' edited version look okay to you?

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

From: Stefan Kangas <stefankangas <at> gmail.com>
To: Stefan Monnier <monnier <at> iro.umontreal.ca>, Eli Zaretskii <eliz <at> gnu.org>
Cc: Tomas Nordin <tomasn <at> posteo.net>, 72915 <at> debbugs.gnu.org
Subject: Re: bug#72915: Docstrings of add-hook and remove-hook improvement?
Date: Sat, 14 Sep 2024 19:24:11 -0400

Stefan Monnier via "Bug reports for GNU Emacs, the Swiss army knife of
text editors" <bug-gnu-emacs <at> gnu.org> writes:

> Something like:
>
>       "Remove FUNCTION from HOOK's functions.
>     HOOK should be a symbol, and FUNCTION may be any valid function.
>     Does nothing if HOOK does not currently contain FUNCTION.
>     Compares functions with `equal`, which means that it can be
>     slow if FUNCTION is not a symbol.  See `add-hook'.

Ah, now I see that you posted this proposal.  This is a better start
than what I had.

Should we install it?

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

From: Tomas Nordin <tomasn <at> posteo.net>
To: Stefan Kangas <stefankangas <at> gmail.com>, Stefan Monnier
 <monnier <at> iro.umontreal.ca>, Eli Zaretskii <eliz <at> gnu.org>
Cc: 72915 <at> debbugs.gnu.org
Subject: Re: bug#72915: Docstrings of add-hook and remove-hook improvement?
Date: Sun, 15 Sep 2024 11:17:55 +0000

Stefan Kangas <stefankangas <at> gmail.com> writes:

> Stefan Monnier via "Bug reports for GNU Emacs, the Swiss army knife of
> text editors" <bug-gnu-emacs <at> gnu.org> writes:
>
>> Something like:
>>
>>       "Remove FUNCTION from HOOK's functions.
>>     HOOK should be a symbol, and FUNCTION may be any valid function.
>>     Does nothing if HOOK does not currently contain FUNCTION.
>>     Compares functions with `equal`, which means that it can be
>>     slow if FUNCTION is not a symbol.  See `add-hook'.
>
> Ah, now I see that you posted this proposal.  This is a better start
> than what I had.
>
> Should we install it?

This is about the doc of remove-hook. What about the edits in the
add-hook docstring, was that OK? There was a question on the bit about
setting the HOOK to nil, but I think that was sorted out.

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

From: Stefan Monnier <monnier <at> iro.umontreal.ca>
To: Tomas Nordin <tomasn <at> posteo.net>
Cc: Eli Zaretskii <eliz <at> gnu.org>, Stefan Kangas <stefankangas <at> gmail.com>,
 72915 <at> debbugs.gnu.org
Subject: Re: bug#72915: Docstrings of add-hook and remove-hook improvement?
Date: Sun, 15 Sep 2024 09:19:43 -0400

Tomas Nordin [2024-09-15 11:17:55] wrote:

> Stefan Kangas <stefankangas <at> gmail.com> writes:
>
>> Stefan Monnier via "Bug reports for GNU Emacs, the Swiss army knife of
>> text editors" <bug-gnu-emacs <at> gnu.org> writes:
>>
>>> Something like:
>>>
>>>       "Remove FUNCTION from HOOK's functions.
>>>     HOOK should be a symbol, and FUNCTION may be any valid function.
>>>     Does nothing if HOOK does not currently contain FUNCTION.
>>>     Compares functions with `equal`, which means that it can be
>>>     slow if FUNCTION is not a symbol.  See `add-hook'.
>>
>> Ah, now I see that you posted this proposal.  This is a better start
>> than what I had.
>>
>> Should we install it?
>
> This is about the doc of remove-hook. What about the edits in the
> add-hook docstring, was that OK? There was a question on the bit about
> setting the HOOK to nil, but I think that was sorted out.

The `add-hook` part was OK for me, indeed.

[ I'm no great fan of that paragraph (neither the original nor the one
  you replace it with), tho, because it's a bit "too detailed" for my
  taste.  E.g. the value *always* ends up being a list of functions, and
  the parenthesis states something which sounds to me like it should be
  inferrable from the rest of the docstring.  ]


        Stefan

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

From: Tomas Nordin <tomasn <at> posteo.net>
To: Stefan Monnier <monnier <at> iro.umontreal.ca>
Cc: Eli Zaretskii <eliz <at> gnu.org>, Stefan Kangas <stefankangas <at> gmail.com>,
 72915 <at> debbugs.gnu.org
Subject: Re: bug#72915: Docstrings of add-hook and remove-hook improvement?
Date: Sun, 15 Sep 2024 13:49:15 +0000

Stefan Monnier <monnier <at> iro.umontreal.ca> writes:

> The `add-hook` part was OK for me, indeed.
>
> [ I'm no great fan of that paragraph (neither the original nor the one
>   you replace it with), tho, because it's a bit "too detailed" for my
>   taste.  E.g. the value *always* ends up being a list of functions, and
>   the parenthesis states something which sounds to me like it should be
>   inferrable from the rest of the docstring.  ]

I think I agree, the parenthesized part could be discarded, shortening
the paragraph to

"HOOK should be a symbol.  If HOOK is void, or if HOOK's value is a
single function, it is changed to a list of functions."

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

From: Tomas Nordin <tomasn <at> posteo.net>
To: Stefan Monnier <monnier <at> iro.umontreal.ca>
Cc: Eli Zaretskii <eliz <at> gnu.org>, Stefan Kangas <stefankangas <at> gmail.com>,
 72915 <at> debbugs.gnu.org
Subject: Re: bug#72915: Docstrings of add-hook and remove-hook improvement?
Date: Thu, 27 Feb 2025 21:25:32 +0000

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

Tomas Nordin <tomasn <at> posteo.net> writes:

> Stefan Monnier <monnier <at> iro.umontreal.ca> writes:
>
>> The `add-hook` part was OK for me, indeed.
>>
>> [ I'm no great fan of that paragraph (neither the original nor the one
>>   you replace it with), tho, because it's a bit "too detailed" for my
>>   taste.  E.g. the value *always* ends up being a list of functions, and
>>   the parenthesis states something which sounds to me like it should be
>>   inferrable from the rest of the docstring.  ]
>
> I think I agree, the parenthesized part could be discarded, shortening
> the paragraph to
>
> "HOOK should be a symbol.  If HOOK is void, or if HOOK's value is a
> single function, it is changed to a list of functions."

I think nothing was installed along this discussion so far. Attached is
an attempt to summarize the suggestions as patch.

[0001-Improve-docstring-of-add-hook-and-remove-hook.patch (text/x-diff, attachment)]

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

From: Stefan Kangas <stefankangas <at> gmail.com>
To: Tomas Nordin <tomasn <at> posteo.net>, Stefan Monnier <monnier <at> iro.umontreal.ca>
Cc: Eli Zaretskii <eliz <at> gnu.org>, 72915 <at> debbugs.gnu.org
Subject: Re: bug#72915: Docstrings of add-hook and remove-hook improvement?
Date: Thu, 27 Feb 2025 21:44:48 +0000

Tomas Nordin <tomasn <at> posteo.net> writes:

> Tomas Nordin <tomasn <at> posteo.net> writes:
>
>> Stefan Monnier <monnier <at> iro.umontreal.ca> writes:
>>
>>> The `add-hook` part was OK for me, indeed.
>>>
>>> [ I'm no great fan of that paragraph (neither the original nor the one
>>>   you replace it with), tho, because it's a bit "too detailed" for my
>>>   taste.  E.g. the value *always* ends up being a list of functions, and
>>>   the parenthesis states something which sounds to me like it should be
>>>   inferrable from the rest of the docstring.  ]
>>
>> I think I agree, the parenthesized part could be discarded, shortening
>> the paragraph to
>>
>> "HOOK should be a symbol.  If HOOK is void, or if HOOK's value is a
>> single function, it is changed to a list of functions."
>
> I think nothing was installed along this discussion so far. Attached is
> an attempt to summarize the suggestions as patch.

Thanks.  I think this contribution is bigger than what we can accept
without a copyright assignment from you to the FSF.

Please see etc/copyright-assign.txt in emacs.git to get started.

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

From: Tomas Nordin <tomasn <at> posteo.net>
To: Stefan Kangas <stefankangas <at> gmail.com>, Stefan Monnier
 <monnier <at> iro.umontreal.ca>
Cc: Eli Zaretskii <eliz <at> gnu.org>, 72915 <at> debbugs.gnu.org
Subject: Re: bug#72915: Docstrings of add-hook and remove-hook improvement?
Date: Thu, 27 Feb 2025 21:57:10 +0000

Stefan Kangas <stefankangas <at> gmail.com> writes:

> Tomas Nordin <tomasn <at> posteo.net> writes:
>
>> Tomas Nordin <tomasn <at> posteo.net> writes:
>>
>>> Stefan Monnier <monnier <at> iro.umontreal.ca> writes:
>>>
>>>> The `add-hook` part was OK for me, indeed.
>>>>
>>>> [ I'm no great fan of that paragraph (neither the original nor the one
>>>>   you replace it with), tho, because it's a bit "too detailed" for my
>>>>   taste.  E.g. the value *always* ends up being a list of functions, and
>>>>   the parenthesis states something which sounds to me like it should be
>>>>   inferrable from the rest of the docstring.  ]
>>>
>>> I think I agree, the parenthesized part could be discarded, shortening
>>> the paragraph to
>>>
>>> "HOOK should be a symbol.  If HOOK is void, or if HOOK's value is a
>>> single function, it is changed to a list of functions."
>>
>> I think nothing was installed along this discussion so far. Attached is
>> an attempt to summarize the suggestions as patch.
>
> Thanks.  I think this contribution is bigger than what we can accept
> without a copyright assignment from you to the FSF.
>
> Please see etc/copyright-assign.txt in emacs.git to get started.

Actually I got my assignment confirmed in November last year. It took
some time, but it should be there on file somewhere. Should I provide
the assignment number?

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

From: Stefan Kangas <stefankangas <at> gmail.com>
To: Tomas Nordin <tomasn <at> posteo.net>, Stefan Monnier <monnier <at> iro.umontreal.ca>
Cc: Eli Zaretskii <eliz <at> gnu.org>, 72915-done <at> debbugs.gnu.org
Subject: Re: bug#72915: Docstrings of add-hook and remove-hook improvement?
Date: Thu, 27 Feb 2025 22:15:09 +0000

Version: 30.1

Tomas Nordin <tomasn <at> posteo.net> writes:

> Stefan Kangas <stefankangas <at> gmail.com> writes:
>
>> Tomas Nordin <tomasn <at> posteo.net> writes:
>>
>>> Tomas Nordin <tomasn <at> posteo.net> writes:
>>>
>>>> Stefan Monnier <monnier <at> iro.umontreal.ca> writes:
>>>>
>>>>> The `add-hook` part was OK for me, indeed.
>>>>>
>>>>> [ I'm no great fan of that paragraph (neither the original nor the one
>>>>>   you replace it with), tho, because it's a bit "too detailed" for my
>>>>>   taste.  E.g. the value *always* ends up being a list of functions, and
>>>>>   the parenthesis states something which sounds to me like it should be
>>>>>   inferrable from the rest of the docstring.  ]
>>>>
>>>> I think I agree, the parenthesized part could be discarded, shortening
>>>> the paragraph to
>>>>
>>>> "HOOK should be a symbol.  If HOOK is void, or if HOOK's value is a
>>>> single function, it is changed to a list of functions."
>>>
>>> I think nothing was installed along this discussion so far. Attached is
>>> an attempt to summarize the suggestions as patch.
>>
>> Thanks.  I think this contribution is bigger than what we can accept
>> without a copyright assignment from you to the FSF.
>>
>> Please see etc/copyright-assign.txt in emacs.git to get started.
>
> Actually I got my assignment confirmed in November last year. It took
> some time, but it should be there on file somewhere. Should I provide
> the assignment number?

No need, thanks.  I just pushed your patch to emacs-30 with the below
small change to use the imperative mood.

Thanks for the patch!  Closing this bug now.

diff --git a/lisp/subr.el b/lisp/subr.el
index d0faff73e4a..7af21125b33 100644
--- a/lisp/subr.el
+++ b/lisp/subr.el
@@ -2177,8 +2177,8 @@ add-hook
 (defun remove-hook (hook function &optional local)
   "Remove FUNCTION from HOOK's functions.
 HOOK should be a symbol, and FUNCTION may be any valid function.
-Does nothing if HOOK does not currently contain FUNCTION.
-Compares functions with `equal`, which means that it can be
+Do nothing if HOOK does not currently contain FUNCTION.
+Compare functions with `equal`, which means that it can be
 slow if FUNCTION is not a symbol.  See `add-hook'.

 The optional third argument, LOCAL, if non-nil, says to modify

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

From: Tomas Nordin <tomasn <at> posteo.net>
To: Stefan Kangas <stefankangas <at> gmail.com>, Stefan Monnier
 <monnier <at> iro.umontreal.ca>
Cc: Eli Zaretskii <eliz <at> gnu.org>, 72915-done <at> debbugs.gnu.org
Subject: Re: bug#72915: Docstrings of add-hook and remove-hook improvement?
Date: Fri, 28 Feb 2025 17:38:29 +0000

Stefan Kangas <stefankangas <at> gmail.com> writes:

> No need, thanks.  I just pushed your patch to emacs-30 with the below
> small change to use the imperative mood.
>
> Thanks for the patch!  Closing this bug now.
>
> diff --git a/lisp/subr.el b/lisp/subr.el
> index d0faff73e4a..7af21125b33 100644
> --- a/lisp/subr.el
> +++ b/lisp/subr.el
> @@ -2177,8 +2177,8 @@ add-hook
>  (defun remove-hook (hook function &optional local)
>    "Remove FUNCTION from HOOK's functions.
>  HOOK should be a symbol, and FUNCTION may be any valid function.
> -Does nothing if HOOK does not currently contain FUNCTION.
> -Compares functions with `equal`, which means that it can be
> +Do nothing if HOOK does not currently contain FUNCTION.
> +Compare functions with `equal`, which means that it can be
>  slow if FUNCTION is not a symbol.  See `add-hook'.
>
>  The optional third argument, LOCAL, if non-nil, says to modify

I wanted to write it like that but was too shy and took Stefan M:s text
verbatim. Perfect, thanks.

Previous Next

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