GNU bug report logs - #29048
26.0.90; [PATCH] Improve documentation on Edebug and macros

Previous Next

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

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

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

From: Gemini Lasswell <gazally <at> runbox.com>
To: bug-gnu-emacs <at> gnu.org
Subject: 26.0.90; [PATCH] Improve documentation on Edebug and macros
Date: Sat, 28 Oct 2017 18:01:43 -0700

[Message part 1 (text/plain, inline)]

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.

[0001-Improve-documentation-of-Edebug-and-macros.patch (text/plain, inline)]

From 648f33d68218ac89d941eb78aa6f6d2934e6f97e Mon Sep 17 00:00:00 2001
From: Gemini Lasswell <gazally <at> runbox.com>
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

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

From: Eli Zaretskii <eliz <at> gnu.org>
To: Gemini Lasswell <gazally <at> runbox.com>
Cc: 29048 <at> debbugs.gnu.org
Subject: Re: bug#29048: 26.0.90;
 [PATCH] Improve documentation on Edebug and macros
Date: Fri, 03 Nov 2017 15:41:32 +0200

> From: Gemini Lasswell <gazally <at> runbox.com>
> 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'.

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

From: Gemini Lasswell <geminilasswell <at> runbox.com>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: Gemini Lasswell <gazally <at> runbox.com>, 29048 <at> debbugs.gnu.org
Subject: Re: bug#29048: 26.0.90;
 [PATCH] Improve documentation on Edebug and macros
Date: Thu, 09 Nov 2017 09:43:01 -0800

[Message part 1 (text/plain, inline)]

Eli Zaretskii <eliz <at> gnu.org> 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.

[0001-Improve-documentation-of-Edebug-and-macros.patch (text/plain, inline)]

From 4213f586b8207bc0529c664ada005bfc61acfa08 Mon Sep 17 00:00:00 2001
From: Gemini Lasswell <gazally <at> runbox.com>
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

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

From: Eli Zaretskii <eliz <at> gnu.org>
To: Gemini Lasswell <geminilasswell <at> runbox.com>
Cc: gazally <at> runbox.com, 29048 <at> debbugs.gnu.org
Subject: Re: bug#29048: 26.0.90;
 [PATCH] Improve documentation on Edebug and macros
Date: Thu, 09 Nov 2017 22:15:53 +0200

> From: Gemini Lasswell <geminilasswell <at> runbox.com>
> Cc: Gemini Lasswell <gazally <at> runbox.com>,  29048 <at> debbugs.gnu.org
> Date: Thu, 09 Nov 2017 09:43:01 -0800
> 
> Eli Zaretskii <eliz <at> gnu.org> 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.

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

From: Gemini Lasswell <gazally <at> runbox.com>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: 29048-done <at> debbugs.gnu.org
Subject: Re: bug#29048: 26.0.90;
 [PATCH] Improve documentation on Edebug and macros
Date: Mon, 13 Nov 2017 15:42:08 -0800

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

> OK, thanks.  This is good to go.

I've pushed this to emacs-26.

Previous Next

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