diff lispref/edebug.texi @ 6558:fa8ff07eaafc

Initial revision

--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/lispref/edebug.texi	Mon Mar 28 20:21:44 1994 +0000
@@ -0,0 +1,1676 @@
+@comment -*-texinfo-*-
+
+@c This file is intended to be used as a section within the Emacs Lisp 
+@c Reference Manual.  It may also be used by an independent Edebug User 
+@c Manual, edebug.tex, in which case the Edebug node below should be used 
+@c with the following links to the Bugs section and to the top level:
+
+@c , Bugs and Todo List, Top, Top
+
+@node Edebug, Bugs and Todo List, Top, Top
+@section Edebug
+@cindex Edebug mode
+
+@cindex Edebug
+  Edebug is a source-level debugger for Emacs Lisp programs with which
+you can:
+
+@itemize @bullet
+@item
+Step through evaluation, stopping before and after each expression.
+
+@item
+Set conditional or unconditional breakpoints.
+
+@item
+Stop when a specified condition is true (the global break event).
+
+@item
+Trace slow or fast, stopping briefly at each stop point, or
+at each breakpoint.
+
+@item
+Display expression results and evaluate expressions as if outside of
+Edebug.
+
+@item 
+Automatically reevaluate a list of expressions and
+display their results each time Edebug updates the display.
+
+@item
+Output trace info on function enter and exit.
+
+@item
+Stop when an error occurs.
+
+@item
+Display a backtrace, omitting Edebug's own frames.
+
+@item
+Specify argument evaluation for macros and defining forms.
+
+@item
+Obtain rudimentary coverage testing and frequency counts.
+@end itemize
+
+The first three sections below should tell you enough about Edebug to
+enable you to use it.
+
+@menu
+* 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.
+* Breakpoints::			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.
+* Instrumenting Macro Calls::	Specifying how to handle macro calls.
+* Options: Edebug Options.	Option variables for customizing Edebug.
+@end menu
+
+@node Using Edebug
+@subsection 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
+@kbd{C-u C-M-x} (@code{eval-defun} with a prefix argument).  See
+@ref{Instrumenting}, for alternative ways to instrument code.
+
+  Once a function is instrumented, any call to the function activates
+Edebug.  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, depending on which Edebug execution
+mode you have selected.  The default execution mode is step, which does
+stop 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}.  This buffer is temporarily read-only.
+
+  An arrow at the left margin 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 normally see.  Point is at the
+open-parenthesis before @code{if}.
+
+@example
+(defun fac (n)
+=>@point{}(if (< 0 n)
+      (* n (fac (1- n)))
+    1))
+@end example
+
+@cindex stop points
+The places within a function where Edebug can stop execution are called
+@dfn{stop points}.  These occur both before and after each subexpression
+that is a list, and also after each variable reference.  
+Here we show with periods the stop points found in the function
+@code{fac}:
+
+@example
+(defun fac (n)
+  .(if .(< 0 n.).
+      .(* n. .(fac (1- n.).).).
+    1).)
+@end 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:
+
+@example
+(defun fac (n)
+=>(if @point{}(< 0 n)
+      (* n (fac (1- n)))
+    1))
+@end 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.
+
+@node Instrumenting
+@subsection Instrumenting for Edebug
+
+  In order to use Edebug to debug Lisp code, you must first
+@dfn{instrument} the code.  Instrumenting code inserts additional code
+into it, code which invokes Edebug at the proper places.
+
+  Once a function is instrumented, any call to the function activates
+Edebug.  This may or may not stop execution, depending on the Edebug
+execution mode in use.  Some Edebug modes only update the display to
+indicate the progress of the evaluation without stopping execution.
+
+@kindex C-M-x
+@findex eval-defun (Edebug)
+  Once you have loaded Edebug, the command @kbd{C-M-x}
+(@code{eval-defun}) is redefined so that when invoked with a prefix
+argument on a definition, it instruments the definition before
+evaluating it.  (The source code itself is not modified.)  If the
+variable @code{edebug-all-defs} is non-@code{nil}, that inverts the
+meaning of the prefix argument: then @kbd{C-M-x} instruments the
+definition @emph{unless} it has a prefix argument.  The default value of
+@code{edebug-all-defs} is @code{nil}.  The command @kbd{M-x
+edebug-all-defs} toggles the value of the variable
+@code{edebug-all-defs}.
+
+@findex edebug-all-forms
+@findex eval-region (Edebug)
+@findex eval-current-buffer (Edebug)
+  If @code{edebug-all-defs} is non-@code{nil}, then the commands
+@code{eval-region}, @code{eval-current-buffer}, and @code{eval-buffer}
+also instrument any definitions they evaluate.  Similarly,
+@code{edebug-all-forms} 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.
+
+@findex 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 value of
+@code{edebug-all-defs} or @code{edebug-all-forms}.
+
+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 @code{nil}.
+You can use this to load up Edebug specifications associated with a
+package you are using, but only when you also use Edebug.
+
+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; 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 function.
+
+@cindex special forms (Edebug)
+@cindex interactive commands (Edebug)
+@cindex anonymous lambda expressions (Edebug)
+@cindex Common Lisp (Edebug)
+@pindex cl.el (Edebug)
+@pindex cl-specs.el
+  Edebug knows how to instrument all the standard special forms, an
+interactive form with an expression argument, anonymous lambda
+expressions, and other defining forms.  Edebug cannot know what a
+user-defined macro will do with the arguments of a macro call, so you
+must tell it; @xref{Instrumenting Macro Calls}, for details.
+
+@findex eval-expression (Edebug)
+  To remove instrumentation from a definition, simply reevaluate its
+definition in a way that does not instrument.  There are two ways of
+evaluating forms without instrumenting them: from a file with
+@code{load}, and from the minibuffer with @code{eval-expression}
+(@kbd{M-ESC}).
+
+  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.
+
+@node Edebug Execution Modes
+@subsection Edebug Execution Modes
+
+@cindex 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 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.
+
+@table @kbd
+@item S
+Stop: don't execute any more of the program for now, just wait for more
+Edebug commands (@code{edebug-stop}).
+
+@item @key{SPC}
+Step: stop at the next stop point encountered (@code{edebug-step-mode}).
+
+@item n
+Next: stop at the next stop point encountered after an expression
+(@code{edebug-next-mode}).  Also see @code{edebug-forward-sexp} in
+@ref{Edebug Misc}.
+
+@item t
+Trace: pause one second at each Edebug stop point (@code{edebug-trace-mode}).
+
+@item T
+Rapid trace: update the display at each stop point, but don't actually
+pause (@code{edebug-Trace-fast-mode}).
+
+@item g
+Go: run until the next breakpoint (@code{edebug-go-mode}).  @xref{Breakpoints}.
+
+@item c
+Continue: pause one second at each breakpoint, and then continue
+(@code{edebug-continue-mode}).
+
+@item C
+Rapid continue: move point to each breakpoint, but don't pause
+(@code{edebug-Continue-fast-mode}).
+
+@item 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.
+@end table
+
+In general, the execution modes earlier in the above list run the
+program more slowly or stop sooner.
+
+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 that you typed.  For example, typing @kbd{t}
+during execution switches to trace mode at the next stop point.  You can
+use @kbd{S} 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.
+
+@cindex 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.  But see the
+@code{edebug-continue-kbd-macro} 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}.  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.
+
+
+@node Jumping
+@subsection 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,
+because a nonlocal exit can bypass the temporary breakpoint where you
+expected the program to stop.
+
+@table @kbd
+@item h
+Proceed to the stop point near where point is (@code{edebug-goto-here}).
+
+@item f
+Run the program forward over one expression
+(@code{edebug-forward-sexp}).
+
+@item o
+Run the program until the end of the containing sexp.
+
+@item i
+Step into the function or macro called by the form after point.
+@end table
+
+The @kbd{h} command proceeds to the stop point near the current location
+if point, using a temporary breakpoint.  See @ref{Breakpoints}, for more
+about breakpoints.
+
+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.
+
+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.
+
+Be careful that the position @kbd{C-M-f} finds is a place that the
+program will really get to; this may not be true in a
+@code{cond}, for example.
+
+The @kbd{f} command does @code{forward-sexp} starting at point, rather
+than at the stop point, for flexibility.  If you want to execute one
+expression @emph{from the current stop point}, type @kbd{w} first, 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, it 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.  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.
+
+@node Edebug Misc
+@subsection Miscellaneous Edebug Commands
+
+  Some miscellaneous Edebug commands are described here.
+
+@table @kbd
+@item ?
+Display the help message for Edebug (@code{edebug-help}).
+
+@item C-]
+Abort one level back to the previous command level
+(@code{abort-recursive-edit}).
+
+@item 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
+@code{unwind-protect} or @code{condition-case} forms may resume
+debugging.
+
+@item Q
+Like @kbd{q} but don't stop even for protected code
+(@code{top-level-nonstop}).
+
+@item r
+Redisplay the most recently known expression result in the echo area
+(@code{edebug-previous-result}).
+
+@item 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.
+@end table
+
+>From the Edebug recursive edit, you may invoke commands that activate
+Edebug again recursively.  Any time 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}.
+
+@node Breakpoints
+@subsection Breakpoints
+
+@cindex breakpoints
+Edebug's step mode stops execution at the next stop point reached.
+There are three other ways to stop Edebug execution once it has started:
+breakpoints, the global break condition, and source breakpoints.
+
+While using Edebug, you can specify @dfn{breakpoints} in the program you
+are testing: points 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:
+
+@table @kbd
+@item 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).
+
+@item u
+Unset the breakpoint (if any) at the stop point at or after 
+point (@code{edebug-unset-breakpoint}).
+
+@item x @var{condition} @key{RET}
+Set a conditional breakpoint which stops the program only if
+@var{condition} evaluates to a non-@code{nil} value
+(@code{edebug-set-conditional-breakpoint}).  With a prefix argument, the
+breakpoint is temporary.
+
+@item B
+Move point to the next breakpoint in the definition
+(@code{edebug-next-breakpoint}).
+@end 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.
+
+Reevaluating or reinstrumenting a definition forgets all its 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
+@dfn{temporary} by using a prefix arg 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 in the definition following point, or
+to the first breakpoint if there are no following breakpoints.  This
+command does not continue execution---it just moves point in the buffer.
+
+@menu
+* Global Break Condition::	Breaking on an event. 
+* Source Breakpoints::  	Embedding breakpoints in source code.
+@end menu
+
+
+@node Global Break Condition
+@subsubsection Global Break Condition
+
+@cindex stopping on events
+@cindex 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 non-@code{nil} 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.
+
+@findex edebug-set-global-break-condition
+@vindex edebug-global-break-condition
+  You can set or edit the condition expression, stored in
+@code{edebug-global-break-condition}, using the @kbd{X} command
+(@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.
+
+@node Source Breakpoints
+@subsubsection Source Breakpoints
+
+@findex edebug
+@cindex source breakpoints
+  All breakpoints in a definition are forgotten each time you
+reinstrument it.  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, insert the first
+line as shown below to stop when the argument reaches zero:
+
+@example
+(defun fac (n)
+  (if (= n 0) (edebug))
+  (if (< 0 n)
+      (* n (fac (1- n)))
+    1))
+@end 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}.
+@c This may not be a good idea anymore.
+
+@node Trapping Errors
+@subsection Trapping Errors
+
+Emacs normally displays an error message when an error is signaled and
+not handled with @code{condition-case}.  While Edebug is active, 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, 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}).
+
+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.
+
+@ignore @c I don't want to document something that works only partly -- rms.
+Edebug can also trap signals even if they are handled.  If
+@code{debug-on-error} is a list of signal names, Edebug will stop when
+any of these errors are signaled.  Edebug shows you the last known stop
+point just as for unhandled errors.  After you continue execution, the
+error is signaled again (but without being caught by Edebug).  Edebug
+can only trap errors that are handled if they are signaled in Lisp code
+(not subroutines) since it does so by temporarily replacing the
+@code{signal} function.
+@end ignore
+
+@node Edebug Views
+@subsection Edebug Views
+
+These Edebug commands let you view aspects of the buffer and window
+status that obtained before entry to Edebug.
+
+@table @kbd
+@item v
+View the outside window configuration (@code{edebug-view-outside}).
+
+@item p
+Temporarily display the outside current buffer with point at its outside
+position (@code{edebug-bounce-point}).  With a prefix argument @var{n},
+pause for @var{n} seconds instead.
+
+@item w
+Move point back to the current stop point (@code{edebug-where}) in the
+source code buffer.  Also, 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.
+
+@item W
+Forget the saved outside window configuration---so that the current
+window configuration will remain unchanged when you next exit Edebug (by
+continuing the program).  Also toggle the @code{edebug-save-windows}
+variable.
+@ignore  @c This text is implementation-oriented and doesn't emphasize
+            what users really want to know.
+Toggle the @code{edebug-save-windows} variable which indicates whether
+the outside window configuration is saved and restored
+(@code{edebug-toggle-save-windows}).  Also, each time it is toggled on,
+make the outside window configuration the same as the current window
+configuration.
+@end ignore
+@end 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 with @kbd{w} from a source code buffer.
+
+@ignore I don't understand this -- rms
+If you type @kbd{W} twice, Edebug continues saving and restoring an
+outside window configuration, but updates it to match the current
+configuration.  You can use this to add another buffer to be displayed
+whenever Edebug is active.  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.
+
+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.
+@end ignore
+
+@node Edebug Eval
+@subsection 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 things that Edebug explicitly
+saves and restores.  @xref{The Outside Context}, for details on this
+process.
+
+@table @kbd
+@item 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.
+
+@item M-@key{ESC} @var{exp} @key{RET}
+Evaluate expression @var{exp} in the context of Edebug itself.
+
+@item C-x C-e
+Evaluate the expression before point, in the context outside of Edebug
+(@code{edebug-eval-last-sexp}).
+@end table
+
+@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}.
+
+
+@node Eval List
+@subsection Evaluation List Buffer
+
+You can use the @dfn{evaluation list buffer}, called @samp{*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*}
+(@code{edebug-visit-eval-list}).
+@end 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:
+
+@table @kbd
+@item LFD
+Evaluate the expression before point, in the outside context, and insert
+the value in the buffer (@code{edebug-eval-print-last-sexp}).
+
+@item C-x C-e
+Evaluate the expression before point, in the context outside of Edebug
+(@code{edebug-eval-last-sexp}).
+
+@item C-c C-u
+Build a new evaluation list from contents of the buffer
+(@code{edebug-update-eval-list}).
+
+@item C-c C-d
+Delete the evaluation list group that point is in
+(@code{edebug-delete-eval-item}).
+
+@item C-c C-w
+Switch back to the source code buffer at the current stop point
+(@code{edebug-where}).
+@end table
+
+You can evaluate expressions in the evaluation list window with
+@kbd{LFD} 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. 
+
+@cindex 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.
+
+Be careful not to add expressions that execute instrumented code since
+that would cause an infinite loop.
+@c There ought to be a way to fix this.
+
+Redisplaying the evaluation list works 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:
+
+@smallexample
+(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
+;---------------------------------------------------------------
+@end 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
+@kbd{C-c C-u}.  To add a new expression to the evaluation list, insert
+the expression at a suitable place, and insert a new comment line.  (You
+need not insert dashes in the comment line---its contents don't matter.)
+Then type @kbd{C-c C-u}.
+
+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.
+
+
+@node Printing in Edebug
+@subsection Printing in Edebug
+
+@cindex printing (Edebug)
+@cindex printing circular structures
+@pindex 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.
+
+@vindex edebug-print-length
+@vindex edebug-print-level
+  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 can also print circular structures and structures that share
+elements more informatively by using the @file{cust-print} package.
+
+  To load @file{cust-print} and activate custom printing only for
+Edebug, simply use the command @kbd{M-x edebug-install-custom-print}.
+To restore the standard print functions, use @kbd{M-x
+edebug-uninstall-custom-print}.
+
+  Here is an example of code that creates a circular structure:
+
+@example
+(setq a '(x y))
+(setcar a a))
+@end example
+
+@noindent
+Custom printing prints this as @samp{Result: #1=(#1# y)}.  The
+@samp{#1=} notation labels the structure that follows it with the label
+@samp{1}, and the @samp{#1#} notation references the previously labelled
+structure.  This notation is used for any shared elements of lists or
+vectors.
+
+  Other programs can also use custom printing; see @file{cust-print.el}
+for details.
+
+@node Trace Buffer
+@subsection Trace Buffer
+@cindex trace buffer
+
+  Edebug can record an execution trace in a buffer named
+@samp{*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.
+
+  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 looks like
+@samp{::::@{} followed by the function name and argument values.  A
+function exit record looks like @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.
+
+@findex edebug-print-trace-before
+@findex edebug-print-trace-after
+  You can customize trace recording for function entry and exit by
+redefining the functions @code{edebug-print-trace-before} and
+@code{edebug-print-trace-after}.
+
+@defmac edebug-tracing string body@dots{}
+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.  All the arguments are evaluated.
+@code{edebug-tracing} returns the value of the last form in @var{body}.
+@end defmac
+
+@defun 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 inserts a newline to separate entries.
+@end defun
+
+  @code{edebug-tracing} and @code{edebug-trace} insert lines in the trace
+buffer even if Edebug is not active.
+
+  Adding text to the trace buffer also scrolls its window to show the
+last lines inserted.
+
+@ignore  @c too vague
+There may be some display problems if you use
+tracing along with the evaluation list.
+@end ignore
+
+@node Coverage Testing
+@subsection Coverage Testing
+
+@cindex coverage testing
+@cindex frequency counts
+@cindex performance analysis
+Edebug provides rudimentary coverage testing and display of execution
+frequency.  All execution of an instrumented function accumulates
+frequency counts, both before and after evaluation of each instrumented
+expression, even if the execution mode is Go-nonstop.  Coverage testing
+is more expensive, so it is only done if @code{edebug-test-coverage} is
+non-@code{nil}.  The command @kbd{M-x edebug-display-freq-count}
+displays both the frequency data and the coverage data (if recorded).
+
+@deffn Command edebug-display-freq-count
+This command displays the frequency count data for each line of the
+current definition.
+
+The frequency counts appear comment lines after each line of code, and
+you can undo all insertions with one @code{undo} command.  The counts
+are appear under the @kbd{(} before an expression or the @kbd{)} after
+an expression, or on the last character of a symbol.  Values do not appear if
+they are equal to the previous count 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
+This is the only coverage information that Edebug records.
+
+To clear the frequency count and coverage data for a definition,
+reinstrument it.
+@end 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:
+
+@example
+(defun fac (n)
+  (if (= n 0) (edebug))
+;#6           1      0 =5 
+  (if (< 0 n)
+;#5         = 
+      (* n (fac (1- n)))
+;#    5               0  
+    1))
+;#   0 
+@end example
+
+The comment lines show that @code{fac} has been called 6 times.  The
+first @code{if} statement has 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} has not returned at all.
+
+
+@node The Outside Context
+@subsection 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.
+
+@c This can be fixed and should be
+The same mechanism that avoids masking certain variable's outside values
+also currently makes it impossible to set these variables within Edebug.
+
+@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.
+@end menu
+
+@node Checking Whether to Stop
+@subsubsection Checking Whether to Stop
+
+Whenever Edebug is entered just to think about whether to take some
+action, it needs to save and restore certain data.
+
+@itemize @bullet
+@item 
+@code{max-lisp-eval-depth} and @code{max-specpdl-size} are both
+incremented one time 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
+Edebug is active, @code{executing-macro} is bound to
+@code{edebug-continue-kbd-macro}.
+
+@end itemize
+
+
+@node Edebug Display Update
+@subsubsection Edebug Display Update
+
+When Edebug needs to display something (e.g., in trace mode), it saves
+the current window configuration from ``outside'' Edebug (@pxref{Window
+Configurations,,, elisp, GNU Emacs Lisp Reference Manual}).  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 comes back into 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.
+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, but some of these are deliberately not restored if an
+error or quit signal occurs.
+
+@itemize @bullet
+@item 
+@cindex 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.
+
+@item 
+@cindex window configuration (Edebug)
+The outside window configuration is saved and restored if
+@code{edebug-save-windows} is non-@code{nil} (@pxref{Edebug Display Update}).
+
+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
+@code{edebug-save-windows} 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.
+
+@item
+@vindex edebug-save-displayed-buffer-points
+The value of point in each displayed buffer is saved and restored if
+@code{edebug-save-displayed-buffer-points} is non-@code{nil}.
+
+@item
+The variables @code{overlay-arrow-position} and
+@code{overlay-arrow-string} are saved and restored.  So you can safely
+invoke Edebug from the recursive edit elsewhere in the same buffer.
+
+@item 
+@code{cursor-in-echo-area} is locally bound to @code{nil} so that
+the cursor shows up in the window.
+@end itemize
+
+@node Edebug Recursive Edit
+@subsubsection Edebug Recursive Edit
+
+When Edebug is entered and actually reads commands from the user, it
+saves (and later restores) these additional data:
+
+@itemize @bullet
+@item
+The current match data.  @xref{Match Data}.
+
+@item
+@code{last-command}, @code{this-command}, @code{last-command-char},
+@code{last-input-char}, @code{last-input-event},
+@code{last-command-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.
+
+The key sequence returned by @code{this-command-keys} is changed by
+executing commands within Edebug and there is no way to reset
+the key sequence from Lisp.
+
+@item
+Complex commands executed while in Edebug are added to the variable
+@code{command-history}.  In rare cases this can alter execution.
+
+@item
+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.
+
+@item
+@code{standard-output} and @code{standard-input} are bound to @code{nil}
+by the @code{recursive-edit}, but Edebug temporarily restores them during
+evaluations.
+
+@item 
+The state of keyboard macro definition is saved and restored.  While
+Edebug is active, @code{defining-kbd-macro} is bound to
+@code{edebug-continue-kbd-macro}.
+@end itemize
+
+@node Instrumenting Macro Calls
+@subsection Instrumenting Macro Calls
+
+When Edebug instruments an expression that calls a Lisp macro, it needs
+additional advice to do the job properly.  This is because there is no
+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.)  You must
+explain the format of calls to each macro to enable Edebug to handle it.
+To do this, use @code{def-edebug-form-spec} to define the format of
+calls to a given macro.
+
+@deffn Macro def-edebug-spec macro specification
+Specify which expressions of a call to macro @var{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.
+
+The @var{macro} argument may actually be any symbol, not just a macro
+name.
+@end deffn
+
+Here is a simple example that defines the specification for the
+@code{for} macro described in the Emacs Lisp Reference Manual, followed
+by an alternative, equivalent specification.
+
+@example
+(def-edebug-spec for
+  (symbolp "from" form "to" form "do" &rest form))
+
+(def-edebug-spec for
+  (symbolp ['from form] ['to form] ['do body]))
+@end example
+
+Here is a table of the possibilities for @var{specification} and how each
+directs processing of arguments.
+
+@table @bullet
+
+@item @code{t}
+All arguments are instrumented for evaluation.
+
+@item @code{0}
+None of the arguments is instrumented.
+
+@item 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 for another macro.
+
+@item 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.
+@end table
+
+@menu
+* Specification List::		How to specify complex patterns of evaluation.
+* Backtracking::		What Edebug does when matching fails.
+@c * Debugging Backquote::	Debugging Backquote
+* Specification Examples::	To help understand specifications.
+@end menu
+
+
+@node Specification List
+@subsubsection Specification List
+
+@cindex 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
+@dfn{specification 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 only apply 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.
+
+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:
+
+@table @code
+@item sexp
+A single unevaluated Lisp object object.
+
+@item form
+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.
+
+@item body
+Short for @code{&rest form}.  See @code{&rest} below.
+
+@item 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
+@code{function}, since it instruments the body of the lambda expression
+either way.
+
+@item lambda-expr
+A lambda expression with no quoting.
+
+@item &optional
+@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 @var{specs}@dots{}]}.  To specify that several
+elements must all match or none, use @code{&optional
+[@var{specs}@dots{}]}.  See the @code{defun} example below.
+
+@item &rest
+@kindex &rest @r{(Edebug)}
+All following elements in the specification list are repeated zero or
+more times.  All the elements need not match in the last repetition,
+however.
+
+To repeat only a few elements, use @code{[&rest @var{specs}@dots{}]}.
+To specify several elements that must all match on every repetition, use
+@code{&rest [@var{specs}@dots{}]}.
+
+@item &or
+@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
+@code{[@dots{}]}.
+
+@item &not
+@kindex &not @r{(Edebug)}
+Each of the following elements is matched as alternatives as if by using
+@code{&or}, but if any of them match, the specification fails.  If none
+of them match, nothing is matched, but the @code{&not} specification
+succeeds.
+
+@item &define 
+@kindex &define @r{(Edebug)}
+Indicates that the specification is for a defining form.  The defining
+form itself is not instrumented (i.e. Edebug does not stop before and
+after the defining form), but forms inside it typically will be
+instrumented.  The @code{&define} keyword should be the first element in
+a list specification.
+
+@item nil
+This is successful when there are no more arguments to match at the
+current argument list level; otherwise it fails.  See sublist
+specifications and the backquote example below.
+
+@item gate
+@cindex 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
+@ref{Backtracking}, for more details.  Also see the @code{let} example
+below.
+
+@item @var{other-symbol}
+@cindex 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 below.
+
+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.
+
+@findex keywordp
+@findex lambda-list-keywordp
+Some suitable predicates include @code{symbolp}, @code{integerp},
+@code{stringp}, @code{vectorp}, and @code{atom}.
+@ignore
+, @code{keywordp}, and
+@code{lambda-list-keywordp}.  The last two, defined in @file{edebug.el},
+test whether the argument is a symbol starting with @samp{@code{:}} and
+@samp{@code{&}} respectively.
+@end ignore
+
+@item [@var{elements}@dots{}]
+@cindex [@dots{}] (Edebug)
+A vector of elements groups the elements into a single @dfn{group
+specification}.  Its meaning has nothing to do with vectors.
+
+@item "@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.
+
+@ignore
+@item '@var{symbol} @r{or} (quote @var{symbol})
+The argument should be the symbol @var{symbol}.  But use a string
+specification instead.
+@end ignore
+
+@item (vector @var{elements}@dots{})
+The argument should be a vector whose elements must match the
+@var{elements} in the specification.  See the backquote example below.
+
+@item (@var{elements}@dots{})
+Any other list is a @dfn{sublist specification} and the argument must be
+a list whose elements match the specification @var{elements}.
+
+@cindex 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
+specs@dots{})])}) whose elements match the non-dotted list arguments.
+This is useful in recursive specifications such as in the backquote
+example below.  Also see the description of a @code{nil} specification
+above for terminating such recursion.
+
+Note that a sublist specification of the form @code{(specs .  nil)}
+means the same as @code{(specs)}, and @code{(specs .
+(sublist-elements@dots{}))} means the same as @code{(specs
+sublist-elements@dots{})}.
+@end table
+
+@c Need to document extensions with &symbol and :symbol
+
+Here is a list of additional specifications that may only appear after
+@code{&define}.  See the @code{defun} example below.
+
+@table @code
+@item 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.
+
+@item :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.
+
+@item arg
+The argument, a symbol, is the name of an argument of the defining form.
+However, lambda list keywords (symbols starting with @samp{@code{&}})
+are not allowed.  See @code{lambda-list} and the example below.
+
+@item lambda-list
+@cindex lambda-list (Edebug)
+This matches a lambda list---the argument list of a lambda expression.
+The argument should be a list of symbols.
+
+@item def-body
+The argument is the body of code in a definition.  This is like
+@code{body}, 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.
+
+@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
+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 below.
+@end table
+
+@node Backtracking
+@subsubsection Backtracking
+
+@cindex backtracking
+@cindex syntax error (Edebug)
+If a specification fails to match at some point, this does not
+necessarily mean a syntax error will be signaled; instead,
+@dfn{backtracking} 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.
+
+Backtracking is disabled for the remainder of a sublist or group when
+certain conditions occur, described below.  Backtracking is reenabled
+when a new alternative is established by @code{&optional}, @code{&rest},
+or @code{&or}.  It is also reenabled initially when processing a
+sublist or group specification or an indirect specification.
+
+You might want to disable backtracking to commit to some alternative so
+that Edebug can provide a more specific syntax error message.  Normally,
+if no alternative matches, Edebug reports that none matched, but if one
+alternative is committed to, Edebug can report how it failed to match.
+
+First, backtracking is disabled while matching any of the form
+specifications (i.e. @code{form}, @code{body}, @code{def-form}, and
+@code{def-body}).  These specifications will match any form so any error
+must be in the form itself rather than at a higher level.
+
+Second, backtracking is disabled after successfully matching a quoted
+symbol or string specification, since this usually indicates a
+recognized construct.  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.,
+@code{["foo" &or [first case] [second case] ...]}.
+
+Third, backtracking may be explicitly disabled by using the
+@code{gate} specification.  This is useful when you know that
+no higher alternatives may apply.
+
+@ignore
+@node Debugging Backquote
+@subsubsection Debugging Backquote
+
+@findex ` (Edebug)
+@cindex backquote (Edebug)
+Backquote (@kbd{`}) is a macro that results in an expression that may or
+may not be evaluated.  It is often used to simplify the definition of a
+macro to return an expression to be evaluated, but Edebug cannot know
+whether the resyult of backquote will be used in any other way.
+
+The forms inside unquotes (@code{,} and @code{,@@}) are evaluated, and
+Edebug instruments them.
+
+Edebug supports nested backquotes, but there is a limit on the support
+of quotes inside of backquotes.  Forms quoted with @code{'} are not
+normally evaluated, but if the quoted form appears immediately within
+@code{,} and @code{,@@} forms, Edebug treats this as a backquoted form
+at the next higher level (even if there is not a next higher level; this
+is difficult to fix).
+
+@findex edebug-`
+If the backquoted forms are code to be evaluated, you can have Edebug
+instrument them by using @code{edebug-`} instead of the regular
+@code{`}.  Unquoting forms can be used inside @code{edebug-`} anywhere a
+form is normally allowed.  But @code{(, @var{form})} may be used in two
+other places specially recognized by Edebug: wherever a predicate
+specification would match, and at the head of a list form where the
+function name normally appears.  The @var{form} inside a spliced
+unquote, @code{(,@@ @var{form})}, will be instrumented, but the unquote
+form itself will not be instrumented since this would interfere with the
+splicing.
+
+There is one other complication with using @code{edebug-`}.  If the
+@code{edebug-`} call is in a macro and the macro may be called from code
+that is also instrumented, and if unquoted forms contain any macro
+arguments bound to instrumented forms, then you should modify the
+specification for the macro as follows: the specifications for those
+arguments must use @code{def-form} instead of @code{form}.  (This is to
+reestablish the Edebugging context for those external forms.)
+
+For example, the @code{for} macro (@pxref{Problems with Macros,,, elisp,
+Emacs Lisp Reference Manual}) is shown here but with @code{edebug-`}
+substituted for regular @code{`}.
+
+@example
+(defmacro inc (var)
+  (list 'setq var (list '1+ var)))
+
+(defmacro for (var from init to final do &rest body)
+  (let ((tempvar (make-symbol "max")))
+    (edebug-` (let (((, var) (, init))
+                    ((, tempvar) (, final)))
+                (while (<= (, var) (, tempvar))
+                  (,@ body)
+                  (inc (, var)))))))
+@end example
+
+Here is the corresponding modified Edebug specification and a
+call of the macro:
+
+@example
+(def-edebug-spec for
+  (symbolp "from" def-form "to" def-form "do" &rest def-form))
+
+(let ((n 5))
+  (for i from n to (* n (+ n 1)) do
+    (message "%s" i)))
+@end example
+
+After instrumenting the @code{for} macro and the macro call, Edebug
+first steps to the beginning of the macro call, then into the macro
+body, then through each of the unquoted expressions in the backquote
+showing the expressions that will be embedded.  Then when the macro
+expansion is evaluated, Edebug will step through the @code{let} form and
+each time it gets to an unquoted form, it will jump back to an argument
+of the macro call to step through that expression.  Finally stepping
+will continue after the macro call.  Even more convoluted execution
+paths may result when using anonymous functions.
+
+@vindex edebug-unwrap-results
+When the result of an expression is an instrumented expression, it is
+difficult to see the expression inside the instrumentation.  So
+you may want to set the option @code{edebug-unwrap-results} to a
+non-@code{nil} value while debugging such expressions, but it would slow
+Edebug down to always do this.
+
+@end ignore
+@node Specification Examples
+@subsubsection 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 value.  In the specification below, notice the @code{gate}
+inside of the sublist to prevent backtracking once a sublist is found.
+
+@example
+(def-edebug-spec let
+  ((&rest
+    &or symbolp (gate symbolp &optional form))
+   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 it is actually evaluated outside of the
+function body.
+
+@example
+(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}}
+@end example
+
+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.)
+
+@example
+(def-edebug-spec ` (backquote-form))  ;; 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))
+@end example
+
+
+@node Edebug Options
+@subsection Edebug Options
+
+  These options affect the behavior of Edebug:
+
+@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
+but only when you also use Edebug.
+@xref{Instrumenting}.
+@end defopt
+
+@defopt edebug-all-defs
+If this is non-@code{nil}, normal evaluation of defining forms such as
+@code{defun} and @code{defmacro} instruments them for Edebug.  This
+applies to @code{eval-defun}, @code{eval-region}, and
+@code{eval-current-buffer}.  @xref{Instrumenting}.
+@end defopt
+
+@defopt edebug-all-forms
+If this is non-@code{nil}, the commands @code{eval-defun}, @code{eval-region},
+and @code{eval-current-buffer} instrument all forms, even those that
+don't define anything.
+
+Use the command @kbd{M-x edebug-all-forms} to toggle the value of this
+option.
+@xref{Instrumenting}.
+@end defopt
+
+@defopt edebug-save-windows
+If this is non-@code{nil}, 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}.
+@end defopt
+
+@defopt edebug-save-displayed-buffer-points
+If non-@code{nil}, Edebug saves and restores point in all 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,
+the buffer's point will change to the window's 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}.
+@end defopt
+
+@defopt edebug-initial-mode
+If this variable is non-@code{nil}, it specifies the initial execution
+mode for Edebug when it is first activated.  Possible values are
+@code{step}, @code{next}, @code{go}, @code{Go-nonstop}, @code{trace},
+@code{Trace-fast}, @code{continue}, and @code{Continue-fast}.
+
+The default value is @code{step}.  
+@xref{Edebug Execution Modes}.
+@end defopt
+
+@defopt edebug-trace
+@findex edebug-print-trace-before
+@findex edebug-print-trace-after
+Non-@code{nil} means display a trace of 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.  
+
+The default value is @code{nil}.  
+
+Also see @code{edebug-tracing}.
+@xref{Tracing}.
+@end defopt
+
+@defopt edebug-test-coverage 
+If non-@code{nil}, Edebug tests coverage of all expressions debugged.
+This is done by comparing the result of each expression
+with the previous result. Coverage is considered OK if two different
+results are found.  So to sufficiently test the coverage of your code,
+try to execute it under conditions that evaluate all expressions more
+than once, and produce different results for each expression.
+
+Use @kbd{M-x edebug-display-freq-count} to display the frequency count
+and coverage information for a definition.
+@xref{Coverage Testing}.
+@end defopt
+
+@defopt edebug-continue-kbd-macro 
+If non-@code{nil}, continue defining or executing any keyboard macro
+that is executing outside of Edebug.   Use this with caution since it is not
+debugged.
+@xref{Edebug Execution Modes}.
+@end defopt
+
+@defopt edebug-print-length
+If non-@code{nil}, bind @code{print-length} to this while printing
+results in Edebug.  The default value is @code{50}.
+@xref{Printing in Edebug}.
+@end defopt
+
+@defopt edebug-print-level 
+If non-@code{nil}, bind @code{print-level} to this while printing
+results in Edebug.  The default value is @code{50}.
+@end defopt
+
+@defopt edebug-print-circle 
+If non-@code{nil}, bind @code{print-circle} to this while printing
+results in Edebug.  The default value is @code{nil}.
+@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
+Errors}.
+@end defopt
+
+@defopt edebug-on-quit
+Edebug binds @code{debug-on-quit} to this value, if
+@code{debug-on-quit} was previously @code{nil}.  @xref{Trapping
+Errors}.
+@end defopt
+
+  If you change the values of @code{edebug-on-error} or
+@code{edebug-on-quit} while Edebug is active, their values won't be used
+until the @emph{next} time Edebug is invoked at a deeper command level.
+
+@ignore
+@defopt edebug-unwrap-results
+Non-@code{nil} if Edebug should unwrap results of expressions.  This is
+useful when debugging macros where the results of expressions are
+instrumented expressions.  But don't do this when results might be
+circular, or an infinite loop will result.  @xref{Debugging Backquote}.
+@end defopt
+@end ignore
+
+@defopt edebug-global-break-condition
+If non-@code{nil}, an expression to test for at every stop point.
+If the result is non-nil, then break.  Errors are ignored.
+@xref{Global Break Condition}.
+@end defopt
+