Merge from emacs--devo--0

Patches applied:

 * emacs--devo--0  (patch 866-879)

   - Merge multi-tty branch
   - Update from CVS
   - Merge from emacs--rel--22

Revision: emacs@sv.gnu.org/emacs--unicode--0--patch-257

1 files changed, 1582 insertions, 0 deletions

diff --git a/doc/lispref/edebug.texi b/doc/lispref/edebug.texi
new file mode 100644
index 00000000000..4be030896c5
--- /dev/null
+++ b/doc/lispref/edebug.texi
@@ -0,0 +1,1582 @@
+@comment -*-texinfo-*-
+@c This is part of the GNU Emacs Lisp Reference Manual.
+@c Copyright (C) 1992, 1993, 1994, 1998, 1999, 2001, 2002, 2003, 2004,
+@c   2005, 2006, 2007  Free Software Foundation, Inc.
+@c See the file elisp.texi for copying conditions.
+
+@c This file can also be used by an independent Edebug User
+@c Manual 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, Syntax Errors, Debugger, Debugging
+@section Edebug
+@cindex Edebug debugging facility
+
+  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 re-evaluate 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.
+* 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.
+@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.  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}.
+
+@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 use periods to show the stop points 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, to invoke Edebug at the proper places.
+
+@kindex C-M-x
+@findex 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
+non-@code{nil}, 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
+@code{nil}.  The command @kbd{M-x edebug-all-defs} toggles the value
+of the variable @code{edebug-all-defs}.
+
+@findex eval-region @r{(Edebug)}
+@findex eval-buffer @r{(Edebug)}
+@findex eval-current-buffer @r{(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 values of
+@code{edebug-all-defs} 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,
+@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.
+
+  Edebug knows how to instrument all the standard special forms,
+@code{interactive} 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
+@code{nil}.  You can use this to load Edebug specifications
+associated with a package you are using, but only when you use Edebug.
+
+@findex 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
+@code{load}, 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.
+
+@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 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.
+
+@table @kbd
+@item S
+Stop: don't execute any more of the program, but 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{Jumping}.
+
+@item t
+Trace: pause (normally 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 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
+@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.  See also 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}.
+(@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.
+
+@defopt edebug-sit-for-seconds
+This option specifies how many seconds to wait between execution steps
+in trace mode.  The default is 1 second.
+@end defopt
+
+@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,
+as that 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 for 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 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
+@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.
+
+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.
+
+@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
+
+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}.
+
+@node Breaks
+@subsection 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.
+
+@menu
+* Breakpoints::                 Breakpoints at stop points.
+* Global Break Condition::	Breaking on an event.
+* Source Breakpoints::  	Embedding breakpoints in source code.
+@end menu
+
+@node Breakpoints
+@subsubsection Edebug Breakpoints
+
+@cindex 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:
+
+@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
+evaluating @var{condition} produces 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 current 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.
+
+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
+@dfn{temporary} 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.
+
+@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
+  The condition expression is stored in
+@code{edebug-global-break-condition}.  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.
+
+@node Source Breakpoints
+@subsubsection Source Breakpoints
+
+@findex edebug
+@cindex 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:
+
+@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 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}).
+
+@c 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.
+
+@node Edebug Views
+@subsection 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.
+
+@table @kbd
+@item v
+Switch to viewing the outside window configuration
+(@code{edebug-view-outside}).  Type @kbd{C-x X w} to return to Edebug.
+
+@item 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
+@var{n} seconds instead.
+
+@item 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.
+
+@item W
+@c 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.
+@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.
+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
+@kbd{C-x 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.
+
+@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 changes to data 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-: @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 C-j
+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 the 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{C-j} 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.  (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:
+
+@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, insert a new comment line, then type
+@kbd{C-c C-u}.  You need not insert dashes in the comment line---its
+contents don't matter.
+
+After selecting @samp{*edebug*}, you can return to the source code
+buffer with @kbd{C-c C-w}.  The @samp{*edebug*} buffer is killed when
+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.
+
+  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}.
+
+@defopt edebug-print-length
+If non-@code{nil}, Edebug binds @code{print-length} to this value while
+printing results.  The default value is @code{50}.
+@end defopt
+
+@defopt edebug-print-level
+If non-@code{nil}, Edebug binds @code{print-level} to this value while
+printing results.  The default value is @code{50}.
+@end defopt
+
+  You can also print circular structures and structures that share
+elements more informatively by binding @code{print-circle}
+to a non-@code{nil} value.
+
+  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 labeled
+structure.  This notation is used for any shared elements of lists or
+vectors.
+
+@defopt edebug-print-circle
+If non-@code{nil}, Edebug binds @code{print-circle} to this value while
+printing results.  The default value is @code{t}.
+@end defopt
+
+  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, storing it 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 consists of
+@samp{::::@{}, 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.
+
+@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, after the @samp{@{} or @samp{@}}.  All
+the arguments are evaluated, and @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 appends a newline to separate entries.
+@end 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.
+
+@node Coverage Testing
+@subsection Coverage Testing
+
+@cindex coverage testing (Edebug)
+@cindex frequency counts
+@cindex 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
+@code{edebug-test-coverage} is non-@code{nil}.  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.
+
+@kindex C-x X =
+@findex 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.
+
+@deffn 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}.
+@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      = =5
+  (if (< 0 n)
+;#5         =
+      (* n (fac (1- n)))
+;#    5               0
+    1))
+;#   0
+@end 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.
+
+
+@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.
+
+@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, it needs to save and restore certain data
+before even deciding whether to make trace information or stop the
+program.
+
+@itemize @bullet
+@item
+@code{max-lisp-eval-depth} and @code{max-specpdl-size} are both
+incremented once to reduce Edebug's impact on the stack.  You could,
+however, still run out of stack space when using Edebug.
+
+@item
+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 non-@code{nil}.
+@end itemize
+
+
+@node Edebug Display Update
+@subsubsection Edebug Display Update
+
+@c This paragraph is not filled, because LaLiberte's conversion script
+@c needs an xref to be on just one line.
+When Edebug needs to display something (e.g., in trace mode), it saves
+the current window configuration from ``outside'' Edebug
+(@pxref{Window Configurations}).  When you exit Edebug (by continuing
+the program), it restores the previous window configuration.
+
+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).
+
+@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 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
+@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
+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
+The variables @code{last-command}, @code{this-command},
+@code{last-command-char}, @code{last-input-char},
+@code{last-input-event}, @code{last-command-event},
+@code{last-event-frame}, @code{last-nonmenu-event}, and
+@code{track-mouse}.  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
+@code{unread-command-events}.  Entering Edebug while this variable has a
+nontrivial value can interfere with execution of the program you are
+debugging.
+
+@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 Edebug and Macros
+@subsection Edebug and Macros
+
+To make Edebug properly instrument expressions that call macros, some
+extra care is needed.  This subsection explains the details.
+
+@menu
+* Instrumenting Macro Calls::   The basic problem.
+* Specification List::		How to specify complex patterns of evaluation.
+* Backtracking::		What Edebug does when matching fails.
+* Specification Examples::	To help understand specifications.
+@end menu
+
+@node Instrumenting Macro Calls
+@subsubsection 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}).
+
+@smallexample
+(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)))
+  ...)
+@end smallexample
+
+  The Edebug specification says which parts of a call to the macro are
+forms to be evaluated.  For simple macros, the @var{specification}
+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
+@code{debug} declarations is preferred, and more convenient, for macro
+definitions in Lisp, but @code{def-edebug-spec} makes it possible to
+define Edebug specifications for special forms implemented in C.
+
+@deffn Macro def-edebug-spec macro specification
+Specify which expressions of a call to macro @var{macro} are forms to be
+evaluated.  @var{specification} should be the edebug specification.
+Neither argument is evaluated.
+
+The @var{macro} argument can actually be any symbol, not just a macro
+name.
+@end deffn
+
+Here is a table of the possibilities for @var{specification} and how each
+directs processing of arguments.
+
+@table @asis
+@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 from 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
+
+@vindex edebug-eval-macro-args
+If a macro has no Edebug specification, neither through a @code{debug}
+declaration nor through a @code{def-edebug-spec} call, the variable
+@code{edebug-eval-macro-args} comes into play.  If it is @code{nil},
+the default, none of the arguments is instrumented for evaluation.
+If it is non-@code{nil}, all arguments are instrumented.
+
+@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 apply only to the remainder of the
+sublist or group they are contained in.
+
+When a specification list involves alternatives or repetition, matching
+it against an actual macro call may require backtracking.
+@xref{Backtracking}, for more details.
+
+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):
+
+@table @code
+@item sexp
+A single unevaluated Lisp object, which is not instrumented.
+@c an "expression" is not necessarily intended for evaluation.
+
+@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
+@c @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.
+
+@item &rest
+@c @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 @var{specs}@dots{}]}.
+To specify several elements that must all match on every repetition, use
+@code{&rest [@var{specs}@dots{}]}.
+
+@item &or
+@c @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
+@c @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
+@c @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.
+
+@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.
+
+@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.
+
+@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.
+
+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.
+
+Some suitable predicates include @code{symbolp}, @code{integerp},
+@code{stringp}, @code{vectorp}, and @code{atom}.
+
+@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.
+
+@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.
+
+@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.  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 .
+(sublist-elements@dots{}))} is equivalent to @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 appear only after
+@code{&define}.  See the @code{defun} example.
+
+@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{&})
+are not allowed.
+
+@item lambda-list
+@cindex lambda-list (Edebug)
+This matches a lambda list---the argument list of a lambda expression.
+
+@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.
+@end table
+
+@node Backtracking
+@subsubsection Backtracking in Specifications
+
+@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.
+
+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
+@code{&optional}, @code{&rest}, or @code{&or}, or at the start of
+processing a sublist, group, or indirect specification.  The effect of
+enabling or disabling backtracking is limited to the remainder of the
+level currently being processed and lower levels.
+
+Backtracking is disabled while matching any of the
+form specifications (that is, @code{form}, @code{body}, @code{def-form}, and
+@code{def-body}).  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.,
+@code{["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.
+
+@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 expression.  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 is actually evaluated outside of the
+function body.
+
+@smallexample
+(def-edebug-spec defmacro defun) ; @r{Indirect ref to @code{defun} spec.}
+(def-edebug-spec defun
+  (&define name lambda-list
+           [&optional stringp]   ; @r{Match the doc string, if present.}
+           [&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 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.)
+
+@smallexample
+(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))
+@end smallexample
+
+
+@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}, @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}.
+@end defopt
+
+@defopt edebug-all-forms
+If this is non-@code{nil}, the commands @code{eval-defun},
+@code{eval-region}, @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}.
+@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 this is non-@code{nil}, 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}.
+@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
+If this is non-@code{nil}, 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}.
+@end defopt
+
+@defopt edebug-test-coverage
+If non-@code{nil}, Edebug tests coverage of all expressions debugged.
+@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-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 via a new command.
+@c Not necessarily a deeper command level.
+@c A new command is not precisely true, but that is close enough -- dan
+
+@defopt edebug-global-break-condition
+If non-@code{nil}, an expression to test for at every stop point.  If
+the result is non-@code{nil}, then break.  Errors are ignored.
+@xref{Global Break Condition}.
+@end defopt
+
+@ignore
+   arch-tag: 74842db8-019f-4818-b5a4-b2de878e57fd
+@end ignore