@c -*-texinfo-*-
@c This is part of the GNU Emacs Lisp Reference Manual.
-@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1998, 1999, 2005
-@c Free Software Foundation, Inc.
+@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1998, 1999, 2001, 2002, 2003,
+@c 2004, 2005, 2006, 2007 Free Software Foundation, Inc.
@c See the file elisp.texi for copying conditions.
@setfilename ../info/debugging
@node Debugging, Read and Print, Advising Functions, Top
@node Debugger
@section The Lisp Debugger
-@cindex debugger
+@cindex debugger for Emacs Lisp
@cindex Lisp debugger
@cindex break
@end defopt
@defopt eval-expression-debug-on-error
-If you set this variable to a non-@code{nil} value, then
-@code{debug-on-error} will be set to @code{t} when evaluating with the
+If this variable has a non-@code{nil} value, then
+@code{debug-on-error} is set to @code{t} when evaluating with the
command @code{eval-expression}. If
@code{eval-expression-debug-on-error} is @code{nil}, then the value of
@code{debug-on-error} is not changed. @xref{Lisp Eval,, Evaluating
function, and then step through its caller.
@deffn Command debug-on-entry function-name
-This function requests @var{function-name} to invoke the debugger each time
-it is called. It works by inserting the form @code{(debug 'debug)} into
-the function definition as the first form.
-
-Any function defined as Lisp code may be set to break on entry,
-regardless of whether it is interpreted code or compiled code. If the
-function is a command, it will enter the debugger when called from Lisp
-and when called interactively (after the reading of the arguments). You
-can't debug primitive functions (i.e., those written in C) this way.
+This function requests @var{function-name} to invoke the debugger each
+time it is called. It works by inserting the form
+@code{(implement-debug-on-entry)} into the function definition as the
+first form.
+
+Any function or macro defined as Lisp code may be set to break on
+entry, regardless of whether it is interpreted code or compiled code.
+If the function is a command, it will enter the debugger when called
+from Lisp and when called interactively (after the reading of the
+arguments). You can also set debug-on-entry for primitive functions
+(i.e., those written in C) this way, but it only takes effect when the
+primitive is called from Lisp code. Debug-on-entry is not allowed for
+special forms.
When @code{debug-on-entry} is called interactively, it prompts for
@var{function-name} in the minibuffer. If the function is already set
@end example
@end deffn
-@deffn Command cancel-debug-on-entry function-name
+@deffn Command cancel-debug-on-entry &optional function-name
This function undoes the effect of @code{debug-on-entry} on
@var{function-name}. When called interactively, it prompts for
@var{function-name} in the minibuffer. If @var{function-name} is
-@code{nil} or the empty string, it cancels break-on-entry for all
-functions.
-
+omitted or @code{nil}, it cancels break-on-entry for all functions.
Calling @code{cancel-debug-on-entry} does nothing to a function which is
-not currently set up to break on entry. It always returns
-@var{function-name}.
+not currently set up to break on entry.
@end deffn
@node Explicit Debug
byte-compiled function. If you would like to step through a
byte-compiled function, replace it with an interpreted definition of
the same function. (To do this, visit the source for the function and
-type @kbd{C-M-x} on its definition.)
+type @kbd{C-M-x} on its definition.) You cannot use the Lisp debugger
+to step through a primitive function.
Here is a list of Debugger mode commands:
@item j
Flag the current frame like @kbd{b}. Then continue execution like
@kbd{c}, but temporarily disable break-on-entry for all functions that
-are set up to do so by @code{debug-on-entry}. The temporarily disabled
-functions are set up to debug on entry again when the debugger is
-entered or when @code{debug-on-entry} is called;
-@code{cancel-debug-on-entry} also re-enables these functions before it
-disables any functions that its argument says it should disable.
+are set up to do so by @code{debug-on-entry}.
@item e
Read a Lisp expression in the minibuffer, evaluate it, and print the
buffer.
@item debug
-@code{debug} as first argument indicates a call to @code{debug}
-because of entry to a function that was set to debug on entry. The
-debugger displays @samp{Debugger entered--entering a function:}, just
-as in the @code{lambda} case. It also marks the stack frame for that
-function so that it will invoke the debugger when exited.
+@code{debug} as first argument means @code{debug} was called because
+of entry to a function that was set to debug on entry. The debugger
+displays the string @samp{Debugger entered--entering a function:},
+just as in the @code{lambda} case. It also marks the stack frame for
+that function so that it will invoke the debugger when exited.
@item t
When the first argument is @code{t}, this indicates a call to
-@code{debug} due to evaluation of a list form when
+@code{debug} due to evaluation of a function call form when
@code{debug-on-next-call} is non-@code{nil}. The debugger displays
@samp{Debugger entered--beginning evaluation of function call form:}
as the top line in the buffer.
@node Syntax Errors
@section Debugging Invalid Lisp Syntax
+@cindex debugging invalid Lisp syntax
The Lisp reader reports invalid syntax, but cannot say where the real
problem is. For example, the error ``End of file during parsing'' in
if it goes to the place where that defun appears to end. If it does
not, there is a problem in that defun.
+@cindex unbalanced parentheses
+@cindex parenthesis mismatch, debugging
However, unmatched parentheses are the most common syntax errors in
Lisp, and we can give further advice for those cases. (In addition,
just moving point through the code with Show Paren mode enabled might
never return. If it ever does return, you get a run-time error.
@end defmac
+ Edebug also has a coverage testing feature (@pxref{Coverage
+Testing}). These features partly duplicate each other, and it would
+be cleaner to combine them.
+
@node Compilation Errors
@section Debugging Problems in Compilation
+@cindex debugging byte compilation problems
When an error happens during byte compilation, it is normally due to
invalid syntax in the program you are compiling. The compiler prints a