From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.io!.POSTED.blaine.gmane.org!not-for-mail From: Stefan Kangas Newsgroups: gmane.emacs.bugs Subject: bug#59379: 29.0.50; `define-advice' documentation needs improving Date: Fri, 18 Nov 2022 23:26:00 -0800 Message-ID: Mime-Version: 1.0 Content-Type: text/plain; charset="UTF-8" Content-Transfer-Encoding: quoted-printable Injection-Info: ciao.gmane.io; posting-host="blaine.gmane.org:116.202.254.214"; logging-data="32545"; mail-complaints-to="usenet@ciao.gmane.io" Cc: Stefan Monnier To: 59379@debbugs.gnu.org Original-X-From: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane-mx.org@gnu.org Sat Nov 19 08:27:22 2022 Return-path: Envelope-to: geb-bug-gnu-emacs@m.gmane-mx.org Original-Received: from lists.gnu.org ([209.51.188.17]) by ciao.gmane.io with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.92) (envelope-from ) id 1owIG2-0008ND-CJ for geb-bug-gnu-emacs@m.gmane-mx.org; Sat, 19 Nov 2022 08:27:22 +0100 Original-Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1owIFl-0004k9-HR; Sat, 19 Nov 2022 02:27:05 -0500 Original-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 ) id 1owIFj-0004jx-3k for bug-gnu-emacs@gnu.org; Sat, 19 Nov 2022 02:27:03 -0500 Original-Received: from debbugs.gnu.org ([209.51.188.43]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1owIFi-0002RO-Ry for bug-gnu-emacs@gnu.org; Sat, 19 Nov 2022 02:27:02 -0500 Original-Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.84_2) (envelope-from ) id 1owIFi-0006cW-HU; Sat, 19 Nov 2022 02:27:02 -0500 X-Loop: help-debbugs@gnu.org Resent-From: Stefan Kangas Original-Sender: "Debbugs-submit" Resent-CC: monnier@iro.umontreal.ca, bug-gnu-emacs@gnu.org Resent-Date: Sat, 19 Nov 2022 07:27:02 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: report 59379 X-GNU-PR-Package: emacs X-Debbugs-Original-To: bug-gnu-emacs@gnu.org X-Debbugs-Original-Xcc: Stefan Monnier Original-Received: via spool by submit@debbugs.gnu.org id=B.166884276825377 (code B ref -1); Sat, 19 Nov 2022 07:27:02 +0000 Original-Received: (at submit) by debbugs.gnu.org; 19 Nov 2022 07:26:08 +0000 Original-Received: from localhost ([127.0.0.1]:38881 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1owIEp-0006bE-MG for submit@debbugs.gnu.org; Sat, 19 Nov 2022 02:26:07 -0500 Original-Received: from lists.gnu.org ([209.51.188.17]:51988) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1owIEm-0006b5-KJ for submit@debbugs.gnu.org; Sat, 19 Nov 2022 02:26:06 -0500 Original-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 ) id 1owIEm-0004gu-FL for bug-gnu-emacs@gnu.org; Sat, 19 Nov 2022 02:26:04 -0500 Original-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 ) id 1owIEk-0002Lr-Jx for bug-gnu-emacs@gnu.org; Sat, 19 Nov 2022 02:26:04 -0500 Original-Received: by mail-oo1-xc35.google.com with SMTP id j6-20020a4ab1c6000000b004809a59818cso1115418ooo.0 for ; 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) Original-Received: from 753933720722 named unknown by gmailapi.google.com with HTTPREST; Fri, 18 Nov 2022 23:26:00 -0800 X-Hashcash: 1:20:221119:bug-gnu-emacs@gnu.org::jl0crV3Xf6n6gFDC:9O0K Received-SPF: pass client-ip=2607:f8b0:4864:20::c35; envelope-from=stefankangas@gmail.com; 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-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list X-BeenThere: bug-gnu-emacs@gnu.org List-Id: "Bug reports for GNU Emacs, the Swiss army knife of text editors" List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane-mx.org@gnu.org Original-Sender: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane-mx.org@gnu.org Xref: news.gmane.io gmane.emacs.bugs:248313 Archived-At: 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.