GNU bug report logs - #59379
29.0.50; `define-advice' documentation needs improving

Previous Next

Package: emacs;

Reported by: Stefan Kangas <stefankangas <at> gmail.com>

Date: Sat, 19 Nov 2022 07:27:02 UTC

Severity: normal

Found in version 29.0.50

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

Bug is archived. No further changes may be made.

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

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

View this report as an mbox folder, status mbox, maintainer mbox


Report forwarded to monnier <at> iro.umontreal.ca, bug-gnu-emacs <at> gnu.org:
bug#59379; Package emacs. (Sat, 19 Nov 2022 07:27:02 GMT) Full text and rfc822 format available.

Acknowledgement sent to Stefan Kangas <stefankangas <at> gmail.com>:
New bug report received and forwarded. Copy sent to monnier <at> iro.umontreal.ca, bug-gnu-emacs <at> gnu.org. (Sat, 19 Nov 2022 07:27:02 GMT) Full text and rfc822 format available.

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

From: Stefan Kangas <stefankangas <at> gmail.com>
To: bug-gnu-emacs <at> gnu.org
Subject: 29.0.50; `define-advice' documentation needs improving
Date: Fri, 18 Nov 2022 23:26:00 -0800
This bug report is about the documentation of the `define-advice' macro.

1. It is mentioned in

    (info "(elisp) Advising Named Functions")

   but there is no explanation of when one would want to use it instead
   of `advice-add'.  In fact, apart from its definition in that info
   node, and its entry in the index, I see no other mention of it in the
   manual.

   It is mentioned before the `advice-add' function, which seems to
   imply that it is more important?

2. It would also be good to have an example of how to use it, at least
   it in the manual.

3. This is its argument list:

   (define-advice SYMBOL (HOW LAMBDA-LIST &optional NAME DEPTH) &rest
   BODY)

   The HOW, LAMBDA-LIST, NAME, DEPTH parameters are not documented in
   the docstring, nor in the info manual.

4. There also seem to be a mistake (or merely a typo) in the argument
   list as described in the argument list (note that "HOW" above is
   replaced with "where"):

    -- Macro: define-advice symbol (where lambda-list &optional name depth)
             &rest body

5. The documentation of NAME says that: "The advice is an anonymous
   function if NAME is ‘nil’ or a function named ‘symbol <at> name’."

   I struggle with parsing this sentence.  It sounds like it is saying
   that, if I want an anonymous function, I should define a function
   named `symbol <at> name' (substituting `symbol' and `name') and then pass
   that argument as the NAME argument?  But then the function is not
   anonymous?

6. Finally, the info manual says: "This macro defines a piece of advice
   and adds it to the function named SYMBOL."  Could the words "a piece
   of advice" simply be replaced with "an advice", or is there some
   important meaning that would be lost?

Thanks.




Information forwarded to bug-gnu-emacs <at> gnu.org:
bug#59379; Package emacs. (Sat, 19 Nov 2022 12:24:02 GMT) Full text and rfc822 format available.

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

From: Visuwesh <visuweshm <at> gmail.com>
To: Stefan Kangas <stefankangas <at> gmail.com>
Cc: 59379 <at> debbugs.gnu.org, Stefan Monnier <monnier <at> iro.umontreal.ca>
Subject: Re: bug#59379: 29.0.50; `define-advice' documentation needs improving
Date: Sat, 19 Nov 2022 17:53:20 +0530
[வெள்ளி நவம்பர் 18, 2022] Stefan Kangas wrote:

> This bug report is about the documentation of the `define-advice' macro.
>
> [...]
>
> 3. This is its argument list:
>
>    (define-advice SYMBOL (HOW LAMBDA-LIST &optional NAME DEPTH) &rest
>    BODY)
>
>    The HOW, LAMBDA-LIST, NAME, DEPTH parameters are not documented in
>    the docstring, nor in the info manual.

HOW, LAMBDA-LIST, NAME, and DEPTH arguments become clear when once looks
up the add-function docstring, and the docstring already mentions
add-function.

> 4. There also seem to be a mistake (or merely a typo) in the argument
>    list as described in the argument list (note that "HOW" above is
>    replaced with "where"):
>
>     -- Macro: define-advice symbol (where lambda-list &optional name depth)
>              &rest body

IIRC, Stefan prefers HOW over WHERE since add-function has :filter-args
and friends.

> 5. The documentation of NAME says that: "The advice is an anonymous
>    function if NAME is ‘nil’ or a function named ‘symbol <at> name’."
>
>    I struggle with parsing this sentence.  It sounds like it is saying
>    that, if I want an anonymous function, I should define a function
>    named `symbol <at> name' (substituting `symbol' and `name') and then pass
>    that argument as the NAME argument?  But then the function is not
>    anonymous?

Would a comma help before the "or"? i.e.,

    The advice is an anonymous function if NAME is ‘nil’, or a function
    named ‘symbol <at> name’.

Changing symbol <at> name to SYMBOL <at> NAME like in the docstring will make it
clearer, I think.  If still not clear, the following happens in the case
of NAME being nil vs. non-nil

    NAME nil ==> (advice-add SYMBOL HOW (lambda LAMBDA-LIST BODY) ...)
    NAME non-nil ==> (advice-add SYMBOL HOW (defun SYMBOL <at> NAME LAMBDA-LIST BODY) ...)

HTH.




Information forwarded to bug-gnu-emacs <at> gnu.org:
bug#59379; Package emacs. (Sat, 19 Nov 2022 13:53:01 GMT) Full text and rfc822 format available.

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

From: Stefan Kangas <stefankangas <at> gmail.com>
To: Visuwesh <visuweshm <at> gmail.com>
Cc: 59379 <at> debbugs.gnu.org, Stefan Monnier <monnier <at> iro.umontreal.ca>
Subject: Re: bug#59379: 29.0.50; `define-advice' documentation needs improving
Date: Sat, 19 Nov 2022 05:52:41 -0800
Visuwesh <visuweshm <at> gmail.com> writes:

>> 3. This is its argument list:
>>
>>    (define-advice SYMBOL (HOW LAMBDA-LIST &optional NAME DEPTH) &rest
>>    BODY)
>>
>>    The HOW, LAMBDA-LIST, NAME, DEPTH parameters are not documented in
>>    the docstring, nor in the info manual.
>
> HOW, LAMBDA-LIST, NAME, and DEPTH arguments become clear when once looks
> up the add-function docstring, and the docstring already mentions
> add-function.

Then that should be explicitly stated.

And LAMBDA-LIST is not explained there either, AFAICT.

>> 5. The documentation of NAME says that: "The advice is an anonymous
>>    function if NAME is ‘nil’ or a function named ‘symbol <at> name’."
>>
>>    I struggle with parsing this sentence.  It sounds like it is saying
>>    that, if I want an anonymous function, I should define a function
>>    named `symbol <at> name' (substituting `symbol' and `name') and then pass
>>    that argument as the NAME argument?  But then the function is not
>>    anonymous?
>
> Would a comma help before the "or"? i.e.,
>
>     The advice is an anonymous function if NAME is ‘nil’, or a function
>     named ‘symbol <at> name’.

So it can be either nil or a symbol?  How do I actually use it?

> Changing symbol <at> name to SYMBOL <at> NAME like in the docstring will make it
> clearer, I think.  If still not clear, the following happens in the case
> of NAME being nil vs. non-nil
>
>     NAME nil ==> (advice-add SYMBOL HOW (lambda LAMBDA-LIST BODY) ...)
>     NAME non-nil ==> (advice-add SYMBOL HOW (defun SYMBOL <at> NAME LAMBDA-LIST BODY) ...)

This all needs to be explained clearly in the documentation.




Information forwarded to bug-gnu-emacs <at> gnu.org:
bug#59379; Package emacs. (Sat, 19 Nov 2022 14:45:01 GMT) Full text and rfc822 format available.

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

From: Visuwesh <visuweshm <at> gmail.com>
To: Stefan Kangas <stefankangas <at> gmail.com>
Cc: 59379 <at> debbugs.gnu.org, Stefan Monnier <monnier <at> iro.umontreal.ca>
Subject: Re: bug#59379: 29.0.50; `define-advice' documentation needs improving
Date: Sat, 19 Nov 2022 20:14:32 +0530
[சனி நவம்பர் 19, 2022] Stefan Kangas wrote:

> Visuwesh <visuweshm <at> gmail.com> writes:
>
>>> 3. This is its argument list:
>>>
>>>    (define-advice SYMBOL (HOW LAMBDA-LIST &optional NAME DEPTH) &rest
>>>    BODY)
>>>
>>>    The HOW, LAMBDA-LIST, NAME, DEPTH parameters are not documented in
>>>    the docstring, nor in the info manual.
>>
>> HOW, LAMBDA-LIST, NAME, and DEPTH arguments become clear when once looks
>> up the add-function docstring, and the docstring already mentions
>> add-function.
>
> Then that should be explicitly stated.

Is that not already spelt out?

    Define an advice and add it to function named SYMBOL.
    See ‘advice-add’ and ‘add-function’ for explanation on the
    ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
    arguments.  Note if NAME is nil the advice is anonymous;
    ^^^^^^^^^^
    otherwise it is named ‘SYMBOL <at> NAME’.

> And LAMBDA-LIST is not explained there either, AFAICT.

Reading the advice-add's document should tell what it means but I might
be biased here.

>>> 5. The documentation of NAME says that: "The advice is an anonymous
>>>    function if NAME is ‘nil’ or a function named ‘symbol <at> name’."
>>>
>>>    I struggle with parsing this sentence.  It sounds like it is saying
>>>    that, if I want an anonymous function, I should define a function
>>>    named `symbol <at> name' (substituting `symbol' and `name') and then pass
>>>    that argument as the NAME argument?  But then the function is not
>>>    anonymous?
>>
>> Would a comma help before the "or"? i.e.,
>>
>>     The advice is an anonymous function if NAME is ‘nil’, or a function
>>     named ‘symbol <at> name’.
>
> So it can be either nil or a symbol?  How do I actually use it?

Yes.  See below for an example with a non-nil NAME

    (define-advice file-cache-file-name (:filter-return (filename) vz/add-slash-if-directory)
      "Add a trailing slash if FILENAME is a directory."
      (if (file-directory-p filename)
          (concat filename "/")
        filename))

which creates a function file-cache-file-name <at> vz/add-slash-if-directory.
But if NAME was nil, then there would be no named function but rather a
lambda that gets added as an advice (which is hard to remove later).

>> Changing symbol <at> name to SYMBOL <at> NAME like in the docstring will make it
>> clearer, I think.  If still not clear, the following happens in the case
>> of NAME being nil vs. non-nil
>>
>>     NAME nil ==> (advice-add SYMBOL HOW (lambda LAMBDA-LIST BODY) ...)
>>     NAME non-nil ==> (advice-add SYMBOL HOW (defun SYMBOL <at> NAME LAMBDA-LIST BODY) ...)
>
> This all needs to be explained clearly in the documentation.

Again, it seems obvious to me.




Information forwarded to bug-gnu-emacs <at> gnu.org:
bug#59379; Package emacs. (Sat, 19 Nov 2022 15:35:02 GMT) Full text and rfc822 format available.

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

From: Stefan Monnier <monnier <at> iro.umontreal.ca>
To: Visuwesh <visuweshm <at> gmail.com>
Cc: 59379 <at> debbugs.gnu.org, Stefan Kangas <stefankangas <at> gmail.com>
Subject: Re: bug#59379: 29.0.50; `define-advice' documentation needs improving
Date: Sat, 19 Nov 2022 10:34:11 -0500
> IIRC, Stefan prefers HOW over WHERE since add-function has :filter-args
> and friends.

It's also because `add-function` takes a gv-place argument, so "where"
can be a bit confusing (does it refer to the place where the advice is
installed or to the way it's combined with previous function?).


        Stefan





Information forwarded to bug-gnu-emacs <at> gnu.org:
bug#59379; Package emacs. (Thu, 08 Feb 2024 06:47:02 GMT) Full text and rfc822 format available.

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

From: Visuwesh <visuweshm <at> gmail.com>
To: Stefan Kangas <stefankangas <at> gmail.com>
Cc: 59379 <at> debbugs.gnu.org, Stefan Monnier <monnier <at> iro.umontreal.ca>
Subject: Re: bug#59379: 29.0.50; `define-advice' documentation needs improving
Date: Thu, 08 Feb 2024 12:16:11 +0530
[Message part 1 (text/plain, inline)]
[வியாழன் பிப்ரவரி 08, 2024] Debdutta Chakraborty wrote:

> Datafile.
>
> Things to read and write:
>
> frequency reduced mass force constant atom1_x atom1_y atom1_z

Sir,

Please find attached file.

[FREQDATA.txt (text/plain, attachment)]

Information forwarded to bug-gnu-emacs <at> gnu.org:
bug#59379; Package emacs. (Thu, 08 Feb 2024 13:51:01 GMT) Full text and rfc822 format available.

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

From: Visuwesh <visuweshm <at> gmail.com>
To: Stefan Kangas <stefankangas <at> gmail.com>
Cc: 59379 <at> debbugs.gnu.org, Stefan Monnier <monnier <at> iro.umontreal.ca>
Subject: Re: bug#59379: 29.0.50; `define-advice' documentation needs improving
Date: Thu, 08 Feb 2024 19:19:43 +0530
Kindly ignore this message: somehow I managed to fat finger very badly
and sent a mail that was addressed to my Prof to debbugs...  Sorry for
the noise.

[வியாழன் பிப்ரவரி 08, 2024] Visuwesh wrote:

> [வியாழன் பிப்ரவரி 08, 2024] Debdutta Chakraborty wrote:
>
>> Datafile.
>>
>> Things to read and write:
>>
>> frequency reduced mass force constant atom1_x atom1_y atom1_z
>
> Sir,
>
> Please find attached file.

Reply sent to Eli Zaretskii <eliz <at> gnu.org>:
You have taken responsibility. (Thu, 08 Feb 2024 13:55:02 GMT) Full text and rfc822 format available.

Notification sent to Stefan Kangas <stefankangas <at> gmail.com>:
bug acknowledged by developer. (Thu, 08 Feb 2024 13:55:02 GMT) Full text and rfc822 format available.

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

From: Eli Zaretskii <eliz <at> gnu.org>
To: 59379-done <at> debbugs.gnu.org
Subject: Re: bug#59379: 29.0.50; `define-advice' documentation needs improving
Date: Thu, 08 Feb 2024 15:54:27 +0200
> Cc: 59379 <at> debbugs.gnu.org, Stefan Monnier <monnier <at> iro.umontreal.ca>
> From: Visuwesh <visuweshm <at> gmail.com>
> Date: Thu, 08 Feb 2024 19:19:43 +0530
> 
> Kindly ignore this message: somehow I managed to fat finger very badly
> and sent a mail that was addressed to my Prof to debbugs...  Sorry for
> the noise.

Closing.




bug archived. Request was from Debbugs Internal Request <help-debbugs <at> gnu.org> to internal_control <at> debbugs.gnu.org. (Fri, 08 Mar 2024 12:24:08 GMT) Full text and rfc822 format available.

This bug report was last modified 20 days ago.

Previous Next


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