Edebug doc fixes

* doc/lispref/edebug.texi (Instrumenting Macro Calls):
Mention defining macros at instrumentation time.
(Edebug Options): Mention edebug-unwrap-results.

* lisp/emacs-lisp/edebug.el (edebug-unwrap-results): Doc fix.
Comments.

* admin/FOR-RELEASE: Markup.

diff --git a/admin/FOR-RELEASE b/admin/FOR-RELEASE
index 1f498e06c31de06c58427ae67545d6adb7a72f00..ec12b977b9eea62e450d8a82c877fc8392208b5a 100644 (file)
--- a/admin/FOR-RELEASE
+++ b/admin/FOR-RELEASE
@@ -183,7 +183,7 @@ xresources.texi   cyd
 abbrevs.texi      rgm
 advice.texi       cyd
 anti.texi         
-back.texi
+back.texi         rgm
 backups.texi      cyd
 buffers.texi      cyd
 commands.texi     cyd
@@ -192,7 +192,7 @@ control.texi      cyd
 customize.texi    cyd
 debugging.texi    cyd
 display.texi      cyd
-edebug.texi
+edebug.texi       rgm
 elisp.texi
 errors.texi       rgm
 eval.texi         cyd

diff --git a/doc/lispref/ChangeLog b/doc/lispref/ChangeLog
index b0f9b7c586e3b0bafe07bc3e02e56f8086e4fa03..cb7a5c48e158ae1b0167d28cd862a3db780287ef 100644 (file)
--- a/doc/lispref/ChangeLog
+++ b/doc/lispref/ChangeLog
@@ -1,3 +1,9 @@
+2012-03-31  Glenn Morris  <rgm@gnu.org>
+
+       * edebug.texi (Instrumenting Macro Calls):
+       Mention defining macros at instrumentation time.
+       (Edebug Options): Mention edebug-unwrap-results.
+
 2012-03-31  Eli Zaretskii  <eliz@gnu.org>
 
        * text.texi (Special Properties): Clarify the description of the

diff --git a/doc/lispref/edebug.texi b/doc/lispref/edebug.texi
index 33e5e54f1c61cc94eba7200a4f8e5748a1b1b8d5..245aaf94c6db6370930c19d1b91a85197b7bbb5c 100644 (file)
--- a/doc/lispref/edebug.texi
+++ b/doc/lispref/edebug.texi
@@ -1113,6 +1113,15 @@ definition, but specifications are much more general than macro
 arguments.  @xref{Defining Macros}, for more explanation of
 the @code{declare} form.
 
+@c See eg http://debbugs.gnu.org/10577
+@c FIXME  Maybe there should be an Edebug option to get it to
+@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 can also define an edebug specification for a macro separately
 from the macro definition with @code{def-edebug-spec}.  Adding
 @code{debug} declarations is preferred, and more convenient, for macro
@@ -1255,6 +1264,8 @@ Each of the following elements is matched as alternatives as if by using
 of them match, nothing is matched, but the @code{&not} specification
 succeeds.
 
+@c FIXME &key?
+
 @item &define
 @c @kindex &define @r{(Edebug)}
 Indicates that the specification is for a defining form.  The defining
@@ -1422,7 +1433,15 @@ of the bindings is either a symbol or a sublist with a symbol and
 optional expression.  In the specification below, notice the @code{gate}
 inside of the sublist to prevent backtracking once a sublist is found.
 
-@c FIXME? The actual definition in edebug.el does not have a gate.
+@ignore
+@c FIXME?  The actual definition in edebug.el looks like this (and always
+@c has AFAICS).  In fact, nothing in edebug.el uses gate.  So maybe
+@c this is just an example for illustration?
+(def-edebug-spec let
+  ((&rest
+    &or (symbolp &optional form) symbolp)
+   body))
+@end ignore
 @example
 (def-edebug-spec let
   ((&rest
@@ -1566,7 +1585,28 @@ debugged.
 @xref{Edebug Execution Modes}.
 @end defopt
 
-@c FIXME edebug-unwrap-results
+@defopt edebug-unwrap-results
+If non-@code{nil}, Edebug tries to remove any of its own
+instrumentation when showing the results of expressions.  This is
+relevant when debugging macros where the results of expressions are
+themselves instrumented expressions.  As a very artificial example,
+suppose that the example function @code{fac} has been instrumented,
+and consider a macro of the form:
+
+@c FIXME find a less silly example.
+@smallexample
+(defmacro test () "Edebug example."
+  (if (symbol-function 'fac)
+      @dots{}))
+@end smallexample
+
+If you instrument the @code{test} macro and step through it, then by
+default the result of the @code{symbol-function} call has numerous
+@code{edebug-after} and @code{edebug-before} forms, which can make it
+difficult to see the ``actual'' result.  If
+@code{edebug-unwrap-results} is non-@code{nil}, Edebug tries to remove
+these forms from the result.
+@end defopt
 
 @defopt edebug-on-error
 Edebug binds @code{debug-on-error} to this value, if

diff --git a/lisp/ChangeLog b/lisp/ChangeLog
index 2def7e4c93468742eedcc14db924655aca1425c3..970c74bf50f86b825fc4122a2823d2673ae37d89 100644 (file)
--- a/lisp/ChangeLog
+++ b/lisp/ChangeLog
@@ -1,3 +1,7 @@
+2012-03-31  Glenn Morris  <rgm@gnu.org>
+
+       * emacs-lisp/edebug.el (edebug-unwrap-results): Doc fix.
+
 2012-03-30  Thierry Volpiatto  <thierry.volpiatto@gmail.com>
 
        * dired-aux.el (dired-copy-file-recursive, dired-create-files):

diff --git a/lisp/emacs-lisp/edebug.el b/lisp/emacs-lisp/edebug.el
index c241ac710cf6697de618491bdf9a29e32803067b..67ffd6d5d31bc3379ea498603a5e1c1cded70de8 100644 (file)
--- a/lisp/emacs-lisp/edebug.el
+++ b/lisp/emacs-lisp/edebug.el
@@ -1,6 +1,6 @@
 ;;; edebug.el --- a source-level debugger for Emacs Lisp
 
-;; Copyright (C) 1988-1995, 1997, 1999-2012  Free Software Foundation, Inc.
+;; Copyright (C) 1988-1995, 1997, 1999-2012 Free Software Foundation, Inc.
 
 ;; Author: Daniel LaLiberte <liberte@holonexus.org>
 ;; Maintainer: FSF
@@ -191,6 +191,7 @@ Use this with caution since it is not debugged."
 
 (defcustom edebug-unwrap-results nil
   "Non-nil if Edebug should unwrap results of expressions.
+That is, Edebug will try to remove its own instrumentation from the result.
 This is useful when debugging macros where the results of expressions
 are instrumented expressions.  But don't do this when results might be
 circular or an infinite loop will result."
@@ -2028,7 +2029,10 @@ expressions; a `progn' form will be returned enclosing these forms."
 (def-edebug-spec apply (function-form &rest form))
 (def-edebug-spec funcall (function-form &rest form))
 
-;; FIXME? The manual has a gate here.
+;; FIXME?  The manual uses this form (maybe that's just for illustration?):
+;; (def-edebug-spec let
+;;   ((&rest &or symbolp (gate symbolp &optional form))
+;;    body))
 (def-edebug-spec let
   ((&rest &or (symbolp &optional form) symbolp)
    body))
@@ -4157,6 +4161,8 @@ You must include newlines in FMT to break lines, but one newline is appended."
 ;;; Frequency count and coverage
 
 ;; FIXME should this use overlays instead?
+;; Definitely, IMO.  The current business with undo in
+;; edebug-temp-display-freq-count is horrid.
 (defun edebug-display-freq-count ()
   "Display the frequency count data for each line of the current definition.
 The frequency counts are inserted as comment lines after each line,
@@ -4226,6 +4232,8 @@ reinstrument it."
        (insert "\n")
        (setq i first-index)))))
 
+;; FIXME this does not work very well.  Eg if you press an arrow key,
+;; or make a mouse-click, it fails with "Non-character input-event".
 (defun edebug-temp-display-freq-count ()
   "Temporarily display the frequency count data for the current definition.
 It is removed when you hit any char."
@@ -4235,6 +4243,7 @@ It is removed when you hit any char."
     (undo-boundary)
     (edebug-display-freq-count)
     (setq unread-command-char (read-char))
+    ;; Yuck!  This doesn't seem to work at all for me.
     (undo)))
 
 \f