GNU bug report logs -
#59379
29.0.50; `define-advice' documentation needs improving
Previous Next
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.
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):
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):
[வெள்ளி நவம்பர் 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):
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):
[சனி நவம்பர் 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):
> 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):
[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):
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):
> 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.