From unknown Tue Aug 19 02:52:26 2025 X-Loop: help-debbugs@gnu.org Subject: bug#29048: 26.0.90; [PATCH] Improve documentation on Edebug and macros Resent-From: Gemini Lasswell Original-Sender: "Debbugs-submit" Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Sun, 29 Oct 2017 01:03:02 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: report 29048 X-GNU-PR-Package: emacs X-GNU-PR-Keywords: patch To: 29048@debbugs.gnu.org X-Debbugs-Original-To: bug-gnu-emacs@gnu.org Received: via spool by submit@debbugs.gnu.org id=B.150923893916652 (code B ref -1); Sun, 29 Oct 2017 01:03:02 +0000 Received: (at submit) by debbugs.gnu.org; 29 Oct 2017 01:02:19 +0000 Received: from localhost ([127.0.0.1]:39583 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1e8bzW-0004KW-OC for submit@debbugs.gnu.org; Sat, 28 Oct 2017 21:02:19 -0400 Received: from eggs.gnu.org ([208.118.235.92]:58944) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1e8bzU-0004KJ-FE for submit@debbugs.gnu.org; Sat, 28 Oct 2017 21:02:17 -0400 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1e8bzO-0003B9-0z for submit@debbugs.gnu.org; Sat, 28 Oct 2017 21:02:11 -0400 X-Spam-Checker-Version: SpamAssassin 3.3.2 (2011-06-06) on eggs.gnu.org X-Spam-Level: * X-Spam-Status: No, score=1.3 required=5.0 tests=BAYES_50,FREEMAIL_FROM, RCVD_IN_SORBS_SPAM,T_DKIM_INVALID autolearn=disabled version=3.3.2 Received: from lists.gnu.org ([2001:4830:134:3::11]:54997) by eggs.gnu.org with esmtps (TLS1.0:RSA_AES_256_CBC_SHA1:32) (Exim 4.71) (envelope-from ) id 1e8bzN-0003Az-TT for submit@debbugs.gnu.org; Sat, 28 Oct 2017 21:02:09 -0400 Received: from eggs.gnu.org ([2001:4830:134:3::10]:49908) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1e8bzM-0007QQ-IY for bug-gnu-emacs@gnu.org; Sat, 28 Oct 2017 21:02:09 -0400 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1e8bzI-00038k-KF for bug-gnu-emacs@gnu.org; Sat, 28 Oct 2017 21:02:08 -0400 Received: from aibo.runbox.com ([91.220.196.211]:55584) by eggs.gnu.org with esmtps (TLS1.0:RSA_AES_128_CBC_SHA1:16) (Exim 4.71) (envelope-from ) id 1e8bzI-00036u-7X for bug-gnu-emacs@gnu.org; Sat, 28 Oct 2017 21:02:04 -0400 DKIM-Signature: v=1; a=rsa-sha256; q=dns/txt; c=relaxed/relaxed; d=runbox.com; s=rbselector1; h=Content-Type:MIME-Version:Message-ID:Date:Subject:To:From; bh=YPLnXfPA4WiTIegqXDpPIFOezA7E8nr2eOsLA9xFtSo=; b=aPd4YyXps5SsySxK8Mmff5Oe3 puMLBwYVxW8zXV9aScFWzgttTbi2ZtWqsMj800IZRz6+Ai9+O9LbKRxcZOZ5/u2yp19x5YVkZZJRK kYO6OdYHubNYqSFDd2klQTs/WnyDjcOcaumArq0iR+BjhqKsTfaSGO8qxD9H9nNNUcUO/P6QUzHtp wyVvKkvBiXzP/eWTw5dUUalSY2w9rdw92DM0yHbHbbQcxtnDpdfXQokNsjDW9CR17cbF3W/60ID1C DtLeCjh0iCLTbDOTQE7tAA0oxMFwwCJggAmJPBXSnpmYbOFRL3Srh/ZEfFsrsLSuJkRH/evCN6/i3 w+mwpioLQ==; Received: from [10.9.9.211] (helo=mailfront11.runbox.com) by mailtransmit03.runbox with esmtp (Exim 4.86_2) (envelope-from ) id 1e8bzA-0007GP-Ro for bug-gnu-emacs@gnu.org; Sun, 29 Oct 2017 02:01:56 +0100 Received: from c-24-22-244-161.hsd1.wa.comcast.net ([24.22.244.161] helo=chinook) by mailfront11.runbox.com with esmtpsa (uid:179284 ) (TLS1.2:RSA_AES_256_CBC_SHA1:256) (Exim 4.82) id 1e8byz-0004DG-Ne for bug-gnu-emacs@gnu.org; Sun, 29 Oct 2017 02:01:46 +0100 From: Gemini Lasswell Date: Sat, 28 Oct 2017 18:01:43 -0700 Message-ID: <87mv4abwco.fsf@runbox.com> MIME-Version: 1.0 Content-Type: multipart/mixed; boundary="=-=-=" X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.2.x-3.x [generic] [fuzzy] X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.6.x X-Received-From: 2001:4830:134:3::11 X-Spam-Score: -3.6 (---) X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: -3.6 (---) --=-=-= Content-Type: text/plain Here are a few suggestions to try to make that dense section of the manual on Edebug and macros a little clearer. I'd like to remove mention of eval-when-compile from the explanation of how to make sure macro specifications are available, because it's not the only way to get yourself in that situation. If you navigate to a function in a file that's not yet loaded which uses a macro in a different file required by the first file and also not yet loaded, and C-u C-M-x, Edebug will complain due to the lack of macro spec regardless of whether the never-executed require in the first file was wrapped with eval-when-compile. --=-=-= Content-Type: text/plain Content-Disposition: inline; filename=0001-Improve-documentation-of-Edebug-and-macros.patch >From 648f33d68218ac89d941eb78aa6f6d2934e6f97e Mon Sep 17 00:00:00 2001 From: Gemini Lasswell Date: Sat, 28 Oct 2017 13:47:15 -0700 Subject: [PATCH] Improve documentation of Edebug and macros * doc/lispref/edebug.texi (Instrumenting Macro Calls): Refer to `require' instead of `eval-when-compile' in discussion of loading macro specifications before instrumenting. (Specification List): Clarify what "defining form" means to Edebug and when `def-form' or `def-body' should be used instead of `form' or `body'. --- doc/lispref/edebug.texi | 30 ++++++++++++++++++++---------- 1 file changed, 20 insertions(+), 10 deletions(-) diff --git a/doc/lispref/edebug.texi b/doc/lispref/edebug.texi index cebf0a3af3..e1c1e26bc5 100644 --- a/doc/lispref/edebug.texi +++ b/doc/lispref/edebug.texi @@ -1144,9 +1144,10 @@ Instrumenting Macro Calls @c automatically load the entire source file containing the function @c being instrumented. That would avoid this. Take care to ensure that the specifications are known to Edebug when -you instrument code. If you are instrumenting a function from a file -that uses @code{eval-when-compile} to require another file containing -macro definitions, you may need to explicitly load that file. +you instrument code. If you are instrumenting a function which uses a +macro defined in another file, you may first need to either evaluate +the @code{require} forms in the file containing your function, or +explicitly load the file containing the macro. You can also define an edebug specification for a macro separately from the macro definition with @code{def-edebug-spec}. Adding @@ -1231,13 +1232,17 @@ Specification List @c an "expression" is not necessarily intended for evaluation. @item form -A single evaluated expression, which is instrumented. +A single evaluated expression, which is instrumented. If your macro +wraps the expression with @code{lambda} before it is evaluated, use +@code{def-form} instead. See @code{def-form} below. @item place A generalized variable. @xref{Generalized Variables}. @item body -Short for @code{&rest form}. See @code{&rest} below. +Short for @code{&rest form}. See @code{&rest} below. If your macro +wraps its body of code with @code{lambda} before it is evaluated, use +@code{def-body} instead. See @code{def-body} below. @item function-form A function form: either a quoted function symbol, a quoted lambda @@ -1292,11 +1297,16 @@ Specification List @item &define @c @kindex &define @r{(Edebug)} -Indicates that the specification is for a defining form. The defining -form itself is not instrumented (that is, Edebug does not stop before and -after the defining form), but forms inside it typically will be -instrumented. The @code{&define} keyword should be the first element in -a list specification. + +Indicates that the specification is for a defining form. Edebug's +definition of a defining form is a form containing one or more code +forms which are saved and executed later, after the execution of the +defining form. + +The defining form itself is not instrumented (that is, Edebug does not +stop before and after the defining form), but forms inside it +typically will be instrumented. The @code{&define} keyword should be +the first element in a list specification. @item nil This is successful when there are no more arguments to match at the -- 2.14.2 --=-=-=-- From unknown Tue Aug 19 02:52:26 2025 X-Loop: help-debbugs@gnu.org Subject: bug#29048: 26.0.90; [PATCH] Improve documentation on Edebug and macros Resent-From: Eli Zaretskii Original-Sender: "Debbugs-submit" Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Fri, 03 Nov 2017 13:42:01 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: followup 29048 X-GNU-PR-Package: emacs X-GNU-PR-Keywords: patch To: Gemini Lasswell Cc: 29048@debbugs.gnu.org Reply-To: Eli Zaretskii Received: via spool by 29048-submit@debbugs.gnu.org id=B29048.15097165085199 (code B ref 29048); Fri, 03 Nov 2017 13:42:01 +0000 Received: (at 29048) by debbugs.gnu.org; 3 Nov 2017 13:41:48 +0000 Received: from localhost ([127.0.0.1]:48895 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1eAcEG-0001Ll-A1 for submit@debbugs.gnu.org; Fri, 03 Nov 2017 09:41:48 -0400 Received: from eggs.gnu.org ([208.118.235.92]:45734) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1eAcED-0001LX-JR for 29048@debbugs.gnu.org; Fri, 03 Nov 2017 09:41:45 -0400 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1eAcE3-0002xu-Ca for 29048@debbugs.gnu.org; Fri, 03 Nov 2017 09:41:40 -0400 X-Spam-Checker-Version: SpamAssassin 3.3.2 (2011-06-06) on eggs.gnu.org X-Spam-Level: X-Spam-Status: No, score=0.8 required=5.0 tests=BAYES_50,RP_MATCHES_RCVD autolearn=disabled version=3.3.2 Received: from fencepost.gnu.org ([2001:4830:134:3::e]:55842) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1eAcE3-0002xb-8J; Fri, 03 Nov 2017 09:41:35 -0400 Received: from [176.228.60.248] (port=2062 helo=home-c4e4a596f7) by fencepost.gnu.org with esmtpsa (TLS1.2:RSA_AES_256_CBC_SHA1:256) (Exim 4.82) (envelope-from ) id 1eAcE2-0004Wa-KO; Fri, 03 Nov 2017 09:41:35 -0400 Date: Fri, 03 Nov 2017 15:41:32 +0200 Message-Id: <83mv43v5rn.fsf@gnu.org> From: Eli Zaretskii In-reply-to: <87mv4abwco.fsf@runbox.com> (message from Gemini Lasswell on Sat, 28 Oct 2017 18:01:43 -0700) References: <87mv4abwco.fsf@runbox.com> X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.2.x-3.x [generic] X-Received-From: 2001:4830:134:3::e X-Spam-Score: -5.0 (-----) X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: -5.0 (-----) > From: Gemini Lasswell > Date: Sat, 28 Oct 2017 18:01:43 -0700 > > Here are a few suggestions to try to make that dense section of the > manual on Edebug and macros a little clearer. Thanks, this is okay for the release branch. > I'd like to remove mention of eval-when-compile from the explanation > of how to make sure macro specifications are available, because it's > not the only way to get yourself in that situation. If you navigate to > a function in a file that's not yet loaded which uses a macro in a > different file required by the first file and also not yet loaded, and > C-u C-M-x, Edebug will complain due to the lack of macro spec > regardless of whether the never-executed require in the first file was > wrapped with eval-when-compile. That's okay, but please mention eval-when-compile as an example of the broader class of situations with instrumenting code wrapped with macros. > * doc/lispref/edebug.texi (Instrumenting Macro Calls): Refer to > `require' instead of `eval-when-compile' in discussion of loading > macro specifications before instrumenting. In log entries and in NEWS, we use quoting 'like this' nowadays, not `like this'. From unknown Tue Aug 19 02:52:26 2025 X-Loop: help-debbugs@gnu.org Subject: bug#29048: 26.0.90; [PATCH] Improve documentation on Edebug and macros Resent-From: Gemini Lasswell Original-Sender: "Debbugs-submit" Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Thu, 09 Nov 2017 17:44:02 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: followup 29048 X-GNU-PR-Package: emacs X-GNU-PR-Keywords: patch To: Eli Zaretskii Cc: Gemini Lasswell , 29048@debbugs.gnu.org Received: via spool by 29048-submit@debbugs.gnu.org id=B29048.1510249402605 (code B ref 29048); Thu, 09 Nov 2017 17:44:02 +0000 Received: (at 29048) by debbugs.gnu.org; 9 Nov 2017 17:43:22 +0000 Received: from localhost ([127.0.0.1]:60693 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1eCqrK-00009g-2Y for submit@debbugs.gnu.org; Thu, 09 Nov 2017 12:43:22 -0500 Received: from aibo.runbox.com ([91.220.196.211]:38250) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1eCqrH-00009X-Th for 29048@debbugs.gnu.org; Thu, 09 Nov 2017 12:43:20 -0500 DKIM-Signature: v=1; a=rsa-sha256; q=dns/txt; c=relaxed/relaxed; d=runbox.com; s=rbselector1; h=Content-Type:MIME-Version:Message-ID:In-Reply-To:Date: References:Subject:Cc:To:From; bh=mK4tSPhFb1xZDiRv5yEfWxg6WpqGxdylUT0+gd9HOxg=; b=kcVEEH92Pq+Iiov7YtQrZ4vuFb clXp7DUgwcDS8bd18ouIwqSxjdeqU3r+FfCQw6syKECBc204NgckRIuu6ms1kz1qoJSAxYZYbakqm XYtDlducrs+dMJUjdNFBm5AWSIiFlk6brEP0gAKMkWo5TH+reFs82q4NeSjR8R9Ev43Jsgqi73Lqx Ei7Ys/w0RDmEwF/lhmFzK9NcsXed3gVUOBmMGcl4VlbQIyhK8l2UIGS4sr+loKL5Js1/NZHRbJMPO UkTpGH0uKz98gL6NHGbJ5mSk4XWWSqMBnnkuz7vd4EDScqfPy6raLVv8NvtY9J4b5Rw1BqodbkQXH zKFAYBzw==; Received: from [10.9.9.210] (helo=mailfront10.runbox.com) by mailtransmit03.runbox with esmtp (Exim 4.86_2) (envelope-from ) id 1eCqrF-0002ar-Iy; Thu, 09 Nov 2017 18:43:17 +0100 Received: from c-24-22-244-161.hsd1.wa.comcast.net ([24.22.244.161] helo=chinook) by mailfront10.runbox.com with esmtpsa (uid:179284 ) (TLS1.2:RSA_AES_256_CBC_SHA1:256) (Exim 4.82) id 1eCqr1-0007QD-Sn; Thu, 09 Nov 2017 18:43:04 +0100 From: Gemini Lasswell References: <87mv4abwco.fsf@runbox.com> <83mv43v5rn.fsf@gnu.org> Date: Thu, 09 Nov 2017 09:43:01 -0800 In-Reply-To: <83mv43v5rn.fsf@gnu.org> (Eli Zaretskii's message of "Fri, 03 Nov 2017 15:41:32 +0200") Message-ID: <87r2t71h7e.fsf@runbox.com> User-Agent: Gnus/5.13 (Gnus v5.13) Emacs/26.0.90 (gnu/linux) MIME-Version: 1.0 Content-Type: multipart/mixed; boundary="=-=-=" X-Spam-Score: -0.7 (/) X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: -0.7 (/) --=-=-= Content-Type: text/plain Eli Zaretskii writes: > That's okay, but please mention eval-when-compile as an example of the > broader class of situations with instrumenting code wrapped with > macros. OK, here's a revised version. --=-=-= Content-Type: text/plain Content-Disposition: inline; filename=0001-Improve-documentation-of-Edebug-and-macros.patch >From 4213f586b8207bc0529c664ada005bfc61acfa08 Mon Sep 17 00:00:00 2001 From: Gemini Lasswell Date: Sat, 28 Oct 2017 13:47:15 -0700 Subject: [PATCH] Improve documentation of Edebug and macros * doc/lispref/edebug.texi (Instrumenting Macro Calls): Improve discussion of when it might be necessary to find and evaluate macro specifications before instrumenting. (Specification List): Clarify what "defining form" means to Edebug and when 'def-form' or 'def-body' should be used instead of 'form' or 'body'. --- doc/lispref/edebug.texi | 32 ++++++++++++++++++++++---------- 1 file changed, 22 insertions(+), 10 deletions(-) diff --git a/doc/lispref/edebug.texi b/doc/lispref/edebug.texi index cebf0a3af3..62fd9f38cb 100644 --- a/doc/lispref/edebug.texi +++ b/doc/lispref/edebug.texi @@ -1144,9 +1144,12 @@ Instrumenting Macro Calls @c automatically load the entire source file containing the function @c being instrumented. That would avoid this. Take care to ensure that the specifications are known to Edebug when -you instrument code. If you are instrumenting a function from a file -that uses @code{eval-when-compile} to require another file containing -macro definitions, you may need to explicitly load that file. +you instrument code. If you are instrumenting a function which uses a +macro defined in another file, you may first need to either evaluate +the @code{require} forms in the file containing your function, or +explicitly load the file containing the macro. If the definition of a +macro is wrapped by @code{eval-when-compile}, you may need to evaluate +it. You can also define an edebug specification for a macro separately from the macro definition with @code{def-edebug-spec}. Adding @@ -1231,13 +1234,17 @@ Specification List @c an "expression" is not necessarily intended for evaluation. @item form -A single evaluated expression, which is instrumented. +A single evaluated expression, which is instrumented. If your macro +wraps the expression with @code{lambda} before it is evaluated, use +@code{def-form} instead. See @code{def-form} below. @item place A generalized variable. @xref{Generalized Variables}. @item body -Short for @code{&rest form}. See @code{&rest} below. +Short for @code{&rest form}. See @code{&rest} below. If your macro +wraps its body of code with @code{lambda} before it is evaluated, use +@code{def-body} instead. See @code{def-body} below. @item function-form A function form: either a quoted function symbol, a quoted lambda @@ -1292,11 +1299,16 @@ Specification List @item &define @c @kindex &define @r{(Edebug)} -Indicates that the specification is for a defining form. The defining -form itself is not instrumented (that is, Edebug does not stop before and -after the defining form), but forms inside it typically will be -instrumented. The @code{&define} keyword should be the first element in -a list specification. + +Indicates that the specification is for a defining form. Edebug's +definition of a defining form is a form containing one or more code +forms which are saved and executed later, after the execution of the +defining form. + +The defining form itself is not instrumented (that is, Edebug does not +stop before and after the defining form), but forms inside it +typically will be instrumented. The @code{&define} keyword should be +the first element in a list specification. @item nil This is successful when there are no more arguments to match at the -- 2.14.3 --=-=-=-- From unknown Tue Aug 19 02:52:26 2025 X-Loop: help-debbugs@gnu.org Subject: bug#29048: 26.0.90; [PATCH] Improve documentation on Edebug and macros Resent-From: Eli Zaretskii Original-Sender: "Debbugs-submit" Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Thu, 09 Nov 2017 20:17:01 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: followup 29048 X-GNU-PR-Package: emacs X-GNU-PR-Keywords: patch To: Gemini Lasswell Cc: gazally@runbox.com, 29048@debbugs.gnu.org Reply-To: Eli Zaretskii Received: via spool by 29048-submit@debbugs.gnu.org id=B29048.151025857029564 (code B ref 29048); Thu, 09 Nov 2017 20:17:01 +0000 Received: (at 29048) by debbugs.gnu.org; 9 Nov 2017 20:16:10 +0000 Received: from localhost ([127.0.0.1]:60850 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1eCtFB-0007gm-Mb for submit@debbugs.gnu.org; Thu, 09 Nov 2017 15:16:10 -0500 Received: from eggs.gnu.org ([208.118.235.92]:41842) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1eCtF7-0007fx-V5 for 29048@debbugs.gnu.org; Thu, 09 Nov 2017 15:16:06 -0500 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1eCtEz-0001Gr-Pl for 29048@debbugs.gnu.org; Thu, 09 Nov 2017 15:16:00 -0500 X-Spam-Checker-Version: SpamAssassin 3.3.2 (2011-06-06) on eggs.gnu.org X-Spam-Level: X-Spam-Status: No, score=-1.9 required=5.0 tests=BAYES_00,RP_MATCHES_RCVD autolearn=disabled version=3.3.2 Received: from fencepost.gnu.org ([2001:4830:134:3::e]:43138) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1eCtEz-0001Gl-Lh; Thu, 09 Nov 2017 15:15:57 -0500 Received: from [176.228.60.248] (port=3176 helo=home-c4e4a596f7) by fencepost.gnu.org with esmtpsa (TLS1.2:RSA_AES_256_CBC_SHA1:256) (Exim 4.82) (envelope-from ) id 1eCtEy-0004zQ-CZ; Thu, 09 Nov 2017 15:15:57 -0500 Date: Thu, 09 Nov 2017 22:15:53 +0200 Message-Id: <83fu9nqkcm.fsf@gnu.org> From: Eli Zaretskii In-reply-to: <87r2t71h7e.fsf@runbox.com> (message from Gemini Lasswell on Thu, 09 Nov 2017 09:43:01 -0800) References: <87mv4abwco.fsf@runbox.com> <83mv43v5rn.fsf@gnu.org> <87r2t71h7e.fsf@runbox.com> X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.2.x-3.x [generic] X-Received-From: 2001:4830:134:3::e X-Spam-Score: -5.0 (-----) X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: -5.0 (-----) > From: Gemini Lasswell > Cc: Gemini Lasswell , 29048@debbugs.gnu.org > Date: Thu, 09 Nov 2017 09:43:01 -0800 > > Eli Zaretskii writes: > > > That's okay, but please mention eval-when-compile as an example of the > > broader class of situations with instrumenting code wrapped with > > macros. > > OK, here's a revised version. OK, thanks. This is good to go. From unknown Tue Aug 19 02:52:26 2025 MIME-Version: 1.0 X-Mailer: MIME-tools 5.505 (Entity 5.505) X-Loop: help-debbugs@gnu.org From: help-debbugs@gnu.org (GNU bug Tracking System) To: Gemini Lasswell Subject: bug#29048: closed (Re: bug#29048: 26.0.90; [PATCH] Improve documentation on Edebug and macros) Message-ID: References: <87o9o5g2zz.fsf@runbox.com> <87mv4abwco.fsf@runbox.com> X-Gnu-PR-Message: they-closed 29048 X-Gnu-PR-Package: emacs X-Gnu-PR-Keywords: patch Reply-To: 29048@debbugs.gnu.org Date: Mon, 13 Nov 2017 23:43:02 +0000 Content-Type: multipart/mixed; boundary="----------=_1510616582-20304-1" This is a multi-part message in MIME format... ------------=_1510616582-20304-1 Content-Disposition: inline Content-Transfer-Encoding: quoted-printable Content-Type: text/plain; charset="utf-8" Your bug report #29048: 26.0.90; [PATCH] Improve documentation on Edebug and macros which was filed against the emacs package, has been closed. The explanation is attached below, along with your original report. If you require more details, please reply to 29048@debbugs.gnu.org. --=20 29048: http://debbugs.gnu.org/cgi/bugreport.cgi?bug=3D29048 GNU Bug Tracking System Contact help-debbugs@gnu.org with problems ------------=_1510616582-20304-1 Content-Type: message/rfc822 Content-Disposition: inline Content-Transfer-Encoding: 7bit Received: (at 29048-done) by debbugs.gnu.org; 13 Nov 2017 23:42:20 +0000 Received: from localhost ([127.0.0.1]:39057 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1eEOMt-0005Ga-Qs for submit@debbugs.gnu.org; Mon, 13 Nov 2017 18:42:19 -0500 Received: from aibo.runbox.com ([91.220.196.211]:34114) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1eEOMr-0005GS-Un for 29048-done@debbugs.gnu.org; Mon, 13 Nov 2017 18:42:18 -0500 DKIM-Signature: v=1; a=rsa-sha256; q=dns/txt; c=relaxed/relaxed; d=runbox.com; s=rbselector1; h=Content-Type:MIME-Version:Message-ID:In-Reply-To:Date: References:Subject:Cc:To:From; bh=XnmPWEca+17HNuBh4ZiKVz7Q8rQCzQklL6hA+P5AOas=; b=LdrusI9GNw12/7BZ89sJ6k887I F0KQsirj43Qm4Ywj3cvFF3kUOQHCycqp7KMaxx2Ie82GZq2EqdYX7F5VBHbGR4PaYufMlmwOK1gFe VRkIPXhMxn7PObgwaLj6fXMn87nIleGlXJm4yA4+HyfWpDb4wSbOrERqUEFjUv2TLutcBnv9c3Qb1 5iXjOKbhVsvC64pk2cQA+YHceWoPSu26FNrP7aOg8mWIglfrpWAUWl6FuXhTYl3q658wOhS+ZFLW7 sHrWALTIw60KVYVzLfkKMFbDesOsCi4H5UhmyDPK+GpG0Mavr3ujKF2p4j5ls6fDk4tewBNTys/u3 MuZz1hvQ==; Received: from [10.9.9.211] (helo=mailfront11.runbox.com) by mailtransmit02.runbox with esmtp (Exim 4.86_2) (envelope-from ) id 1eEOMq-0004NY-C8; Tue, 14 Nov 2017 00:42:16 +0100 Received: from 207-118-94-15.dyn.centurytel.net ([207.118.94.15] helo=sockeye) by mailfront11.runbox.com with esmtpsa (uid:179284 ) (TLS1.2:RSA_AES_256_CBC_SHA1:256) (Exim 4.82) id 1eEOMl-00087a-JT; Tue, 14 Nov 2017 00:42:12 +0100 From: Gemini Lasswell To: Eli Zaretskii Subject: Re: bug#29048: 26.0.90; [PATCH] Improve documentation on Edebug and macros References: <87mv4abwco.fsf@runbox.com> <83mv43v5rn.fsf@gnu.org> <87r2t71h7e.fsf@runbox.com> <83fu9nqkcm.fsf@gnu.org> Date: Mon, 13 Nov 2017 15:42:08 -0800 In-Reply-To: <83fu9nqkcm.fsf@gnu.org> (Eli Zaretskii's message of "Thu, 09 Nov 2017 22:15:53 +0200") Message-ID: <87o9o5g2zz.fsf@runbox.com> User-Agent: Gnus/5.13 (Gnus v5.13) Emacs/26.0.90 (gnu/linux) MIME-Version: 1.0 Content-Type: text/plain X-Spam-Score: -0.7 (/) X-Debbugs-Envelope-To: 29048-done Cc: 29048-done@debbugs.gnu.org X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: -0.7 (/) Eli Zaretskii writes: > OK, thanks. This is good to go. I've pushed this to emacs-26. ------------=_1510616582-20304-1 Content-Type: message/rfc822 Content-Disposition: inline Content-Transfer-Encoding: 7bit Received: (at submit) by debbugs.gnu.org; 29 Oct 2017 01:02:19 +0000 Received: from localhost ([127.0.0.1]:39583 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1e8bzW-0004KW-OC for submit@debbugs.gnu.org; Sat, 28 Oct 2017 21:02:19 -0400 Received: from eggs.gnu.org ([208.118.235.92]:58944) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1e8bzU-0004KJ-FE for submit@debbugs.gnu.org; Sat, 28 Oct 2017 21:02:17 -0400 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1e8bzO-0003B9-0z for submit@debbugs.gnu.org; Sat, 28 Oct 2017 21:02:11 -0400 X-Spam-Checker-Version: SpamAssassin 3.3.2 (2011-06-06) on eggs.gnu.org X-Spam-Level: * X-Spam-Status: No, score=1.3 required=5.0 tests=BAYES_50,FREEMAIL_FROM, RCVD_IN_SORBS_SPAM,T_DKIM_INVALID autolearn=disabled version=3.3.2 Received: from lists.gnu.org ([2001:4830:134:3::11]:54997) by eggs.gnu.org with esmtps (TLS1.0:RSA_AES_256_CBC_SHA1:32) (Exim 4.71) (envelope-from ) id 1e8bzN-0003Az-TT for submit@debbugs.gnu.org; Sat, 28 Oct 2017 21:02:09 -0400 Received: from eggs.gnu.org ([2001:4830:134:3::10]:49908) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1e8bzM-0007QQ-IY for bug-gnu-emacs@gnu.org; Sat, 28 Oct 2017 21:02:09 -0400 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1e8bzI-00038k-KF for bug-gnu-emacs@gnu.org; Sat, 28 Oct 2017 21:02:08 -0400 Received: from aibo.runbox.com ([91.220.196.211]:55584) by eggs.gnu.org with esmtps (TLS1.0:RSA_AES_128_CBC_SHA1:16) (Exim 4.71) (envelope-from ) id 1e8bzI-00036u-7X for bug-gnu-emacs@gnu.org; Sat, 28 Oct 2017 21:02:04 -0400 DKIM-Signature: v=1; a=rsa-sha256; q=dns/txt; c=relaxed/relaxed; d=runbox.com; s=rbselector1; h=Content-Type:MIME-Version:Message-ID:Date:Subject:To:From; bh=YPLnXfPA4WiTIegqXDpPIFOezA7E8nr2eOsLA9xFtSo=; b=aPd4YyXps5SsySxK8Mmff5Oe3 puMLBwYVxW8zXV9aScFWzgttTbi2ZtWqsMj800IZRz6+Ai9+O9LbKRxcZOZ5/u2yp19x5YVkZZJRK kYO6OdYHubNYqSFDd2klQTs/WnyDjcOcaumArq0iR+BjhqKsTfaSGO8qxD9H9nNNUcUO/P6QUzHtp wyVvKkvBiXzP/eWTw5dUUalSY2w9rdw92DM0yHbHbbQcxtnDpdfXQokNsjDW9CR17cbF3W/60ID1C DtLeCjh0iCLTbDOTQE7tAA0oxMFwwCJggAmJPBXSnpmYbOFRL3Srh/ZEfFsrsLSuJkRH/evCN6/i3 w+mwpioLQ==; Received: from [10.9.9.211] (helo=mailfront11.runbox.com) by mailtransmit03.runbox with esmtp (Exim 4.86_2) (envelope-from ) id 1e8bzA-0007GP-Ro for bug-gnu-emacs@gnu.org; Sun, 29 Oct 2017 02:01:56 +0100 Received: from c-24-22-244-161.hsd1.wa.comcast.net ([24.22.244.161] helo=chinook) by mailfront11.runbox.com with esmtpsa (uid:179284 ) (TLS1.2:RSA_AES_256_CBC_SHA1:256) (Exim 4.82) id 1e8byz-0004DG-Ne for bug-gnu-emacs@gnu.org; Sun, 29 Oct 2017 02:01:46 +0100 From: Gemini Lasswell To: bug-gnu-emacs@gnu.org Subject: 26.0.90; [PATCH] Improve documentation on Edebug and macros Date: Sat, 28 Oct 2017 18:01:43 -0700 Message-ID: <87mv4abwco.fsf@runbox.com> MIME-Version: 1.0 Content-Type: multipart/mixed; boundary="=-=-=" X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.2.x-3.x [generic] [fuzzy] X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.6.x X-Received-From: 2001:4830:134:3::11 X-Spam-Score: -3.6 (---) X-Debbugs-Envelope-To: submit X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: -3.6 (---) --=-=-= Content-Type: text/plain Here are a few suggestions to try to make that dense section of the manual on Edebug and macros a little clearer. I'd like to remove mention of eval-when-compile from the explanation of how to make sure macro specifications are available, because it's not the only way to get yourself in that situation. If you navigate to a function in a file that's not yet loaded which uses a macro in a different file required by the first file and also not yet loaded, and C-u C-M-x, Edebug will complain due to the lack of macro spec regardless of whether the never-executed require in the first file was wrapped with eval-when-compile. --=-=-= Content-Type: text/plain Content-Disposition: inline; filename=0001-Improve-documentation-of-Edebug-and-macros.patch >From 648f33d68218ac89d941eb78aa6f6d2934e6f97e Mon Sep 17 00:00:00 2001 From: Gemini Lasswell Date: Sat, 28 Oct 2017 13:47:15 -0700 Subject: [PATCH] Improve documentation of Edebug and macros * doc/lispref/edebug.texi (Instrumenting Macro Calls): Refer to `require' instead of `eval-when-compile' in discussion of loading macro specifications before instrumenting. (Specification List): Clarify what "defining form" means to Edebug and when `def-form' or `def-body' should be used instead of `form' or `body'. --- doc/lispref/edebug.texi | 30 ++++++++++++++++++++---------- 1 file changed, 20 insertions(+), 10 deletions(-) diff --git a/doc/lispref/edebug.texi b/doc/lispref/edebug.texi index cebf0a3af3..e1c1e26bc5 100644 --- a/doc/lispref/edebug.texi +++ b/doc/lispref/edebug.texi @@ -1144,9 +1144,10 @@ Instrumenting Macro Calls @c automatically load the entire source file containing the function @c being instrumented. That would avoid this. Take care to ensure that the specifications are known to Edebug when -you instrument code. If you are instrumenting a function from a file -that uses @code{eval-when-compile} to require another file containing -macro definitions, you may need to explicitly load that file. +you instrument code. If you are instrumenting a function which uses a +macro defined in another file, you may first need to either evaluate +the @code{require} forms in the file containing your function, or +explicitly load the file containing the macro. You can also define an edebug specification for a macro separately from the macro definition with @code{def-edebug-spec}. Adding @@ -1231,13 +1232,17 @@ Specification List @c an "expression" is not necessarily intended for evaluation. @item form -A single evaluated expression, which is instrumented. +A single evaluated expression, which is instrumented. If your macro +wraps the expression with @code{lambda} before it is evaluated, use +@code{def-form} instead. See @code{def-form} below. @item place A generalized variable. @xref{Generalized Variables}. @item body -Short for @code{&rest form}. See @code{&rest} below. +Short for @code{&rest form}. See @code{&rest} below. If your macro +wraps its body of code with @code{lambda} before it is evaluated, use +@code{def-body} instead. See @code{def-body} below. @item function-form A function form: either a quoted function symbol, a quoted lambda @@ -1292,11 +1297,16 @@ Specification List @item &define @c @kindex &define @r{(Edebug)} -Indicates that the specification is for a defining form. The defining -form itself is not instrumented (that is, Edebug does not stop before and -after the defining form), but forms inside it typically will be -instrumented. The @code{&define} keyword should be the first element in -a list specification. + +Indicates that the specification is for a defining form. Edebug's +definition of a defining form is a form containing one or more code +forms which are saved and executed later, after the execution of the +defining form. + +The defining form itself is not instrumented (that is, Edebug does not +stop before and after the defining form), but forms inside it +typically will be instrumented. The @code{&define} keyword should be +the first element in a list specification. @item nil This is successful when there are no more arguments to match at the -- 2.14.2 --=-=-=-- ------------=_1510616582-20304-1--