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

Previous Next

Full log

View this message in rfc822 format

From: help-debbugs <at> gnu.org (GNU bug Tracking System)
To: Gemini Lasswell <gazally <at> runbox.com>
Subject: bug#29048: closed (Re: bug#29048: 26.0.90; [PATCH] Improve
 documentation on Edebug and macros)
Date: Mon, 13 Nov 2017 23:43:02 +0000

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

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 <at> debbugs.gnu.org.

-- 
29048: http://debbugs.gnu.org/cgi/bugreport.cgi?bug=29048
GNU Bug Tracking System
Contact help-debbugs <at> gnu.org with problems

[Message part 2 (message/rfc822, inline)]

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.

[Message part 3 (message/rfc822, inline)]

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 4 (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

Previous Next

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