Commit 0b021094 authored by Glenn Morris's avatar Glenn Morris

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.
parent 979022ef
......@@ -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
......
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
......
......@@ -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
......
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):
......
;;; 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)))
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment