[Top][All Lists]
[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[Emacs-diffs] Changes to edebug.texi
|
From: |
Glenn Morris |
|
Subject: |
[Emacs-diffs] Changes to edebug.texi |
|
Date: |
Thu, 06 Sep 2007 04:19:25 +0000 |
CVSROOT: /sources/emacs
Module name: emacs
Changes by: Glenn Morris <gm> 07/09/06 04:19:24
Index: edebug.texi
===================================================================
RCS file: edebug.texi
diff -N edebug.texi
--- /dev/null 1 Jan 1970 00:00:00 -0000
+++ edebug.texi 6 Sep 2007 04:19:24 -0000 1.1
@@ -0,0 +1,1582 @@
address@hidden -*-texinfo-*-
address@hidden This is part of the GNU Emacs Lisp Reference Manual.
address@hidden Copyright (C) 1992, 1993, 1994, 1998, 1999, 2001, 2002, 2003,
2004,
address@hidden 2005, 2006, 2007 Free Software Foundation, Inc.
address@hidden See the file elisp.texi for copying conditions.
+
address@hidden This file can also be used by an independent Edebug User
address@hidden Manual in which case the Edebug node below should be used
address@hidden with the following links to the Bugs section and to the top
level:
+
address@hidden , Bugs and Todo List, Top, Top
+
address@hidden Edebug, Syntax Errors, Debugger, Debugging
address@hidden Edebug
address@hidden Edebug debugging facility
+
+ Edebug is a source-level debugger for Emacs Lisp programs with which
+you can:
+
address@hidden @bullet
address@hidden
+Step through evaluation, stopping before and after each expression.
+
address@hidden
+Set conditional or unconditional breakpoints.
+
address@hidden
+Stop when a specified condition is true (the global break event).
+
address@hidden
+Trace slow or fast, stopping briefly at each stop point, or
+at each breakpoint.
+
address@hidden
+Display expression results and evaluate expressions as if outside of
+Edebug.
+
address@hidden
+Automatically re-evaluate a list of expressions and
+display their results each time Edebug updates the display.
+
address@hidden
+Output trace info on function enter and exit.
+
address@hidden
+Stop when an error occurs.
+
address@hidden
+Display a backtrace, omitting Edebug's own frames.
+
address@hidden
+Specify argument evaluation for macros and defining forms.
+
address@hidden
+Obtain rudimentary coverage testing and frequency counts.
address@hidden itemize
+
+The first three sections below should tell you enough about Edebug to
+enable you to use it.
+
address@hidden
+* 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.
+* 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.
address@hidden menu
+
address@hidden Using Edebug
address@hidden Using Edebug
+
+ To debug a Lisp program with Edebug, you must first @dfn{instrument}
+the Lisp code that you want to debug. A simple way to do this is to
+first move point into the definition of a function or macro and then do
address@hidden C-M-x} (@code{eval-defun} with a prefix argument). See
address@hidden, for alternative ways to instrument code.
+
+ Once a function is instrumented, any call to the function activates
+Edebug. Depending on which Edebug execution mode you have selected,
+activating Edebug may stop execution and let you step through the
+function, or it may update the display and continue execution while
+checking for debugging commands. The default execution mode is step,
+which stops execution. @xref{Edebug Execution Modes}.
+
+ Within Edebug, you normally view an Emacs buffer showing the source of
+the Lisp code you are debugging. This is referred to as the @dfn{source
+code buffer}, and it is temporarily read-only.
+
+ An arrow in the left fringe indicates the line where the function is
+executing. Point initially shows where within the line the function is
+executing, but this ceases to be true if you move point yourself.
+
+ If you instrument the definition of @code{fac} (shown below) and then
+execute @code{(fac 3)}, here is what you would normally see. Point is
+at the open-parenthesis before @code{if}.
+
address@hidden
+(defun fac (n)
+=>@point{}(if (< 0 n)
+ (* n (fac (1- n)))
+ 1))
address@hidden example
+
address@hidden stop points
+The places within a function where Edebug can stop execution are called
address@hidden points}. These occur both before and after each subexpression
+that is a list, and also after each variable reference.
+Here we use periods to show the stop points in the function
address@hidden:
+
address@hidden
+(defun fac (n)
+ .(if .(< 0 n.).
+ .(* n. .(fac .(1- n.).).).
+ 1).)
address@hidden example
+
+The special commands of Edebug are available in the source code buffer
+in addition to the commands of Emacs Lisp mode. For example, you can
+type the Edebug command @key{SPC} to execute until the next stop point.
+If you type @key{SPC} once after entry to @code{fac}, here is the
+display you will see:
+
address@hidden
+(defun fac (n)
+=>(if @point{}(< 0 n)
+ (* n (fac (1- n)))
+ 1))
address@hidden example
+
+When Edebug stops execution after an expression, it displays the
+expression's value in the echo area.
+
+Other frequently used commands are @kbd{b} to set a breakpoint at a stop
+point, @kbd{g} to execute until a breakpoint is reached, and @kbd{q} to
+exit Edebug and return to the top-level command loop. Type @kbd{?} to
+display a list of all Edebug commands.
+
address@hidden Instrumenting
address@hidden Instrumenting for Edebug
+
+ In order to use Edebug to debug Lisp code, you must first
address@hidden the code. Instrumenting code inserts additional code
+into it, to invoke Edebug at the proper places.
+
address@hidden C-M-x
address@hidden eval-defun (Edebug)
+ When you invoke command @kbd{C-M-x} (@code{eval-defun}) with a
+prefix argument on a function definition, it instruments the
+definition before evaluating it. (This does not modify the source
+code itself.) If the variable @code{edebug-all-defs} is
address@hidden, that inverts the meaning of the prefix argument: in
+this case, @kbd{C-M-x} instruments the definition @emph{unless} it has
+a prefix argument. The default value of @code{edebug-all-defs} is
address@hidden The command @kbd{M-x edebug-all-defs} toggles the value
+of the variable @code{edebug-all-defs}.
+
address@hidden eval-region @r{(Edebug)}
address@hidden eval-buffer @r{(Edebug)}
address@hidden eval-current-buffer @r{(Edebug)}
+ If @code{edebug-all-defs} is address@hidden, then the commands
address@hidden, @code{eval-current-buffer}, and @code{eval-buffer}
+also instrument any definitions they evaluate. Similarly,
address@hidden controls whether @code{eval-region} should
+instrument @emph{any} form, even non-defining forms. This doesn't apply
+to loading or evaluations in the minibuffer. The command @kbd{M-x
+edebug-all-forms} toggles this option.
+
address@hidden edebug-eval-top-level-form
+ Another command, @kbd{M-x edebug-eval-top-level-form}, is available to
+instrument any top-level form regardless of the values of
address@hidden and @code{edebug-all-forms}.
+
+ 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
+instrumented. This is possible only if Edebug knows where to find the
+source for that function; for this reading, after loading Edebug,
address@hidden 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
+function.
+
+ Edebug knows how to instrument all the standard special forms,
address@hidden forms with an expression argument, anonymous lambda
+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.
+
+ 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
address@hidden You can use this to load Edebug specifications
+associated with a package you are using, but only when you use Edebug.
+
address@hidden eval-expression @r{(Edebug)}
+ To remove instrumentation from a definition, simply re-evaluate its
+definition in a way that does not instrument. There are two ways of
+evaluating forms that never instrument them: from a file with
address@hidden, and from the minibuffer with @code{eval-expression}
+(@kbd{M-:}).
+
+ If Edebug detects a syntax error while instrumenting, it leaves point
+at the erroneous code and signals an @code{invalid-read-syntax} error.
+
+ @xref{Edebug Eval}, for other evaluation functions available
+inside of Edebug.
+
address@hidden Edebug Execution Modes
address@hidden Edebug Execution Modes
+
address@hidden Edebug execution modes
+Edebug supports several execution modes for running the program you are
+debugging. We call these alternatives @dfn{Edebug execution modes}; do
+not confuse them with major or minor modes. The current Edebug execution mode
+determines how far Edebug continues execution before stopping---whether
+it stops at each stop point, or continues to the next breakpoint, for
+example---and how much Edebug displays the progress of the evaluation
+before it stops.
+
+Normally, you specify the Edebug execution mode by typing a command to
+continue the program in a certain mode. Here is a table of these
+commands; all except for @kbd{S} resume execution of the program, at
+least for a certain distance.
+
address@hidden @kbd
address@hidden S
+Stop: don't execute any more of the program, but wait for more
+Edebug commands (@code{edebug-stop}).
+
address@hidden @key{SPC}
+Step: stop at the next stop point encountered (@code{edebug-step-mode}).
+
address@hidden n
+Next: stop at the next stop point encountered after an expression
+(@code{edebug-next-mode}). Also see @code{edebug-forward-sexp} in
address@hidden
+
address@hidden t
+Trace: pause (normally one second) at each Edebug stop point
+(@code{edebug-trace-mode}).
+
address@hidden T
+Rapid trace: update the display at each stop point, but don't actually
+pause (@code{edebug-Trace-fast-mode}).
+
address@hidden g
+Go: run until the next breakpoint (@code{edebug-go-mode}). @xref{Breakpoints}.
+
address@hidden c
+Continue: pause one second at each breakpoint, and then continue
+(@code{edebug-continue-mode}).
+
address@hidden C
+Rapid continue: move point to each breakpoint, but don't pause
+(@code{edebug-Continue-fast-mode}).
+
address@hidden G
+Go non-stop: ignore breakpoints (@code{edebug-Go-nonstop-mode}). You
+can still stop the program by typing @kbd{S}, or any editing command.
address@hidden table
+
+In general, the execution modes earlier in the above list run the
+program more slowly or stop sooner than the modes later in the list.
+
+While executing or tracing, you can interrupt the execution by typing
+any Edebug command. Edebug stops the program at the next stop point and
+then executes the command you typed. For example, typing @kbd{t} during
+execution switches to trace mode at the next stop point. You can use
address@hidden to stop execution without doing anything else.
+
+If your function happens to read input, a character you type intending
+to interrupt execution may be read by the function instead. You can
+avoid such unintended results by paying attention to when your program
+wants input.
+
address@hidden keyboard macros (Edebug)
+Keyboard macros containing the commands in this section do not
+completely work: exiting from Edebug, to resume the program, loses track
+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
address@hidden option (@pxref{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
+that you may reenter the same Edebug level several times if, for
+example, an instrumented function is called several times from one
+command.
+
address@hidden edebug-sit-for-seconds
+This option specifies how many seconds to wait between execution steps
+in trace mode. The default is 1 second.
address@hidden defopt
+
address@hidden Jumping
address@hidden Jumping
+
+ The commands described in this section execute until they reach a
+specified location. All except @kbd{i} make a temporary breakpoint to
+establish the place to stop, then switch to go mode. Any other
+breakpoint reached before the intended stop point will also stop
+execution. @xref{Breakpoints}, for the details on breakpoints.
+
+ These commands may fail to work as expected in case of nonlocal exit,
+as that can bypass the temporary breakpoint where you expected the
+program to stop.
+
address@hidden @kbd
address@hidden h
+Proceed to the stop point near where point is (@code{edebug-goto-here}).
+
address@hidden f
+Run the program for one expression
+(@code{edebug-forward-sexp}).
+
address@hidden o
+Run the program until the end of the containing sexp.
+
address@hidden i
+Step into the function or macro called by the form after point.
address@hidden table
+
+The @kbd{h} command proceeds to the stop point at or after the current
+location of point, using a temporary breakpoint.
+
+The @kbd{f} command runs the program forward over one expression. More
+precisely, it sets a temporary breakpoint at the position that
address@hidden 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
address@hidden 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.
+
+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}.
+
+The @kbd{o} command continues ``out of'' an expression. It places a
+temporary breakpoint at the end of the sexp containing point. If the
+containing sexp is a function definition itself, @kbd{o} continues until
+just before the last sexp in the definition. If that is where you are
+now, it returns from the function and then stops. In other words, this
+command does not exit the currently executing function unless you are
+positioned after the last sexp.
+
+The @kbd{i} command steps into the function or macro called by the list
+form after point, and stops at its first stop point. Note that the form
+need not be the one about to be evaluated. But if the form is a
+function call about to be evaluated, remember to use this command before
+any of the arguments are evaluated, since otherwise it will be too late.
+
+The @kbd{i} command instruments the function or macro it's supposed to
+step into, if it isn't instrumented already. This is convenient, but keep
+in mind that the function or macro remains instrumented unless you explicitly
+arrange to deinstrument it.
+
address@hidden Edebug Misc
address@hidden Miscellaneous Edebug Commands
+
+ Some miscellaneous Edebug commands are described here.
+
address@hidden @kbd
address@hidden ?
+Display the help message for Edebug (@code{edebug-help}).
+
address@hidden C-]
+Abort one level back to the previous command level
+(@code{abort-recursive-edit}).
+
address@hidden q
+Return to the top level editor command loop (@code{top-level}). This
+exits all recursive editing levels, including all levels of Edebug
+activity. However, instrumented code protected with
address@hidden or @code{condition-case} forms may resume
+debugging.
+
address@hidden Q
+Like @kbd{q}, but don't stop even for protected code
+(@code{top-level-nonstop}).
+
address@hidden r
+Redisplay the most recently known expression result in the echo area
+(@code{edebug-previous-result}).
+
address@hidden d
+Display a backtrace, excluding Edebug's own functions for clarity
+(@code{edebug-backtrace}).
+
+You cannot use debugger commands in the backtrace buffer in Edebug as
+you would in the standard debugger.
+
+The backtrace buffer is killed automatically when you continue
+execution.
address@hidden table
+
+You can invoke commands from Edebug that activate Edebug again
+recursively. Whenever Edebug is active, you can quit to the top level
+with @kbd{q} or abort one recursive edit level with @kbd{C-]}. You can
+display a backtrace of all the pending evaluations with @kbd{d}.
+
address@hidden Breaks
address@hidden Breaks
+
+Edebug's step mode stops execution when the next stop point is reached.
+There are three other ways to stop Edebug execution once it has started:
+breakpoints, the global break condition, and source breakpoints.
+
address@hidden
+* Breakpoints:: Breakpoints at stop points.
+* Global Break Condition:: Breaking on an event.
+* Source Breakpoints:: Embedding breakpoints in source code.
address@hidden menu
+
address@hidden Breakpoints
address@hidden Edebug Breakpoints
+
address@hidden breakpoints (Edebug)
+While using Edebug, you can specify @dfn{breakpoints} in the program you
+are testing: these are places where execution should stop. You can set a
+breakpoint at any stop point, as defined in @ref{Using Edebug}. For
+setting and unsetting breakpoints, the stop point that is affected is
+the first one at or after point in the source code buffer. Here are the
+Edebug commands for breakpoints:
+
address@hidden @kbd
address@hidden b
+Set a breakpoint at the stop point at or after point
+(@code{edebug-set-breakpoint}). If you use a prefix argument, the
+breakpoint is temporary---it turns off the first time it stops the
+program.
+
address@hidden u
+Unset the breakpoint (if any) at the stop point at or after
+point (@code{edebug-unset-breakpoint}).
+
address@hidden x @var{condition} @key{RET}
+Set a conditional breakpoint which stops the program only if
+evaluating @var{condition} produces a address@hidden value
+(@code{edebug-set-conditional-breakpoint}). With a prefix argument,
+the breakpoint is temporary.
+
address@hidden B
+Move point to the next breakpoint in the current definition
+(@code{edebug-next-breakpoint}).
address@hidden table
+
+While in Edebug, you can set a breakpoint with @kbd{b} and unset one
+with @kbd{u}. First move point to the Edebug stop point of your choice,
+then type @kbd{b} or @kbd{u} to set or unset a breakpoint there.
+Unsetting a breakpoint where none has been set has no effect.
+
+Re-evaluating or reinstrumenting a definition removes all of its
+previous breakpoints.
+
+A @dfn{conditional breakpoint} tests a condition each time the program
+gets there. Any errors that occur as a result of evaluating the
+condition are ignored, as if the result were @code{nil}. To set a
+conditional breakpoint, use @kbd{x}, and specify the condition
+expression in the minibuffer. Setting a conditional breakpoint at a
+stop point that has a previously established conditional breakpoint puts
+the previous condition expression in the minibuffer so you can edit it.
+
+You can make a conditional or unconditional breakpoint
address@hidden by using a prefix argument with the command to set the
+breakpoint. When a temporary breakpoint stops the program, it is
+automatically unset.
+
+Edebug always stops or pauses at a breakpoint, except when the Edebug
+mode is Go-nonstop. In that mode, it ignores breakpoints entirely.
+
+To find out where your breakpoints are, use the @kbd{B} command, which
+moves point to the next breakpoint following point, within the same
+function, or to the first breakpoint if there are no following
+breakpoints. This command does not continue execution---it just moves
+point in the buffer.
+
address@hidden Global Break Condition
address@hidden Global Break Condition
+
address@hidden stopping on events
address@hidden global break condition
+ A @dfn{global break condition} stops execution when a specified
+condition is satisfied, no matter where that may occur. Edebug
+evaluates the global break condition at every stop point; if it
+evaluates to a address@hidden value, then execution stops or pauses
+depending on the execution mode, as if a breakpoint had been hit. If
+evaluating the condition gets an error, execution does not stop.
+
address@hidden edebug-set-global-break-condition
+ The condition expression is stored in
address@hidden You can specify a new expression
+using the @kbd{X} command from the source code buffer while Edebug is
+active, or using @kbd{C-x X X} from any buffer at any time, as long as
+Edebug is loaded (@code{edebug-set-global-break-condition}).
+
+ The global break condition is the simplest way to find where in your
+code some event occurs, but it makes code run much more slowly. So you
+should reset the condition to @code{nil} when not using it.
+
address@hidden Source Breakpoints
address@hidden Source Breakpoints
+
address@hidden edebug
address@hidden source breakpoints
+ All breakpoints in a definition are forgotten each time you
+reinstrument it. If you wish to make a breakpoint that won't be
+forgotten, you can write a @dfn{source breakpoint}, which is simply a
+call to the function @code{edebug} in your source code. You can, of
+course, make such a call conditional. For example, in the @code{fac}
+function, you can insert the first line as shown below, to stop when the
+argument reaches zero:
+
address@hidden
+(defun fac (n)
+ (if (= n 0) (edebug))
+ (if (< 0 n)
+ (* n (fac (1- n)))
+ 1))
address@hidden example
+
+ When the @code{fac} definition is instrumented and the function is
+called, the call to @code{edebug} acts as a breakpoint. Depending on
+the execution mode, Edebug stops or pauses there.
+
+ If no instrumented code is being executed when @code{edebug} is called,
+that function calls @code{debug}.
address@hidden This may not be a good idea anymore.
+
address@hidden Trapping Errors
address@hidden Trapping Errors
+
+ Emacs normally displays an error message when an error is signaled and
+not handled with @code{condition-case}. While Edebug is active and
+executing instrumented code, it normally responds to all unhandled
+errors. You can customize this with the options @code{edebug-on-error}
+and @code{edebug-on-quit}; see @ref{Edebug Options}.
+
+ When Edebug responds to an error, it shows the last stop point
+encountered before the error. This may be the location of a call to a
+function which was not instrumented, and within which the error actually
+occurred. For an unbound variable error, the last known stop point
+might be quite distant from the offending variable reference. In that
+case, you might want to display a full backtrace (@pxref{Edebug Misc}).
+
address@hidden Edebug should be changed for the following: -- dan
+ If you change @code{debug-on-error} or @code{debug-on-quit} while
+Edebug is active, these changes will be forgotten when Edebug becomes
+inactive. Furthermore, during Edebug's recursive edit, these variables
+are bound to the values they had outside of Edebug.
+
address@hidden Edebug Views
address@hidden Edebug Views
+
+ These Edebug commands let you view aspects of the buffer and window
+status as they were before entry to Edebug. The outside window
+configuration is the collection of windows and contents that were in
+effect outside of Edebug.
+
address@hidden @kbd
address@hidden v
+Switch to viewing the outside window configuration
+(@code{edebug-view-outside}). Type @kbd{C-x X w} to return to Edebug.
+
address@hidden p
+Temporarily display the outside current buffer with point at its
+outside position (@code{edebug-bounce-point}), pausing for one second
+before returning to Edebug. With a prefix argument @var{n}, pause for
address@hidden seconds instead.
+
address@hidden w
+Move point back to the current stop point in the source code buffer
+(@code{edebug-where}).
+
+If you use this command in a different window displaying the same
+buffer, that window will be used instead to display the current
+definition in the future.
+
address@hidden W
address@hidden Its function is not simply to forget the saved configuration --
dan
+Toggle whether Edebug saves and restores the outside window
+configuration (@code{edebug-toggle-save-windows}).
+
+With a prefix argument, @code{W} only toggles saving and restoring of
+the selected window. To specify a window that is not displaying the
+source code buffer, you must use @kbd{C-x X W} from the global keymap.
address@hidden table
+
+ You can view the outside window configuration with @kbd{v} or just
+bounce to the point in the current buffer with @kbd{p}, even if
+it is not normally displayed.
+
+ After moving point, you may wish to jump back to the stop point.
+You can do that with @kbd{w} from a source code buffer. You can jump
+back to the stop point in the source code buffer from any buffer using
address@hidden X w}.
+
+ Each time you use @kbd{W} to turn saving @emph{off}, Edebug forgets the
+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
+conflict with the buffers you wish to see unless you have enough windows
+open.
+
address@hidden Edebug Eval
address@hidden Evaluation
+
+ 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
+explicitly saves and restores. @xref{The Outside Context}, for details
+on this process.
+
address@hidden @kbd
address@hidden e @var{exp} @key{RET}
+Evaluate expression @var{exp} in the context outside of Edebug
+(@code{edebug-eval-expression}). That is, Edebug tries to minimize its
+interference with the evaluation.
+
address@hidden M-: @var{exp} @key{RET}
+Evaluate expression @var{exp} in the context of Edebug itself.
+
address@hidden C-x C-e
+Evaluate the expression before point, in the context outside of Edebug
+(@code{edebug-eval-last-sexp}).
address@hidden table
+
address@hidden lexical binding (Edebug)
+ Edebug supports evaluation of expressions containing references to
+lexically bound symbols created by the following constructs in
address@hidden (version 2.03 or later): @code{lexical-let},
address@hidden, and @code{symbol-macrolet}.
+
address@hidden Eval List
address@hidden Evaluation List Buffer
+
+ You can use the @dfn{evaluation list buffer}, called @samp{*edebug*}, to
+evaluate expressions interactively. You can also set up the
address@hidden list} of expressions to be evaluated automatically each
+time Edebug updates the display.
+
address@hidden @kbd
address@hidden E
+Switch to the evaluation list buffer @samp{*edebug*}
+(@code{edebug-visit-eval-list}).
address@hidden table
+
+ In the @samp{*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:
+
address@hidden @kbd
address@hidden C-j
+Evaluate the expression before point, in the outside context, and insert
+the value in the buffer (@code{edebug-eval-print-last-sexp}).
+
address@hidden C-x C-e
+Evaluate the expression before point, in the context outside of Edebug
+(@code{edebug-eval-last-sexp}).
+
address@hidden C-c C-u
+Build a new evaluation list from the contents of the buffer
+(@code{edebug-update-eval-list}).
+
address@hidden C-c C-d
+Delete the evaluation list group that point is in
+(@code{edebug-delete-eval-item}).
+
address@hidden C-c C-w
+Switch back to the source code buffer at the current stop point
+(@code{edebug-where}).
address@hidden table
+
+ You can evaluate expressions in the evaluation list window with
address@hidden or @kbd{C-x C-e}, just as you would in @samp{*scratch*};
+but they are evaluated in the context outside of Edebug.
+
+ The expressions you enter interactively (and their results) are lost
+when you continue execution; but you can set up an @dfn{evaluation list}
+consisting of expressions to be evaluated each time execution stops.
+
address@hidden evaluation list group
+ To do this, write one or more @dfn{evaluation list groups} in the
+evaluation list buffer. An evaluation list group consists of one or
+more Lisp expressions. Groups are separated by comment lines.
+
+ The command @kbd{C-c C-u} (@code{edebug-update-eval-list}) rebuilds the
+evaluation list, scanning the buffer and using the first expression of
+each group. (The idea is that the second expression of the group is the
+value previously computed and displayed.)
+
+ Each entry to Edebug redisplays the evaluation list by inserting each
+expression in the buffer, followed by its current value. It also
+inserts comment lines so that each expression becomes its own group.
+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.
+
+ Here is an example of what the evaluation list window looks like after
+several expressions have been added to it:
+
address@hidden
+(current-buffer)
+#<buffer *scratch*>
+;---------------------------------------------------------------
+(selected-window)
+#<window 16 on *scratch*>
+;---------------------------------------------------------------
+(point)
+196
+;---------------------------------------------------------------
+bad-var
+"Symbol's value as variable is void: bad-var"
+;---------------------------------------------------------------
+(recursion-depth)
+0
+;---------------------------------------------------------------
+this-command
+eval-last-sexp
+;---------------------------------------------------------------
address@hidden smallexample
+
+To delete a group, move point into it and type @kbd{C-c C-d}, or simply
+delete the text for the group and update the evaluation list with
address@hidden C-u}. To add a new expression to the evaluation list, insert
+the expression at a suitable place, insert a new comment line, then type
address@hidden 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
+you continue execution, and recreated next time it is needed.
+
address@hidden Printing in Edebug
address@hidden Printing in Edebug
+
address@hidden printing (Edebug)
address@hidden printing circular structures
address@hidden cust-print
+ If an expression in your program produces a value containing circular
+list structure, you may get an error when Edebug attempts to print it.
+
+ 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.)
address@hidden Variables}.
+
address@hidden edebug-print-length
+If address@hidden, Edebug binds @code{print-length} to this value while
+printing results. The default value is @code{50}.
address@hidden defopt
+
address@hidden edebug-print-level
+If address@hidden, Edebug binds @code{print-level} to this value while
+printing results. The default value is @code{50}.
address@hidden defopt
+
+ You can also print circular structures and structures that share
+elements more informatively by binding @code{print-circle}
+to a address@hidden value.
+
+ Here is an example of code that creates a circular structure:
+
address@hidden
+(setq a '(x y))
+(setcar a a)
address@hidden example
+
address@hidden
+Custom printing prints this as @samp{Result: #1=(#1# y)}. The
address@hidden notation labels the structure that follows it with the label
address@hidden, and the @samp{#1#} notation references the previously labeled
+structure. This notation is used for any shared elements of lists or
+vectors.
+
address@hidden edebug-print-circle
+If address@hidden, Edebug binds @code{print-circle} to this value while
+printing results. The default value is @code{t}.
address@hidden defopt
+
+ Other programs can also use custom printing; see @file{cust-print.el}
+for details.
+
address@hidden Trace Buffer
address@hidden Trace Buffer
address@hidden trace buffer
+
+ Edebug can record an execution trace, storing it in a buffer named
address@hidden 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 address@hidden value.
+
+ Making a trace buffer is not the same thing as using trace execution
+mode (@pxref{Edebug Execution Modes}).
+
+ When trace recording is enabled, each function entry and exit adds
+lines to the trace buffer. A function entry record consists of
address@hidden::::@{}, followed by the function name and argument values. A
+function exit record consists of @samp{::::@}}, followed by the function
+name and result of the function.
+
+ The number of @samp{:}s in an entry shows its recursion depth. You
+can use the braces in the trace buffer to find the matching beginning or
+end of function calls.
+
address@hidden edebug-print-trace-before
address@hidden edebug-print-trace-after
+ You can customize trace recording for function entry and exit by
+redefining the functions @code{edebug-print-trace-before} and
address@hidden
+
address@hidden edebug-tracing string address@hidden
+This macro requests additional trace information around the execution
+of the @var{body} forms. The argument @var{string} specifies text
+to put in the trace buffer, after the @address@hidden or @address@hidden All
+the arguments are evaluated, and @code{edebug-tracing} returns the
+value of the last form in @var{body}.
address@hidden defmac
+
address@hidden edebug-trace format-string &rest format-args
+This function inserts text in the trace buffer. It computes the text
+with @code{(apply 'format @var{format-string} @var{format-args})}.
+It also appends a newline to separate entries.
address@hidden defun
+
+ @code{edebug-tracing} and @code{edebug-trace} insert lines in the
+trace buffer whenever they are called, even if Edebug is not active.
+Adding text to the trace buffer also scrolls its window to show the last
+lines inserted.
+
address@hidden Coverage Testing
address@hidden Coverage Testing
+
address@hidden coverage testing (Edebug)
address@hidden frequency counts
address@hidden performance analysis
+ Edebug provides rudimentary coverage testing and display of execution
+frequency.
+
+ Coverage testing works by comparing the result of each expression with
+the previous result; each form in the program is considered ``covered''
+if it has returned two different values since you began testing coverage
+in the current Emacs session. Thus, to do coverage testing on your
+program, execute it under various conditions and note whether it behaves
+correctly; Edebug will tell you when you have tried enough different
+conditions that each form has returned two different values.
+
+ Coverage testing makes execution slower, so it is only done if
address@hidden is address@hidden Frequency counting is
+performed for all execution of an instrumented function, even if the
+execution mode is Go-nonstop, and regardless of whether coverage testing
+is enabled.
+
address@hidden C-x X =
address@hidden edebug-temp-display-freq-count
+ Use @kbd{C-x X =} (@code{edebug-display-freq-count}) to display both
+the coverage information and the frequency counts for a definition.
+Just @kbd{=} (@code{edebug-temp-display-freq-count}) displays the same
+information temporarily, only until you type another key.
+
address@hidden Command edebug-display-freq-count
+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.
+
+The character @samp{=} following the count for an expression says that
+the expression has returned the same value each time it was evaluated.
+In other words, it is not yet ``covered'' for coverage testing purposes.
+
+To clear the frequency count and coverage data for a definition,
+simply reinstrument it with @code{eval-defun}.
address@hidden deffn
+
+For example, after evaluating @code{(fac 5)} with a source
+breakpoint, and setting @code{edebug-test-coverage} to @code{t}, when
+the breakpoint is reached, the frequency data looks like this:
+
address@hidden
+(defun fac (n)
+ (if (= n 0) (edebug))
+;#6 1 = =5
+ (if (< 0 n)
+;#5 =
+ (* n (fac (1- n)))
+;# 5 0
+ 1))
+;# 0
address@hidden example
+
+The comment lines show that @code{fac} was called 6 times. The
+first @code{if} statement returned 5 times with the same result each
+time; the same is true of the condition on the second @code{if}.
+The recursive call of @code{fac} did not return at all.
+
+
address@hidden The Outside Context
address@hidden The Outside Context
+
+Edebug tries to be transparent to the program you are debugging, but it
+does not succeed completely. Edebug also tries to be transparent when
+you evaluate expressions with @kbd{e} or with the evaluation list
+buffer, by temporarily restoring the outside context. This section
+explains precisely what context Edebug restores, and how Edebug fails to
+be completely transparent.
+
address@hidden
+* 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.
address@hidden menu
+
address@hidden Checking Whether to Stop
address@hidden Checking Whether to Stop
+
+Whenever Edebug is entered, it needs to save and restore certain data
+before even deciding whether to make trace information or stop the
+program.
+
address@hidden @bullet
address@hidden
address@hidden 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.
+
address@hidden
+The state of keyboard macro execution is saved and restored. While
+Edebug is active, @code{executing-kbd-macro} is bound to @code{nil}
+unless @code{edebug-continue-kbd-macro} is address@hidden
address@hidden itemize
+
+
address@hidden Edebug Display Update
address@hidden Edebug Display Update
+
address@hidden This paragraph is not filled, because LaLiberte's conversion
script
address@hidden 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.
+
+Emacs redisplays only when it pauses. Usually, when you continue
+execution, the program re-enters Edebug at a breakpoint or after
+stepping, without pausing or reading input in between. In such cases,
+Emacs never gets a chance to redisplay the ``outside'' configuration.
+Consequently, what you see is the same window configuration as the last
+time Edebug was active, with no interruption.
+
+Entry to Edebug for displaying something also saves and restores the
+following data (though some of them are deliberately not restored if an
+error or quit signal occurs).
+
address@hidden @bullet
address@hidden
address@hidden current buffer point and mark (Edebug)
+Which buffer is current, and the positions of point and the mark in the
+current buffer, are saved and restored.
+
address@hidden
address@hidden window configuration (Edebug)
+The outside window configuration is saved and restored if
address@hidden is address@hidden (@pxref{Edebug Options}).
+
+The window configuration is not restored on error or quit, but the
+outside selected window @emph{is} reselected even on error or quit in
+case a @code{save-excursion} is active. If the value of
address@hidden is a list, only the listed windows are saved
+and restored.
+
+The window start and horizontal scrolling of the source code buffer are
+not restored, however, so that the display remains coherent within Edebug.
+
address@hidden
+The value of point in each displayed buffer is saved and restored if
address@hidden is address@hidden
+
address@hidden
+The variables @code{overlay-arrow-position} and
address@hidden are saved and restored. So you can safely
+invoke Edebug from the recursive edit elsewhere in the same buffer.
+
address@hidden
address@hidden is locally bound to @code{nil} so that
+the cursor shows up in the window.
address@hidden itemize
+
address@hidden Edebug Recursive Edit
address@hidden Edebug Recursive Edit
+
+When Edebug is entered and actually reads commands from the user, it
+saves (and later restores) these additional data:
+
address@hidden @bullet
address@hidden
+The current match data. @xref{Match Data}.
+
address@hidden
+The variables @code{last-command}, @code{this-command},
address@hidden, @code{last-input-char},
address@hidden, @code{last-command-event},
address@hidden, @code{last-nonmenu-event}, and
address@hidden Commands used within 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
+reset the key sequence from Lisp.
+
+Edebug cannot save and restore the value of
address@hidden Entering Edebug while this variable has a
+nontrivial value can interfere with execution of the program you are
+debugging.
+
address@hidden
+Complex commands executed while in Edebug are added to the variable
address@hidden In rare cases this can alter execution.
+
address@hidden
+Within Edebug, the recursion depth appears one deeper than the recursion
+depth outside Edebug. This is not true of the automatically updated
+evaluation list window.
+
address@hidden
address@hidden and @code{standard-input} are bound to @code{nil}
+by the @code{recursive-edit}, but Edebug temporarily restores them during
+evaluations.
+
address@hidden
+The state of keyboard macro definition is saved and restored. While
+Edebug is active, @code{defining-kbd-macro} is bound to
address@hidden
address@hidden itemize
+
address@hidden Edebug and Macros
address@hidden Edebug and Macros
+
+To make Edebug properly instrument expressions that call macros, some
+extra care is needed. This subsection explains the details.
+
address@hidden
+* 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.
address@hidden menu
+
address@hidden Instrumenting Macro Calls
address@hidden Instrumenting Macro Calls
+
+ When Edebug instruments an expression that calls a Lisp macro, it needs
+additional information about the macro to do the job properly. This is
+because there is no a-priori way to tell which subexpressions of the
+macro call are forms to be evaluated. (Evaluation may occur explicitly
+in the macro body, or when the resulting expansion is evaluated, or any
+time later.)
+
+ Therefore, you must define an Edebug specification for each macro
+that Edebug will encounter, to explain the format of calls to that
+macro. To do this, add a @code{debug} declaration to the macro
+definition. Here is a simple example that shows the specification for
+the @code{for} example macro (@pxref{Argument Evaluation}).
+
address@hidden
+(defmacro for (var from init to final do &rest body)
+ "Execute a simple \"for\" loop.
+For example, (for i from 1 to 10 do (print i))."
+ (declare (debug (symbolp "from" form "to" form "do" &rest form)))
+ ...)
address@hidden smallexample
+
+ The Edebug specification says which parts of a call to the macro are
+forms to be evaluated. For simple macros, the @var{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.
+
+ You can also define an edebug specification for a macro separately
+from the macro definition with @code{def-edebug-spec}. Adding
address@hidden 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.
+
address@hidden Macro 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.
address@hidden deffn
+
+Here is a table of the possibilities for @var{specification} and how each
+directs processing of arguments.
+
address@hidden @asis
address@hidden @code{t}
+All arguments are instrumented for evaluation.
+
address@hidden @code{0}
+None of the arguments is instrumented.
+
address@hidden a symbol
+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.
+
address@hidden a list
+The elements of the list describe the types of the arguments of a
+calling form. The possible elements of a specification list are
+described in the following sections.
address@hidden table
+
address@hidden 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
address@hidden comes into play. If it is @code{nil},
+the default, none of the arguments is instrumented for evaluation.
+If it is address@hidden, all arguments are instrumented.
+
address@hidden Specification List
address@hidden Specification List
+
address@hidden Edebug specification list
+A @dfn{specification list} is required for an Edebug specification if
+some arguments of a macro call are evaluated while others are not. Some
+elements in a specification list match one or more arguments, but others
+modify the processing of all following elements. The latter, called
address@hidden keywords}, are symbols beginning with @samp{&} (such
+as @code{&optional}).
+
+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.
address@hidden, for more details.
+
+Edebug specifications provide the power of regular expression matching,
+plus some context-free grammar constructs: the matching of sublists with
+balanced parentheses, recursive processing of forms, and recursion via
+indirect specifications.
+
+Here's a table of the possible elements of a specification list, with
+their meanings (see @ref{Specification Examples}, for the referenced
+examples):
+
address@hidden @code
address@hidden sexp
+A single unevaluated Lisp object, which is not instrumented.
address@hidden an "expression" is not necessarily intended for evaluation.
+
address@hidden form
+A single evaluated expression, which is instrumented.
+
address@hidden place
address@hidden edebug-unwrap
+A place to store a value, as in the Common Lisp @code{setf} construct.
+
address@hidden body
+Short for @code{&rest form}. See @code{&rest} below.
+
address@hidden function-form
+A function form: either a quoted function symbol, a quoted lambda
+expression, or a form (that should evaluate to a function symbol or
+lambda expression). This is useful when an argument that's a lambda
+expression might be quoted with @code{quote} rather than
address@hidden, since it instruments the body of the lambda expression
+either way.
+
address@hidden lambda-expr
+A lambda expression with no quoting.
+
address@hidden &optional
address@hidden @kindex &optional @r{(Edebug)}
+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,
+use @code{[&optional @address@hidden To specify that several
+elements must all match or none, use @code{&optional
address@hidden@dots{}]}. See the @code{defun} example.
+
address@hidden &rest
address@hidden @kindex &rest @r{(Edebug)}
+All following elements in the specification list are repeated zero or
+more times. In the last repetition, however, it is not a problem if the
+expression runs out before matching all of the elements of the
+specification list.
+
+To repeat only a few elements, use @code{[&rest @address@hidden
+To specify several elements that must all match on every repetition, use
address@hidden&rest address@hidden@dots{}]}.
+
address@hidden &or
address@hidden @kindex &or @r{(Edebug)}
+Each of the following elements in the specification list is an
+alternative. One of the alternatives must match, or the @code{&or}
+specification fails.
+
+Each list element following @code{&or} is a single alternative. To
+group two or more list elements as a single alternative, enclose them in
address@hidden@dots{}]}.
+
address@hidden ¬
address@hidden @kindex ¬ @r{(Edebug)}
+Each of the following elements is matched as alternatives as if by using
address@hidden&or}, but if any of them match, the specification fails. If none
+of them match, nothing is matched, but the @code{¬} specification
+succeeds.
+
address@hidden &define
address@hidden @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.
+
address@hidden nil
+This is successful when there are no more arguments to match at the
+current argument list level; otherwise it fails. See sublist
+specifications and the backquote example.
+
address@hidden gate
address@hidden preventing backtracking
+No argument is matched but backtracking through the gate is disabled
+while matching the remainder of the specifications at this level. This
+is primarily used to generate more specific syntax error messages. See
address@hidden, for more details. Also see the @code{let} example.
+
address@hidden @var{other-symbol}
address@hidden indirect specifications
+Any other symbol in a specification list may be a predicate or an
+indirect specification.
+
+If the symbol has an Edebug specification, this @dfn{indirect
+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.
+
+Otherwise, the symbol should be a predicate. The predicate is called
+with the argument and the specification fails if the predicate returns
address@hidden In either case, that argument is not instrumented.
+
+Some suitable predicates include @code{symbolp}, @code{integerp},
address@hidden, @code{vectorp}, and @code{atom}.
+
address@hidden address@hidden@dots{}]
address@hidden address@hidden (Edebug)
+A vector of elements groups the elements into a single @dfn{group
+specification}. Its meaning has nothing to do with vectors.
+
address@hidden "@var{string}"
+The argument should be a symbol named @var{string}. This specification
+is equivalent to the quoted symbol, @code{'@var{symbol}}, where the name
+of @var{symbol} is the @var{string}, but the string form is preferred.
+
address@hidden (vector @address@hidden)
+The argument should be a vector whose elements must match the
address@hidden in the specification. See the backquote example.
+
address@hidden (@address@hidden)
+Any other list is a @dfn{sublist specification} and the argument must be
+a list whose elements match the specification @var{elements}.
+
address@hidden dotted lists (Edebug)
+A sublist specification may be a dotted list and the corresponding list
+argument may then be a dotted list. Alternatively, the last @sc{cdr} of a
+dotted list specification may be another sublist specification (via a
+grouping or an indirect specification, e.g., @code{(spec . [(more
address@hidden)])}) whose elements match the non-dotted list arguments.
+This is useful in recursive specifications such as in the backquote
+example. Also see the description of a @code{nil} specification
+above for terminating such recursion.
+
+Note that a sublist specification written as @code{(specs . nil)}
+is equivalent to @code{(specs)}, and @code{(specs .
+(address@hidden))} is equivalent to @code{(specs
address@hidden)}.
address@hidden table
+
address@hidden Need to document extensions with &symbol and :symbol
+
+Here is a list of additional specifications that may appear only after
address@hidden&define}. See the @code{defun} example.
+
address@hidden @code
address@hidden name
+The argument, a symbol, is the name of the defining form.
+
+A defining form is not required to have a name field; and it may have
+multiple name fields.
+
address@hidden :name
+This construct does not actually match an argument. The element
+following @code{:name} should be a symbol; it is used as an additional
+name component for the definition. You can use this to add a unique,
+static component to the name of the definition. It may be used more
+than once.
+
address@hidden arg
+The argument, a symbol, is the name of an argument of the defining form.
+However, lambda-list keywords (symbols starting with @samp{&})
+are not allowed.
+
address@hidden lambda-list
address@hidden lambda-list (Edebug)
+This matches a lambda list---the argument list of a lambda expression.
+
address@hidden def-body
+The argument is the body of code in a definition. This is like
address@hidden, described above, but a definition body must be instrumented
+with a different Edebug call that looks up information associated with
+the definition. Use @code{def-body} for the highest level list of forms
+within the definition.
+
address@hidden 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
+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
address@hidden example.
address@hidden table
+
address@hidden Backtracking
address@hidden Backtracking in Specifications
+
address@hidden backtracking
address@hidden syntax error (Edebug)
+If a specification fails to match at some point, this does not
+necessarily mean a syntax error will be signaled; instead,
address@hidden will take place until all alternatives have been
+exhausted. Eventually every element of the argument list must be
+matched by some element in the specification, and every required element
+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
+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
address@hidden&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
address@hidden). These specifications will match any form so any error
+must be in the form itself rather than at a higher level.
+
+Backtracking is also disabled after successfully matching a quoted
+symbol or string specification, since this usually indicates a
+recognized construct. But if you have a set of alternative constructs that
+all begin with the same symbol, you can usually work around this
+constraint by factoring the symbol out of the alternatives, e.g.,
address@hidden"foo" &or [first case] [second case] ...]}.
+
+Most needs are satisfied by these two ways that backtracking is
+automatically disabled, but occasionally it is useful to explicitly
+disable backtracking by using the @code{gate} specification. This is
+useful when you know that no higher alternatives could apply. See the
+example of the @code{let} specification.
+
address@hidden Specification Examples
address@hidden Specification Examples
+
+It may be easier to understand Edebug specifications by studying
+the examples provided here.
+
+A @code{let} special form has a sequence of bindings and a body. Each
+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.
+
address@hidden
+(def-edebug-spec let
+ ((&rest
+ &or symbolp (gate symbolp &optional form))
+ body))
address@hidden example
+
+Edebug uses the following specifications for @code{defun} and
address@hidden 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.
+
address@hidden
+(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.}
+ [&optional ("interactive" interactive)]
+ def-body))
+
+(def-edebug-spec lambda-list
+ (([&rest arg]
+ [&optional ["&optional" arg &rest arg]]
+ &optional ["&rest" arg]
+ )))
+
+(def-edebug-spec interactive
+ (&optional &or stringp def-form)) ; @r{Notice: @code{def-form}}
address@hidden smallexample
+
+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.)
+
address@hidden
+(def-edebug-spec ` (backquote-form)) ; @r{Alias just for clarity.}
+
+(def-edebug-spec backquote-form
+ (&or ([&or "," ",@@"] &or ("quote" backquote-form) form)
+ (backquote-form . [&or nil backquote-form])
+ (vector &rest backquote-form)
+ sexp))
address@hidden smallexample
+
+
address@hidden Edebug Options
address@hidden Edebug Options
+
+ These options affect the behavior of Edebug:
+
address@hidden 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
address@hidden is reset 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.
address@hidden
address@hidden defopt
+
address@hidden edebug-all-defs
+If this is address@hidden, normal evaluation of defining forms such as
address@hidden and @code{defmacro} instruments them for Edebug. This
+applies to @code{eval-defun}, @code{eval-region}, @code{eval-buffer},
+and @code{eval-current-buffer}.
+
+Use the command @kbd{M-x edebug-all-defs} to toggle the value of this
+option. @xref{Instrumenting}.
address@hidden defopt
+
address@hidden edebug-all-forms
+If this is address@hidden, the commands @code{eval-defun},
address@hidden, @code{eval-buffer}, and @code{eval-current-buffer}
+instrument all forms, even those that don't define anything.
+This doesn't apply to loading or evaluations in the minibuffer.
+
+Use the command @kbd{M-x edebug-all-forms} to toggle the value of this
+option. @xref{Instrumenting}.
address@hidden defopt
+
address@hidden edebug-save-windows
+If this is address@hidden, Edebug saves and restores the window
+configuration. That takes some time, so if your program does not care
+what happens to the window configurations, it is better to set this
+variable to @code{nil}.
+
+If the value is a list, only the listed windows are saved and
+restored.
+
+You can use the @kbd{W} command in Edebug to change this variable
+interactively. @xref{Edebug Display Update}.
address@hidden defopt
+
address@hidden edebug-save-displayed-buffer-points
+If this is address@hidden, Edebug saves and restores point in all
+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
+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.
+
+Saving and restoring point in all buffers is expensive, since it
+requires selecting each window twice, so enable this only if you need
+it. @xref{Edebug Display Update}.
address@hidden defopt
+
address@hidden edebug-initial-mode
+If this variable is address@hidden, it specifies the initial execution
+mode for Edebug when it is first activated. Possible values are
address@hidden, @code{next}, @code{go}, @code{Go-nonstop}, @code{trace},
address@hidden, @code{continue}, and @code{Continue-fast}.
+
+The default value is @code{step}.
address@hidden Execution Modes}.
address@hidden defopt
+
address@hidden edebug-trace
+If this is address@hidden, trace each function entry and exit.
+Tracing output is displayed in a buffer named @samp{*edebug-trace*}, one
+function entry or exit per line, indented by the recursion level.
+
+Also see @code{edebug-tracing}, in @ref{Trace Buffer}.
address@hidden defopt
+
address@hidden edebug-test-coverage
+If address@hidden, Edebug tests coverage of all expressions debugged.
address@hidden Testing}.
address@hidden defopt
+
address@hidden edebug-continue-kbd-macro
+If address@hidden, continue defining or executing any keyboard macro
+that is executing outside of Edebug. Use this with caution since it is not
+debugged.
address@hidden Execution Modes}.
address@hidden defopt
+
address@hidden edebug-on-error
+Edebug binds @code{debug-on-error} to this value, if
address@hidden was previously @code{nil}. @xref{Trapping
+Errors}.
address@hidden defopt
+
address@hidden edebug-on-quit
+Edebug binds @code{debug-on-quit} to this value, if
address@hidden was previously @code{nil}. @xref{Trapping
+Errors}.
address@hidden defopt
+
+ If you change the values of @code{edebug-on-error} or
address@hidden while Edebug is active, their values won't be used
+until the @emph{next} time Edebug is invoked via a new command.
address@hidden Not necessarily a deeper command level.
address@hidden A new command is not precisely true, but that is close enough --
dan
+
address@hidden edebug-global-break-condition
+If address@hidden, an expression to test for at every stop point. If
+the result is address@hidden, then break. Errors are ignored.
address@hidden Break Condition}.
address@hidden defopt
+
address@hidden
+ arch-tag: 74842db8-019f-4818-b5a4-b2de878e57fd
address@hidden ignore