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

Please note: This is a static page, with minimal formatting, updated once a day.
Click here to see this page with the latest information and nicer formatting.

Package: emacs; Reported by: Stefan Kangas <stefankangas@HIDDEN>; dated Sat, 19 Nov 2022 07:27:02 UTC; Maintainer for emacs is bug-gnu-emacs@HIDDEN.

Message received at 59379 <at> debbugs.gnu.org:


Received: (at 59379) by debbugs.gnu.org; 19 Nov 2022 12:23:34 +0000
From debbugs-submit-bounces <at> debbugs.gnu.org Sat Nov 19 07:23:34 2022
Received: from localhost ([127.0.0.1]:39202 helo=debbugs.gnu.org)
	by debbugs.gnu.org with esmtp (Exim 4.84_2)
	(envelope-from <debbugs-submit-bounces <at> debbugs.gnu.org>)
	id 1owMsg-0001lE-Gd
	for submit <at> debbugs.gnu.org; Sat, 19 Nov 2022 07:23:34 -0500
Received: from mail-pl1-f194.google.com ([209.85.214.194]:40750)
 by debbugs.gnu.org with esmtp (Exim 4.84_2)
 (envelope-from <visuweshm@HIDDEN>) id 1owMsc-0001kz-Q4
 for 59379 <at> debbugs.gnu.org; Sat, 19 Nov 2022 07:23:34 -0500
Received: by mail-pl1-f194.google.com with SMTP id p21so6786038plr.7
 for <59379 <at> debbugs.gnu.org>; Sat, 19 Nov 2022 04:23:30 -0800 (PST)
DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20210112;
 h=content-transfer-encoding:mime-version:message-id:date:user-agent
 :references:in-reply-to:subject:cc:to:from:from:to:cc:subject:date
 :message-id:reply-to;
 bh=pSs9u+UD4mzitQP7jCyxlMhSOWk/2GJh/FDgDAt2oSw=;
 b=KbC4mHmOaYpcKiEhSuqmstS0nDblsvBh8qZIVO2i98mBrkzInRFhLNFEYqvZvNGtS8
 02wZH2w0CUbWFQwEOpwWWV8CDSO+m/m2FjRpj0YNk0yLhpjM1hm/yUgTWw1tEL/Ln7W+
 ZiAG2cA+Yxg7OZqSYMBtg+6PexMi9ztXWcFzX2g4pocWifdHn9Oe3C8Goembkf2EdOmz
 NAkQ1y/vHWz889kdmp7z0NK6VY+4PMhAdbXf2UjuCQZjHDVxIql7OfLa7sMx44sOLBev
 xww5Oger67kBzPtWrNxEfC4/BcFqqpkSZM2GBhq4728CVGz6Jjx6BA7EtWawMzvUfO4s
 s2LQ==
X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed;
 d=1e100.net; s=20210112;
 h=content-transfer-encoding:mime-version:message-id:date:user-agent
 :references:in-reply-to:subject:cc:to:from:x-gm-message-state:from
 :to:cc:subject:date:message-id:reply-to;
 bh=pSs9u+UD4mzitQP7jCyxlMhSOWk/2GJh/FDgDAt2oSw=;
 b=x9Pye3CnvXVFuCsOTbnvgPkRAyYfYIIWjt78RBsXqQQntdnd077bupSX4gudlZOX0P
 EiieXLIpsaFEuoKRustWRk1VlZath5RuPcEPtv3R1VuTzRc93lEmRwxGDmTgOLDBZp9x
 io2mxWW0baF3qDTWoKrQJ+5CTK6iu9lh6+ZwSKkBWFrBgfsJ4ZF1+DIhmCp2ION0Wh+X
 vZztsjdEyPvWnmeIxIvoWgreXPVv8pbsE35IkTHK+DvLYGVEqiqG+B4NJhVquN3z6rUD
 ft8mSP/oCaweC8Kv/w6LADYDwBL3oeoVQBGkoG4s0kp+k2OVECgBsow27ZQnRRAO5cPM
 3Jig==
X-Gm-Message-State: ANoB5pl46vNIzQcKQeqTZShhqW65Yiw+yMMXLD518FvgCbgcc7doltbD
 nbRikWwjmGWQZflWJ0lcJZ0=
X-Google-Smtp-Source: AA0mqf7Qu5NHEpOiWZ0s4zRPKylGPRZApailW8YSlY0duldDwgc/fmByrgxvv1a5Go7XZc7ct6yZqg==
X-Received: by 2002:a17:90b:394a:b0:210:4438:2d40 with SMTP id
 oe10-20020a17090b394a00b0021044382d40mr18066865pjb.196.1668860604878; 
 Sat, 19 Nov 2022 04:23:24 -0800 (PST)
Received: from localhost ([118.185.152.162]) by smtp.gmail.com with ESMTPSA id
 o31-20020a635d5f000000b004769f0fd385sm4299823pgm.52.2022.11.19.04.23.23
 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256);
 Sat, 19 Nov 2022 04:23:24 -0800 (PST)
From: Visuwesh <visuweshm@HIDDEN>
To: Stefan Kangas <stefankangas@HIDDEN>
Subject: Re: bug#59379: 29.0.50; `define-advice' documentation needs improving
In-Reply-To: <CADwFkmmPp+K=LsEe867soqXEYHzS_LKHpzzcsm3JCR8KRMX+aA@HIDDEN>
 (Stefan Kangas's message of "Fri, 18 Nov 2022 23:26:00 -0800")
References: <CADwFkmmPp+K=LsEe867soqXEYHzS_LKHpzzcsm3JCR8KRMX+aA@HIDDEN>
User-Agent: Gnus/5.13 (Gnus v5.13)
Date: Sat, 19 Nov 2022 17:53:20 +0530
Message-ID: <877czrb0av.fsf@HIDDEN>
MIME-Version: 1.0
Content-Type: text/plain; charset=utf-8
Content-Transfer-Encoding: quoted-printable
X-Spam-Score: -0.0 (/)
X-Debbugs-Envelope-To: 59379
Cc: 59379 <at> debbugs.gnu.org, Stefan Monnier <monnier@HIDDEN>
X-BeenThere: debbugs-submit <at> debbugs.gnu.org
X-Mailman-Version: 2.1.18
Precedence: list
List-Id: <debbugs-submit.debbugs.gnu.org>
List-Unsubscribe: <https://debbugs.gnu.org/cgi-bin/mailman/options/debbugs-submit>, 
 <mailto:debbugs-submit-request <at> debbugs.gnu.org?subject=unsubscribe>
List-Archive: <https://debbugs.gnu.org/cgi-bin/mailman/private/debbugs-submit/>
List-Post: <mailto:debbugs-submit <at> debbugs.gnu.org>
List-Help: <mailto:debbugs-submit-request <at> debbugs.gnu.org?subject=help>
List-Subscribe: <https://debbugs.gnu.org/cgi-bin/mailman/listinfo/debbugs-submit>, 
 <mailto:debbugs-submit-request <at> debbugs.gnu.org?subject=subscribe>
Errors-To: debbugs-submit-bounces <at> debbugs.gnu.org
Sender: "Debbugs-submit" <debbugs-submit-bounces <at> debbugs.gnu.org>
X-Spam-Score: -1.0 (-)

[=E0=AE=B5=E0=AF=86=E0=AE=B3=E0=AF=8D=E0=AE=B3=E0=AE=BF =E0=AE=A8=E0=AE=B5=
=E0=AE=AE=E0=AF=8D=E0=AE=AA=E0=AE=B0=E0=AF=8D 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 dept=
h)
>              &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 =E2=80=98nil=E2=80=99 or a function named =E2=80=
=98symbol@name=E2=80=99."
>
>    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@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 =E2=80=98nil=E2=80=99, o=
r a function
    named =E2=80=98symbol@name=E2=80=99.

Changing symbol@name to SYMBOL@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 =3D=3D> (advice-add SYMBOL HOW (lambda LAMBDA-LIST BODY) ...)
    NAME non-nil =3D=3D> (advice-add SYMBOL HOW (defun SYMBOL@NAME LAMBDA-L=
IST BODY) ...)

HTH.




Information forwarded to bug-gnu-emacs@HIDDEN:
bug#59379; Package emacs. Full text available.

Message received at submit <at> debbugs.gnu.org:


Received: (at submit) by debbugs.gnu.org; 19 Nov 2022 07:26:08 +0000
From debbugs-submit-bounces <at> debbugs.gnu.org Sat Nov 19 02:26:08 2022
Received: from localhost ([127.0.0.1]:38881 helo=debbugs.gnu.org)
	by debbugs.gnu.org with esmtp (Exim 4.84_2)
	(envelope-from <debbugs-submit-bounces <at> debbugs.gnu.org>)
	id 1owIEp-0006bE-MG
	for submit <at> debbugs.gnu.org; Sat, 19 Nov 2022 02:26:07 -0500
Received: from lists.gnu.org ([209.51.188.17]:51988)
 by debbugs.gnu.org with esmtp (Exim 4.84_2)
 (envelope-from <stefankangas@HIDDEN>) id 1owIEm-0006b5-KJ
 for submit <at> debbugs.gnu.org; Sat, 19 Nov 2022 02:26:06 -0500
Received: from eggs.gnu.org ([2001:470:142:3::10])
 by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256)
 (Exim 4.90_1) (envelope-from <stefankangas@HIDDEN>)
 id 1owIEm-0004gu-FL
 for bug-gnu-emacs@HIDDEN; Sat, 19 Nov 2022 02:26:04 -0500
Received: from mail-oo1-xc35.google.com ([2607:f8b0:4864:20::c35])
 by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128)
 (Exim 4.90_1) (envelope-from <stefankangas@HIDDEN>)
 id 1owIEk-0002Lr-Jx
 for bug-gnu-emacs@HIDDEN; Sat, 19 Nov 2022 02:26:04 -0500
Received: by mail-oo1-xc35.google.com with SMTP id
 j6-20020a4ab1c6000000b004809a59818cso1115418ooo.0
 for <bug-gnu-emacs@HIDDEN>; Fri, 18 Nov 2022 23:26:02 -0800 (PST)
DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20210112;
 h=content-transfer-encoding:to:subject:message-id:date:mime-version
 :from:from:to:cc:subject:date:message-id:reply-to;
 bh=qeWdqpwHgGhCZxbU6Hk3UvCH0mHW5m5UPX8c9BNh+Z8=;
 b=L3oIIMb9OQ8TZCVbKaeO61IbupIf292o80C3PWpnAHHW64YxX2Ragp/Qw7FJnYTAMN
 xHQXfZoEDJZH/HurBhk+xlIBw3Ruifb5TEgqYZ2wOLOa7rABePhm6eY+rV0b2jz1DNZ+
 GRxptr1OschneUkdSV3RgGfKlMHB1Biq26HSoIAVlYWFvAZHozG81oCZ60tgvsqvaUbI
 K2SyEWvCDlD2S0XEeXoUk10W4OpS6YSvQhL2CH2mIcalMFtike8vbCfJaiUbDl7srG4L
 Cvk4umpqgKVwtOT5NhlL8LHfiyErBrhsM0XGED0l3r0ldS0lQEnfJRnvSm6ZuhSp+eRA
 kE4w==
X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed;
 d=1e100.net; s=20210112;
 h=content-transfer-encoding:to:subject:message-id:date:mime-version
 :from:x-gm-message-state:from:to:cc:subject:date:message-id:reply-to;
 bh=qeWdqpwHgGhCZxbU6Hk3UvCH0mHW5m5UPX8c9BNh+Z8=;
 b=MmDjKqPQ8nwj84Qbn/bgGmFzSyBLk4lK3yzc5jVutrIWpi5jbV0jshXwvrOJuXsQfb
 V3NN30bYFsPEDY/tlXIJ4nr0edpIOdKwYkMlEdCYo0+xAREI9QMw46mNT8duF0judqYE
 U5c2VDhZKoxqKJCSxLYnuy+Zk7xYh3qgxpIXXiTfPRndEPHWwSBZP6SVygaej6A2OjUU
 QSiA+Y26OltT9Wmn23BVTPmeOzdOfWoQ8qaEjJy+QX+E2/bkkizdZd7aknPePtvpfZet
 Abp3yhYrBU6XCFSI16zuv3v9wGK1q4dsBa9sO1fQeQwajOve3Nt2fwPB6Ru5b9amtOMR
 6vmg==
X-Gm-Message-State: ANoB5pkaRpJfvigYDSLt9tuE2zF9a2ZEOTqcT3cNadqb3UrMwegEg5Rs
 5IyIFyYFQegAIg1xtubThgebwfoho4WKPyfDE54zAEph
X-Google-Smtp-Source: AA0mqf73kV+5ErP3rXGXR20s40W/5xpunzVexgRGsEdaqWebxLGeMdVBSbaxxhm4g9gOV30hpnkqBw3zR53EdPal8ZY=
X-Received: by 2002:a4a:54c1:0:b0:49f:d54c:9bcd with SMTP id
 t184-20020a4a54c1000000b0049fd54c9bcdmr938837ooa.5.1668842761181; Fri, 18 Nov
 2022 23:26:01 -0800 (PST)
Received: from 753933720722 named unknown by gmailapi.google.com with
 HTTPREST; Fri, 18 Nov 2022 23:26:00 -0800
From: Stefan Kangas <stefankangas@HIDDEN>
X-Debbugs-CC: Stefan Monnier <monnier@HIDDEN>
X-Hashcash: 1:20:221119:bug-gnu-emacs@HIDDEN::jl0crV3Xf6n6gFDC:9O0K
MIME-Version: 1.0
Date: Fri, 18 Nov 2022 23:26:00 -0800
Message-ID: <CADwFkmmPp+K=LsEe867soqXEYHzS_LKHpzzcsm3JCR8KRMX+aA@HIDDEN>
Subject: 29.0.50; `define-advice' documentation needs improving
To: bug-gnu-emacs@HIDDEN
Content-Type: text/plain; charset="UTF-8"
Content-Transfer-Encoding: quoted-printable
Received-SPF: pass client-ip=2607:f8b0:4864:20::c35;
 envelope-from=stefankangas@HIDDEN; helo=mail-oo1-xc35.google.com
X-Spam_score_int: -20
X-Spam_score: -2.1
X-Spam_bar: --
X-Spam_report: (-2.1 / 5.0 requ) BAYES_00=-1.9, DKIM_SIGNED=0.1,
 DKIM_VALID=-0.1, DKIM_VALID_AU=-0.1, DKIM_VALID_EF=-0.1, FREEMAIL_FROM=0.001,
 RCVD_IN_DNSWL_NONE=-0.0001, SPF_HELO_NONE=0.001,
 SPF_PASS=-0.001 autolearn=ham autolearn_force=no
X-Spam_action: no action
X-Spam-Score: -1.3 (-)
X-Debbugs-Envelope-To: submit
X-BeenThere: debbugs-submit <at> debbugs.gnu.org
X-Mailman-Version: 2.1.18
Precedence: list
List-Id: <debbugs-submit.debbugs.gnu.org>
List-Unsubscribe: <https://debbugs.gnu.org/cgi-bin/mailman/options/debbugs-submit>, 
 <mailto:debbugs-submit-request <at> debbugs.gnu.org?subject=unsubscribe>
List-Archive: <https://debbugs.gnu.org/cgi-bin/mailman/private/debbugs-submit/>
List-Post: <mailto:debbugs-submit <at> debbugs.gnu.org>
List-Help: <mailto:debbugs-submit-request <at> debbugs.gnu.org?subject=help>
List-Subscribe: <https://debbugs.gnu.org/cgi-bin/mailman/listinfo/debbugs-submit>, 
 <mailto:debbugs-submit-request <at> debbugs.gnu.org?subject=subscribe>
Errors-To: debbugs-submit-bounces <at> debbugs.gnu.org
Sender: "Debbugs-submit" <debbugs-submit-bounces <at> debbugs.gnu.org>
X-Spam-Score: -2.3 (--)

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 =E2=80=98nil=E2=80=99 or a function named =E2=80=98s=
ymbol@name=E2=80=99."

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




Acknowledgement sent to Stefan Kangas <stefankangas@HIDDEN>:
New bug report received and forwarded. Copy sent to monnier@HIDDEN, bug-gnu-emacs@HIDDEN. Full text available.
Report forwarded to monnier@HIDDEN, bug-gnu-emacs@HIDDEN:
bug#59379; Package emacs. Full text available.
Please note: This is a static page, with minimal formatting, updated once a day.
Click here to see this page with the latest information and nicer formatting.
Last modified: Sat, 19 Nov 2022 12:30:02 UTC

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