@comment -*-texinfo-*-
@c This is part of the GNU Emacs Lisp Reference Manual.
-@c Copyright (C) 1992, 1993, 1994, 1998, 1999, 2001, 2002, 2003, 2004,
-@c 2005, 2006, 2007, 2008 Free Software Foundation, Inc.
+@c Copyright (C) 1992-1994, 1998-1999, 2001-2015 Free Software
+@c Foundation, Inc.
@c See the file elisp.texi for copying conditions.
@c This file can also be used by an independent Edebug User
@c , Bugs and Todo List, Top, Top
-@node Edebug, Syntax Errors, Debugger, Debugging
+@node Edebug
@section Edebug
@cindex Edebug debugging facility
- Edebug is a source-level debugger for Emacs Lisp programs with which
+ Edebug is a source-level debugger for Emacs Lisp programs, with which
you can:
@itemize @bullet
display their results each time Edebug updates the display.
@item
-Output trace info on function enter and exit.
+Output trace information on function calls and returns.
@item
Stop when an error occurs.
@end itemize
The first three sections below should tell you enough about Edebug to
-enable you to use it.
+start using it.
@menu
-* Using Edebug:: Introduction to use of Edebug.
-* Instrumenting:: You must instrument your code
- in order to debug it with Edebug.
+* Using Edebug:: Introduction to use of Edebug.
+* Instrumenting:: You must instrument your code
+ in order to debug it with Edebug.
* Modes: Edebug Execution Modes. Execution modes, stopping more or less often.
-* Jumping:: Commands to jump to a specified place.
-* Misc: Edebug Misc. Miscellaneous commands.
+* Jumping:: Commands to jump to a specified place.
+* Misc: Edebug Misc. Miscellaneous commands.
* Breaks:: Setting breakpoints to make the program stop.
-* Trapping Errors:: Trapping errors with Edebug.
-* Views: Edebug Views. Views inside and outside of Edebug.
-* Eval: Edebug Eval. Evaluating expressions within Edebug.
-* Eval List:: Expressions whose values are displayed
- each time you enter Edebug.
-* Printing in Edebug:: Customization of printing.
-* Trace Buffer:: How to produce trace output in a buffer.
-* Coverage Testing:: How to test evaluation coverage.
-* The Outside Context:: Data that Edebug saves and restores.
-* Edebug and Macros:: Specifying how to handle macro calls.
-* Options: Edebug Options. Option variables for customizing Edebug.
+* Trapping Errors:: Trapping errors with Edebug.
+* Views: Edebug Views. Views inside and outside of Edebug.
+* Eval: Edebug Eval. Evaluating expressions within Edebug.
+* Eval List:: Expressions whose values are displayed
+ each time you enter Edebug.
+* Printing in Edebug:: Customization of printing.
+* Trace Buffer:: How to produce trace output in a buffer.
+* Coverage Testing:: How to test evaluation coverage.
+* The Outside Context:: Data that Edebug saves and restores.
+* Edebug and Macros:: Specifying how to handle macro calls.
+* Options: Edebug Options. Option variables for customizing Edebug.
@end menu
@node Using Edebug
@node Instrumenting
@subsection Instrumenting for Edebug
+@cindex instrumenting for Edebug
In order to use Edebug to debug Lisp code, you must first
@dfn{instrument} the code. Instrumenting code inserts additional code
edebug-all-forms} toggles this option.
@findex edebug-eval-top-level-form
+@findex edebug-defun
Another command, @kbd{M-x edebug-eval-top-level-form}, is available to
instrument any top-level form regardless of the values of
@code{edebug-all-defs} and @code{edebug-all-forms}.
+@code{edebug-defun} is an alias for @code{edebug-eval-top-level-form}.
While Edebug is active, the command @kbd{I}
(@code{edebug-instrument-callee}) instruments the definition of the
-function or macro called by the list form after point, if is not already
+function or macro called by the list form after point, if it is not already
instrumented. This is possible only if Edebug knows where to find the
-source for that function; for this reading, after loading Edebug,
+source for that function; for this reason, after loading Edebug,
@code{eval-region} records the position of every definition it
evaluates, even if not instrumenting it. See also the @kbd{i} command
(@pxref{Jumping}), which steps into the call after instrumenting the
expressions, and other defining forms. However, Edebug cannot determine
on its own what a user-defined macro will do with the arguments of a
macro call, so you must provide that information using Edebug
-specifications; see @ref{Edebug and Macros}, for details.
+specifications; for details, @pxref{Edebug and Macros}.
When Edebug is about to instrument code for the first time in a
session, it runs the hook @code{edebug-setup-hook}, then sets it to
If Edebug detects a syntax error while instrumenting, it leaves point
at the erroneous code and signals an @code{invalid-read-syntax} error.
+@c FIXME? I can't see that it "leaves point at the erroneous code".
@xref{Edebug Eval}, for other evaluation functions available
inside of Edebug.
@item S
Stop: don't execute any more of the program, but wait for more
Edebug commands (@code{edebug-stop}).
+@c FIXME Does not work. http://debbugs.gnu.org/9764
@item @key{SPC}
Step: stop at the next stop point encountered (@code{edebug-step-mode}).
of the keyboard macro. This is not easy to fix. Also, defining or
executing a keyboard macro outside of Edebug does not affect commands
inside Edebug. This is usually an advantage. See also the
-@code{edebug-continue-kbd-macro} option (@pxref{Edebug Options}).
+@code{edebug-continue-kbd-macro} option in @ref{Edebug Options}.
When you enter a new Edebug level, the initial execution mode comes
-from the value of the variable @code{edebug-initial-mode}.
-(@xref{Edebug Options}.) By default, this specifies step mode. Note
+from the value of the variable @code{edebug-initial-mode}
+(@pxref{Edebug Options}). By default, this specifies step mode. Note
that you may reenter the same Edebug level several times if, for
example, an instrumented function is called several times from one
command.
@defopt edebug-sit-for-seconds
This option specifies how many seconds to wait between execution steps
-in trace mode. The default is 1 second.
+in trace mode or continue mode. The default is 1 second.
@end defopt
@node Jumping
(@code{edebug-forward-sexp}).
@item o
-Run the program until the end of the containing sexp.
+Run the program until the end of the containing sexp (@code{edebug-step-out}).
@item i
-Step into the function or macro called by the form after point.
+Step into the function or macro called by the form after point
+(@code{edebug-step-in}).
@end table
The @kbd{h} command proceeds to the stop point at or after the current
The @kbd{f} command runs the program forward over one expression. More
precisely, it sets a temporary breakpoint at the position that
-@kbd{C-M-f} would reach, then executes in go mode so that the program
-will stop at breakpoints.
+@code{forward-sexp} would reach, then executes in go mode so that
+the program will stop at breakpoints.
With a prefix argument @var{n}, the temporary breakpoint is placed
@var{n} sexps beyond point. If the containing list ends before @var{n}
more elements, then the place to stop is after the containing
expression.
-You must check that the position @kbd{C-M-f} finds is a place that the
-program will really get to. In @code{cond}, for example, this may not
-be true.
+You must check that the position @code{forward-sexp} finds is a place
+that the program will really get to. In @code{cond}, for example,
+this may not be true.
For flexibility, the @kbd{f} command does @code{forward-sexp} starting
at point, rather than at the stop point. If you want to execute one
-expression @emph{from the current stop point}, first type @kbd{w}, to
-move point there, and then type @kbd{f}.
+expression @emph{from the current stop point}, first type @kbd{w}
+(@code{edebug-where}) to move point there, and then type @kbd{f}.
The @kbd{o} command continues ``out of'' an expression. It places a
temporary breakpoint at the end of the sexp containing point. If the
@item Q
Like @kbd{q}, but don't stop even for protected code
-(@code{top-level-nonstop}).
+(@code{edebug-top-level-nonstop}).
@item r
Redisplay the most recently known expression result in the echo area
@menu
* Breakpoints:: Breakpoints at stop points.
-* Global Break Condition:: Breaking on an event.
-* Source Breakpoints:: Embedding breakpoints in source code.
+* Global Break Condition:: Breaking on an event.
+* Source Breakpoints:: Embedding breakpoints in source code.
@end menu
@node Breakpoints
saved outside window configuration---so that even if you turn saving
back @emph{on}, the current window configuration remains unchanged when
you next exit Edebug (by continuing the program). However, the
-automatic redisplay of @samp{*edebug*} and @samp{*edebug-trace*} may
+automatic redisplay of @file{*edebug*} and @file{*edebug-trace*} may
conflict with the buffers you wish to see unless you have enough windows
open.
@node Edebug Eval
@subsection Evaluation
- While within Edebug, you can evaluate expressions ``as if'' Edebug
+ While within Edebug, you can evaluate expressions as if Edebug
were not running. Edebug tries to be invisible to the expression's
evaluation and printing. Evaluation of expressions that cause side
effects will work as expected, except for changes to data that Edebug
interference with the evaluation.
@item M-: @var{exp} @key{RET}
-Evaluate expression @var{exp} in the context of Edebug itself.
+Evaluate expression @var{exp} in the context of Edebug itself
+(@code{eval-expression}).
@item C-x C-e
Evaluate the expression before point, in the context outside of Edebug
@cindex lexical binding (Edebug)
Edebug supports evaluation of expressions containing references to
lexically bound symbols created by the following constructs in
-@file{cl.el} (version 2.03 or later): @code{lexical-let},
-@code{macrolet}, and @code{symbol-macrolet}.
+@file{cl.el}: @code{lexical-let}, @code{macrolet}, and
+@code{symbol-macrolet}.
+@c FIXME? What about lexical-binding = t?
@node Eval List
@subsection Evaluation List Buffer
- You can use the @dfn{evaluation list buffer}, called @samp{*edebug*}, to
+ You can use the @dfn{evaluation list buffer}, called @file{*edebug*}, to
evaluate expressions interactively. You can also set up the
@dfn{evaluation list} of expressions to be evaluated automatically each
time Edebug updates the display.
@table @kbd
@item E
-Switch to the evaluation list buffer @samp{*edebug*}
+Switch to the evaluation list buffer @file{*edebug*}
(@code{edebug-visit-eval-list}).
@end table
- In the @samp{*edebug*} buffer you can use the commands of Lisp
+ In the @file{*edebug*} buffer you can use the commands of Lisp
Interaction mode (@pxref{Lisp Interaction,,, emacs, The GNU Emacs
Manual}) as well as these special commands:
@end table
You can evaluate expressions in the evaluation list window with
-@kbd{C-j} or @kbd{C-x C-e}, just as you would in @samp{*scratch*};
+@kbd{C-j} or @kbd{C-x C-e}, just as you would in @file{*scratch*};
but they are evaluated in the context outside of Edebug.
The expressions you enter interactively (and their results) are lost
Thus, if you type @kbd{C-c C-u} again without changing the buffer text,
the evaluation list is effectively unchanged.
- If an error occurs during an evaluation from the evaluation list, the
-error message is displayed in a string as if it were the result.
-Therefore, expressions that use variables not currently valid do not
-interrupt your debugging.
+ If an error occurs during an evaluation from the evaluation list,
+the error message is displayed in a string as if it were the result.
+Therefore, expressions using variables that are not currently valid do
+not interrupt your debugging.
Here is an example of what the evaluation list window looks like after
several expressions have been added to it:
@kbd{C-c C-u}. You need not insert dashes in the comment line---its
contents don't matter.
-After selecting @samp{*edebug*}, you can return to the source code
-buffer with @kbd{C-c C-w}. The @samp{*edebug*} buffer is killed when
+After selecting @file{*edebug*}, you can return to the source code
+buffer with @kbd{C-c C-w}. The @file{*edebug*} buffer is killed when
you continue execution, and recreated next time it is needed.
@node Printing in Edebug
One way to cope with circular structure is to set @code{print-length}
or @code{print-level} to truncate the printing. Edebug does this for
-you; it binds @code{print-length} and @code{print-level} to 50 if they
-were @code{nil}. (Actually, the variables @code{edebug-print-length}
-and @code{edebug-print-level} specify the values to use within Edebug.)
-@xref{Output Variables}.
+you; it binds @code{print-length} and @code{print-level} to the values
+of the variables @code{edebug-print-length} and
+@code{edebug-print-level} (so long as they have non-@code{nil}
+values). @xref{Output Variables}.
@defopt edebug-print-length
If non-@code{nil}, Edebug binds @code{print-length} to this value while
@cindex trace buffer
Edebug can record an execution trace, storing it in a buffer named
-@samp{*edebug-trace*}. This is a log of function calls and returns,
+@file{*edebug-trace*}. This is a log of function calls and returns,
showing the function names and their arguments and values. To enable
trace recording, set @code{edebug-trace} to a non-@code{nil} value.
Coverage testing makes execution slower, so it is only done if
@code{edebug-test-coverage} is non-@code{nil}. Frequency counting is
-performed for all execution of an instrumented function, even if the
+performed for all executions of an instrumented function, even if the
execution mode is Go-nonstop, and regardless of whether coverage testing
is enabled.
This command displays the frequency count data for each line of the
current definition.
-The frequency counts appear as comment lines after each line of code,
-and you can undo all insertions with one @code{undo} command. The
-counts appear under the @samp{(} before an expression or the @samp{)}
-after an expression, or on the last character of a variable. To
-simplify the display, a count is not shown if it is equal to the
-count of an earlier expression on the same line.
+It inserts frequency counts as comment lines after each line of code.
+You can undo all insertions with one @code{undo} command. The counts
+appear under the @samp{(} before an expression or the @samp{)} after
+an expression, or on the last character of a variable. To simplify
+the display, a count is not shown if it is equal to the count of an
+earlier expression on the same line.
The character @samp{=} following the count for an expression says that
the expression has returned the same value each time it was evaluated.
be completely transparent.
@menu
-* Checking Whether to Stop:: When Edebug decides what to do.
-* Edebug Display Update:: When Edebug updates the display.
-* Edebug Recursive Edit:: When Edebug stops execution.
+* Checking Whether to Stop:: When Edebug decides what to do.
+* Edebug Display Update:: When Edebug updates the display.
+* Edebug Recursive Edit:: When Edebug stops execution.
@end menu
@node Checking Whether to Stop
@itemize @bullet
@item
@code{max-lisp-eval-depth} and @code{max-specpdl-size} are both
-incremented once to reduce Edebug's impact on the stack. You could,
-however, still run out of stack space when using Edebug.
+increased to reduce Edebug's impact on the stack. You could, however,
+still run out of stack space when using Edebug.
@item
The state of keyboard macro execution is saved and restored. While
@c needs an xref to be on just one line.
When Edebug needs to display something (e.g., in trace mode), it saves
the current window configuration from ``outside'' Edebug
-(@pxref{Window Configurations}). When you exit Edebug (by continuing
-the program), it restores the previous window configuration.
+(@pxref{Window Configurations}). When you exit Edebug, it restores
+the previous window configuration.
Emacs redisplays only when it pauses. Usually, when you continue
execution, the program re-enters Edebug at a breakpoint or after
@item
The variables @code{overlay-arrow-position} and
-@code{overlay-arrow-string} are saved and restored. So you can safely
+@code{overlay-arrow-string} are saved and restored, so you can safely
invoke Edebug from the recursive edit elsewhere in the same buffer.
@item
@item
The variables @code{last-command}, @code{this-command},
-@code{last-command-char}, @code{last-input-char},
-@code{last-input-event}, @code{last-command-event},
+@code{last-command-event}, @code{last-input-event},
@code{last-event-frame}, @code{last-nonmenu-event}, and
-@code{track-mouse}. Commands used within Edebug do not affect these
-variables outside of Edebug.
+@code{track-mouse}. Commands in Edebug do not affect these variables
+outside of Edebug.
Executing commands within Edebug can change the key sequence that
would be returned by @code{this-command-keys}, and there is no way to
@menu
* Instrumenting Macro Calls:: The basic problem.
-* Specification List:: How to specify complex patterns of evaluation.
-* Backtracking:: What Edebug does when matching fails.
-* Specification Examples:: To help understand specifications.
+* Specification List:: How to specify complex patterns of evaluation.
+* Backtracking:: What Edebug does when matching fails.
+* Specification Examples:: To help understand specifications.
@end menu
@node Instrumenting Macro Calls
@end smallexample
The Edebug specification says which parts of a call to the macro are
-forms to be evaluated. For simple macros, the @var{specification}
+forms to be evaluated. For simple macros, the specification
often looks very similar to the formal argument list of the macro
definition, but specifications are much more general than macro
arguments. @xref{Defining Macros}, for more explanation of
the @code{declare} form.
+@c See, e.g., 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
definitions in Lisp, but @code{def-edebug-spec} makes it possible to
define Edebug specifications for special forms implemented in C.
-@deffn Macro def-edebug-spec macro specification
+@defmac def-edebug-spec macro specification
Specify which expressions of a call to macro @var{macro} are forms to be
evaluated. @var{specification} should be the edebug specification.
Neither argument is evaluated.
The @var{macro} argument can actually be any symbol, not just a macro
name.
-@end deffn
+@end defmac
Here is a table of the possibilities for @var{specification} and how each
directs processing of arguments.
None of the arguments is instrumented.
@item a symbol
-The symbol must have an Edebug specification which is used instead.
+The symbol must have an Edebug specification, which is used instead.
This indirection is repeated until another kind of specification is
found. This allows you to inherit the specification from another macro.
described in the following sections.
@end table
-@vindex edebug-eval-macro-args
If a macro has no Edebug specification, neither through a @code{debug}
declaration nor through a @code{def-edebug-spec} call, the variable
-@code{edebug-eval-macro-args} comes into play. If it is @code{nil},
-the default, none of the arguments is instrumented for evaluation.
-If it is non-@code{nil}, all arguments are instrumented.
+@code{edebug-eval-macro-args} comes into play.
+
+@defopt edebug-eval-macro-args
+This controls the way Edebug treats macro arguments with no explicit
+Edebug specification. If it is @code{nil} (the default), none of the
+arguments is instrumented for evaluation. Otherwise, all arguments
+are instrumented.
+@end defopt
@node Specification List
@subsubsection Specification List
@dfn{specification keywords}, are symbols beginning with @samp{&} (such
as @code{&optional}).
-A specification list may contain sublists which match arguments that are
+A specification list may contain sublists, which match arguments that are
themselves lists, or it may contain vectors used for grouping. Sublists
and groups thus subdivide the specification list into a hierarchy of
levels. Specification keywords apply only to the remainder of the
sublist or group they are contained in.
When a specification list involves alternatives or repetition, matching
-it against an actual macro call may require backtracking.
-@xref{Backtracking}, for more details.
+it against an actual macro call may require backtracking. For more
+details, @pxref{Backtracking}.
Edebug specifications provide the power of regular expression matching,
plus some context-free grammar constructs: the matching of sublists with
A single evaluated expression, which is instrumented.
@item place
-@findex edebug-unwrap
-A place to store a value, as in the Common Lisp @code{setf} construct.
+A generalized variable. @xref{Generalized Variables}.
@item body
Short for @code{&rest form}. See @code{&rest} below.
All following elements in the specification list are optional; as soon
as one does not match, Edebug stops matching at this level.
-To make just a few elements optional followed by non-optional elements,
+To make just a few elements optional, followed by non-optional elements,
use @code{[&optional @var{specs}@dots{}]}. To specify that several
elements must all match or none, use @code{&optional
[@var{specs}@dots{}]}. See the @code{defun} example.
of them match, nothing is matched, but the @code{¬} specification
succeeds.
+@c FIXME &key?
+
@item &define
@c @kindex &define @r{(Edebug)}
Indicates that the specification is for a defining form. The defining
specification} should be either a list specification that is used in
place of the symbol, or a function that is called to process the
arguments. The specification may be defined with @code{def-edebug-spec}
-just as for macros. See the @code{defun} example.
+just as for macros. See the @code{defun} example.
Otherwise, the symbol should be a predicate. The predicate is called
-with the argument and the specification fails if the predicate returns
-@code{nil}. In either case, that argument is not instrumented.
+with the argument, and if the predicate returns @code{nil}, the
+specification fails and the argument is not instrumented.
Some suitable predicates include @code{symbolp}, @code{integerp},
@code{stringp}, @code{vectorp}, and @code{atom}.
@item def-form
The argument is a single, highest-level form in a definition. This is
-like @code{def-body}, except use this to match a single form rather than
+like @code{def-body}, except it is used to match a single form rather than
a list of forms. As a special case, @code{def-form} also means that
tracing information is not output when the form is executed. See the
@code{interactive} example.
in the specification must match some argument.
When a syntax error is detected, it might not be reported until much
-later after higher-level alternatives have been exhausted, and with the
+later, after higher-level alternatives have been exhausted, and with the
point positioned further from the real error. But if backtracking is
disabled when an error occurs, it can be reported immediately. Note
that backtracking is also reenabled automatically in several situations;
-it is reenabled when a new alternative is established by
-@code{&optional}, @code{&rest}, or @code{&or}, or at the start of
-processing a sublist, group, or indirect specification. The effect of
-enabling or disabling backtracking is limited to the remainder of the
-level currently being processed and lower levels.
+when a new alternative is established by @code{&optional},
+@code{&rest}, or @code{&or}, or at the start of processing a sublist,
+group, or indirect specification. The effect of enabling or disabling
+backtracking is limited to the remainder of the level currently being
+processed and lower levels.
Backtracking is disabled while matching any of the
form specifications (that is, @code{form}, @code{body}, @code{def-form}, and
optional expression. In the specification below, notice the @code{gate}
inside of the sublist to prevent backtracking once a sublist is found.
+@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
body))
@end example
-Edebug uses the following specifications for @code{defun} and
-@code{defmacro} and the associated argument list and @code{interactive}
-specifications. It is necessary to handle interactive forms specially
-since an expression argument is actually evaluated outside of the
-function body.
+Edebug uses the following specifications for @code{defun} and the
+associated argument list and @code{interactive} specifications. It is
+necessary to handle interactive forms specially since an expression
+argument is actually evaluated outside of the function body. (The
+specification for @code{defmacro} is very similar to that for
+@code{defun}, but allows for the @code{declare} statement.)
@smallexample
-(def-edebug-spec defmacro defun) ; @r{Indirect ref to @code{defun} spec.}
(def-edebug-spec defun
(&define name lambda-list
[&optional stringp] ; @r{Match the doc string, if present.}
The specification for backquote below illustrates how to match
dotted lists and use @code{nil} to terminate recursion. It also
illustrates how components of a vector may be matched. (The actual
-specification defined by Edebug does not support dotted lists because
-doing so causes very deep recursion that could fail.)
+specification defined by Edebug is a little different, and does not
+support dotted lists because doing so causes very deep recursion that
+could fail.)
@smallexample
-(def-edebug-spec ` (backquote-form)) ; @r{Alias just for clarity.}
+(def-edebug-spec \` (backquote-form)) ; @r{Alias just for clarity.}
(def-edebug-spec backquote-form
(&or ([&or "," ",@@"] &or ("quote" backquote-form) form)
@subsection Edebug Options
These options affect the behavior of Edebug:
+@c Previously defopt'd:
+@c edebug-sit-for-seconds, edebug-print-length, edebug-print-level
+@c edebug-print-circle, edebug-eval-macro-args
@defopt edebug-setup-hook
Functions to call before Edebug is used. Each time it is set to a new
value, Edebug will call those functions once and then
-@code{edebug-setup-hook} is reset to @code{nil}. You could use this to
-load up Edebug specifications associated with a package you are using
+reset @code{edebug-setup-hook} to @code{nil}. You could use this to
+load up Edebug specifications associated with a package you are using,
but only when you also use Edebug.
@xref{Instrumenting}.
@end defopt
displayed buffers.
Saving and restoring point in other buffers is necessary if you are
-debugging code that changes the point of a buffer which is displayed in
+debugging code that changes the point of a buffer that is displayed in
a non-selected window. If Edebug or the user then selects the window,
point in that buffer will move to the window's value of point.
@defopt edebug-trace
If this is non-@code{nil}, trace each function entry and exit.
-Tracing output is displayed in a buffer named @samp{*edebug-trace*}, one
+Tracing output is displayed in a buffer named @file{*edebug-trace*}, one
function entry or exit per line, indented by the recursion level.
Also see @code{edebug-tracing}, in @ref{Trace Buffer}.
@xref{Edebug Execution Modes}.
@end defopt
+@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
@code{debug-on-error} was previously @code{nil}. @xref{Trapping
the result is non-@code{nil}, then break. Errors are ignored.
@xref{Global Break Condition}.
@end defopt
-
-@ignore
- arch-tag: 74842db8-019f-4818-b5a4-b2de878e57fd
-@end ignore