--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/man/lispref/debugging.texi	Mon Aug 13 08:45:50 2007 +0200
@@ -0,0 +1,741 @@
+@c -*-texinfo-*-
+@c This is part of the XEmacs Lisp Reference Manual.
+@c Copyright (C) 1990, 1991, 1992, 1993, 1994 Free Software Foundation, Inc. 
+@c See the file lispref.texi for copying conditions.
+@setfilename ../../info/debugging.info
+@node Debugging, Read and Print, Byte Compilation, Top
+@chapter Debugging Lisp Programs
+
+  There are three ways to investigate a problem in an XEmacs Lisp program,
+depending on what you are doing with the program when the problem appears.
+
+@itemize @bullet
+@item
+If the problem occurs when you run the program, you can use a Lisp
+debugger (either the default debugger or Edebug) to investigate what is
+happening during execution.
+
+@item
+If the problem is syntactic, so that Lisp cannot even read the program,
+you can use the XEmacs facilities for editing Lisp to localize it.
+
+@item
+If the problem occurs when trying to compile the program with the byte
+compiler, you need to know how to examine the compiler's input buffer.
+@end itemize
+
+@menu
+* Debugger::            How the XEmacs Lisp debugger is implemented.
+* Syntax Errors::       How to find syntax errors.
+* Compilation Errors::  How to find errors that show up in byte compilation.
+* Edebug::		A source-level XEmacs Lisp debugger.
+@end menu
+
+  Another useful debugging tool is the dribble file.  When a dribble
+file is open, XEmacs copies all keyboard input characters to that file.
+Afterward, you can examine the file to find out what input was used.
+@xref{Terminal Input}.
+
+  For debugging problems in terminal descriptions, the
+@code{open-termscript} function can be useful.  @xref{Terminal Output}.
+
+@node Debugger
+@section The Lisp Debugger
+@cindex debugger
+@cindex Lisp debugger
+@cindex break
+
+  The @dfn{Lisp debugger} provides the ability to suspend evaluation of
+a form.  While evaluation is suspended (a state that is commonly known
+as a @dfn{break}), you may examine the run time stack, examine the
+values of local or global variables, or change those values.  Since a
+break is a recursive edit, all the usual editing facilities of XEmacs are
+available; you can even run programs that will enter the debugger
+recursively.  @xref{Recursive Editing}.
+
+@menu
+* Error Debugging::       Entering the debugger when an error happens.
+* Infinite Loops::	  Stopping and debugging a program that doesn't exit.
+* Function Debugging::    Entering it when a certain function is called.
+* Explicit Debug::        Entering it at a certain point in the program.
+* Using Debugger::        What the debugger does; what you see while in it.
+* Debugger Commands::     Commands used while in the debugger.
+* Invoking the Debugger:: How to call the function @code{debug}.
+* Internals of Debugger:: Subroutines of the debugger, and global variables.
+@end menu
+
+@node Error Debugging
+@subsection Entering the Debugger on an Error
+@cindex error debugging
+@cindex debugging errors
+
+  The most important time to enter the debugger is when a Lisp error
+happens.  This allows you to investigate the immediate causes of the
+error.
+
+  However, entry to the debugger is not a normal consequence of an
+error.  Many commands frequently get Lisp errors when invoked in
+inappropriate contexts (such as @kbd{C-f} at the end of the buffer) and
+during ordinary editing it would be very unpleasant to enter the
+debugger each time this happens.  If you want errors to enter the
+debugger, set the variable @code{debug-on-error} to non-@code{nil}.
+
+@defopt debug-on-error
+This variable determines whether the debugger is called when an error is
+signaled and not handled.  If @code{debug-on-error} is @code{t}, all
+errors call the debugger.  If it is @code{nil}, none call the debugger.
+
+The value can also be a list of error conditions that should call the
+debugger.  For example, if you set it to the list
+@code{(void-variable)}, then only errors about a variable that has no
+value invoke the debugger.
+
+When this variable is non-@code{nil}, Emacs does not catch errors that
+happen in process filter functions and sentinels.  Therefore, these
+errors also can invoke the debugger.  @xref{Processes}.
+@end defopt
+
+  To debug an error that happens during loading of the @file{.emacs}
+file, use the option @samp{-debug-init}, which binds
+@code{debug-on-error} to @code{t} while @file{.emacs} is loaded and
+inhibits use of @code{condition-case} to catch init file errors.
+
+  If your @file{.emacs} file sets @code{debug-on-error}, the effect may
+not last past the end of loading @file{.emacs}.  (This is an undesirable
+byproduct of the code that implements the @samp{-debug-init} command
+line option.)  The best way to make @file{.emacs} set
+@code{debug-on-error} permanently is with @code{after-init-hook}, like
+this:
+
+@example
+(add-hook 'after-init-hook
+          '(lambda () (setq debug-on-error t)))
+@end example
+
+@defopt debug-on-signal
+This variable is similar to @code{debug-on-error} but breaks
+whenever an error is signalled, regardless of whether it would be
+handled.
+@end defopt
+
+@node Infinite Loops
+@subsection Debugging Infinite Loops
+@cindex infinite loops
+@cindex loops, infinite
+@cindex quitting from infinite loop
+@cindex stopping an infinite loop
+
+  When a program loops infinitely and fails to return, your first
+problem is to stop the loop.  On most operating systems, you can do this
+with @kbd{C-g}, which causes quit.
+
+  Ordinary quitting gives no information about why the program was
+looping.  To get more information, you can set the variable
+@code{debug-on-quit} to non-@code{nil}.  Quitting with @kbd{C-g} is not
+considered an error, and @code{debug-on-error} has no effect on the
+handling of @kbd{C-g}.  Likewise, @code{debug-on-quit} has no effect on
+errors.
+
+  Once you have the debugger running in the middle of the infinite loop,
+you can proceed from the debugger using the stepping commands.  If you
+step through the entire loop, you will probably get enough information
+to solve the problem.
+
+@defopt debug-on-quit
+This variable determines whether the debugger is called when @code{quit}
+is signaled and not handled.  If @code{debug-on-quit} is non-@code{nil},
+then the debugger is called whenever you quit (that is, type @kbd{C-g}).
+If @code{debug-on-quit} is @code{nil}, then the debugger is not called
+when you quit.  @xref{Quitting}.
+@end defopt
+
+@node Function Debugging
+@subsection Entering the Debugger on a Function Call
+@cindex function call debugging
+@cindex debugging specific functions
+
+  To investigate a problem that happens in the middle of a program, one
+useful technique is to enter the debugger whenever a certain function is
+called.  You can do this to the function in which the problem occurs,
+and then step through the function, or you can do this to a function
+called shortly before the problem, step quickly over the call to that
+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.
+
+  When @code{debug-on-entry} is called interactively, it prompts
+for @var{function-name} in the minibuffer.
+
+  If the function is already set up to invoke the debugger on entry,
+@code{debug-on-entry} does nothing.
+
+  @strong{Note:} if you redefine a function after using
+@code{debug-on-entry} on it, the code to enter the debugger is lost.
+
+  @code{debug-on-entry} returns @var{function-name}.
+
+@example
+@group
+(defun fact (n)
+  (if (zerop n) 1
+      (* n (fact (1- n)))))
+     @result{} fact
+@end group
+@group
+(debug-on-entry 'fact)
+     @result{} fact
+@end group
+@group
+(fact 3)
+@end group
+
+@group
+------ Buffer: *Backtrace* ------
+Entering:
+* fact(3)
+  eval-region(4870 4878 t)
+  byte-code("...")
+  eval-last-sexp(nil)
+  (let ...)
+  eval-insert-last-sexp(nil)
+* call-interactively(eval-insert-last-sexp)
+------ Buffer: *Backtrace* ------
+@end group
+
+@group
+(symbol-function 'fact)
+     @result{} (lambda (n)
+          (debug (quote debug))
+          (if (zerop n) 1 (* n (fact (1- n)))))
+@end group
+@end example
+@end deffn
+
+@deffn Command cancel-debug-on-entry 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 debugging for all functions.
+
+If @code{cancel-debug-on-entry} is called more than once on the same
+function, the second call does nothing.  @code{cancel-debug-on-entry}
+returns @var{function-name}.
+@end deffn
+
+@node Explicit Debug
+@subsection Explicit Entry to the Debugger
+
+  You can cause the debugger to be called at a certain point in your
+program by writing the expression @code{(debug)} at that point.  To do
+this, visit the source file, insert the text @samp{(debug)} at the
+proper place, and type @kbd{C-M-x}.  Be sure to undo this insertion
+before you save the file!
+
+  The place where you insert @samp{(debug)} must be a place where an
+additional form can be evaluated and its value ignored.  (If the value
+of @code{(debug)} isn't ignored, it will alter the execution of the
+program!)  The most common suitable places are inside a @code{progn} or
+an implicit @code{progn} (@pxref{Sequencing}).
+
+@node Using Debugger
+@subsection Using the Debugger
+
+  When the debugger is entered, it displays the previously selected
+buffer in one window and a buffer named @samp{*Backtrace*} in another
+window.  The backtrace buffer contains one line for each level of Lisp
+function execution currently going on.  At the beginning of this buffer
+is a message describing the reason that the debugger was invoked (such
+as the error message and associated data, if it was invoked due to an
+error).
+
+  The backtrace buffer is read-only and uses a special major mode,
+Debugger mode, in which letters are defined as debugger commands.  The
+usual XEmacs editing commands are available; thus, you can switch windows
+to examine the buffer that was being edited at the time of the error,
+switch buffers, visit files, or do any other sort of editing.  However,
+the debugger is a recursive editing level (@pxref{Recursive Editing})
+and it is wise to go back to the backtrace buffer and exit the debugger
+(with the @kbd{q} command) when you are finished with it.  Exiting
+the debugger gets out of the recursive edit and kills the backtrace
+buffer.
+
+@cindex current stack frame
+  The backtrace buffer shows you the functions that are executing and
+their argument values.  It also allows you to specify a stack frame by
+moving point to the line describing that frame.  (A stack frame is the
+place where the Lisp interpreter records information about a particular
+invocation of a function.)  The frame whose line point is on is
+considered the @dfn{current frame}.  Some of the debugger commands
+operate on the current frame.
+
+  The debugger itself must be run byte-compiled, since it makes
+assumptions about how many stack frames are used for the debugger
+itself.  These assumptions are false if the debugger is running
+interpreted.
+
+@need 3000
+
+@node Debugger Commands
+@subsection Debugger Commands
+@cindex debugger command list
+
+  Inside the debugger (in Debugger mode), these special commands are
+available in addition to the usual cursor motion commands.  (Keep in
+mind that all the usual facilities of XEmacs, such as switching windows
+or buffers, are still available.)
+
+  The most important use of debugger commands is for stepping through
+code, so that you can see how control flows.  The debugger can step
+through the control structures of an interpreted function, but cannot do
+so in a 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 file for the function and
+type @kbd{C-M-x} on its definition.)
+
+  Here is a list of Debugger mode commands:
+
+@table @kbd
+@item c
+Exit the debugger and continue execution.  This resumes execution of the
+program as if the debugger had never been entered (aside from the
+effect of any variables or data structures you may have changed while
+inside the debugger).
+
+Continuing when an error or quit was signalled will cause the normal
+action of the signalling to take place.  If you do not want this to
+happen, but instead want the program execution to continue as if
+the call to @code{signal} did not occur, use the @kbd{r} command.
+
+@item d
+Continue execution, but enter the debugger the next time any Lisp
+function is called.  This allows you to step through the
+subexpressions of an expression, seeing what values the subexpressions
+compute, and what else they do.
+
+The stack frame made for the function call which enters the debugger in
+this way will be flagged automatically so that the debugger will be
+called again when the frame is exited.  You can use the @kbd{u} command
+to cancel this flag.
+
+@item b
+Flag the current frame so that the debugger will be entered when the
+frame is exited.  Frames flagged in this way are marked with stars
+in the backtrace buffer.
+
+@item u
+Don't enter the debugger when the current frame is exited.  This
+cancels a @kbd{b} command on that frame.
+
+@item e
+Read a Lisp expression in the minibuffer, evaluate it, and print the
+value in the echo area.  The debugger alters certain important
+variables, and the current buffer, as part of its operation; @kbd{e}
+temporarily restores their outside-the-debugger values so you can
+examine them.  This makes the debugger more transparent.  By contrast,
+@kbd{M-:} does nothing special in the debugger; it shows you the
+variable values within the debugger.
+
+@item q
+Terminate the program being debugged; return to top-level XEmacs
+command execution.
+
+If the debugger was entered due to a @kbd{C-g} but you really want
+to quit, and not debug, use the @kbd{q} command.
+
+@item r
+Return a value from the debugger.  The value is computed by reading an
+expression with the minibuffer and evaluating it.
+
+The @kbd{r} command is useful when the debugger was invoked due to exit
+from a Lisp call frame (as requested with @kbd{b}); then the value
+specified in the @kbd{r} command is used as the value of that frame.  It
+is also useful if you call @code{debug} and use its return value.
+
+If the debugger was entered at the beginning of a function call, @kbd{r}
+has the same effect as @kbd{c}, and the specified return value does not
+matter.
+
+If the debugger was entered through a call to @code{signal} (i.e. as a
+result of an error or quit), then returning a value will cause the
+call to @code{signal} itself to return, rather than throwing to
+top-level or invoking a handler, as is normal.  This allows you to
+correct an error (e.g. the type of an argument was wrong) or continue
+from a @code{debug-on-quit} as if it never happened.
+
+Note that some errors (e.g. any error signalled using the @code{error}
+function, and many errors signalled from a primitive function) are not
+continuable.  If you return a value from them and continue execution,
+then the error will immediately be signalled again.  Other errors
+(e.g. wrong-type-argument errors) will be continually resignalled
+until the problem is corrected.
+@end table
+
+@node Invoking the Debugger
+@subsection Invoking the Debugger
+
+  Here we describe fully the function used to invoke the debugger.
+
+@defun debug &rest debugger-args
+This function enters the debugger.  It switches buffers to a buffer
+named @samp{*Backtrace*} (or @samp{*Backtrace*<2>} if it is the second
+recursive entry to the debugger, etc.), and fills it with information
+about the stack of Lisp function calls.  It then enters a recursive
+edit, showing the backtrace buffer in Debugger mode.
+
+The Debugger mode @kbd{c} and @kbd{r} commands exit the recursive edit;
+then @code{debug} switches back to the previous buffer and returns to
+whatever called @code{debug}.  This is the only way the function
+@code{debug} can return to its caller.
+
+If the first of the @var{debugger-args} passed to @code{debug} is
+@code{nil} (or if it is not one of the special values in the table
+below), then @code{debug} displays the rest of its arguments at the
+top of the @samp{*Backtrace*} buffer.  This mechanism is used to display
+a message to the user.
+
+However, if the first argument passed to @code{debug} is one of the
+following special values, then it has special significance.  Normally,
+these values are passed to @code{debug} only by the internals of XEmacs
+and the debugger, and not by programmers calling @code{debug}.
+
+The special values are:
+
+@table @code
+@item lambda
+@cindex @code{lambda} in debug
+A first argument of @code{lambda} means @code{debug} was called because
+of entry to a function when @code{debug-on-next-call} was
+non-@code{nil}.  The debugger displays @samp{Entering:} as a line of
+text at the top of 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{Entering:}, 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-on-next-call} is non-@code{nil}.  The debugger displays the
+following as the top line in the buffer:
+
+@smallexample
+Beginning evaluation of function call form:
+@end smallexample
+
+@item exit
+When the first argument is @code{exit}, it indicates the exit of a
+stack frame previously marked to invoke the debugger on exit.  The
+second argument given to @code{debug} in this case is the value being
+returned from the frame.  The debugger displays @samp{Return value:} on
+the top line of the buffer, followed by the value being returned.
+
+@item error
+@cindex @code{error} in debug
+When the first argument is @code{error}, the debugger indicates that
+it is being entered because an error or @code{quit} was signaled and not
+handled, by displaying @samp{Signaling:} followed by the error signaled
+and any arguments to @code{signal}.  For example,
+
+@example
+@group
+(let ((debug-on-error t))
+  (/ 1 0))
+@end group
+
+@group
+------ Buffer: *Backtrace* ------
+Signaling: (arith-error)
+  /(1 0)
+...
+------ Buffer: *Backtrace* ------
+@end group
+@end example
+
+If an error was signaled, presumably the variable
+@code{debug-on-error} is non-@code{nil}.  If @code{quit} was signaled,
+then presumably the variable @code{debug-on-quit} is non-@code{nil}.
+
+@item nil
+Use @code{nil} as the first of the @var{debugger-args} when you want
+to enter the debugger explicitly.  The rest of the @var{debugger-args}
+are printed on the top line of the buffer.  You can use this feature to
+display messages---for example, to remind yourself of the conditions
+under which @code{debug} is called.
+@end table
+@end defun
+
+@need 5000
+
+@node Internals of Debugger
+@subsection Internals of the Debugger
+
+  This section describes functions and variables used internally by the
+debugger.
+
+@defvar debugger
+The value of this variable is the function to call to invoke the
+debugger.  Its value must be a function of any number of arguments (or,
+more typically, the name of a function).  Presumably this function will
+enter some kind of debugger.  The default value of the variable is
+@code{debug}.
+
+The first argument that Lisp hands to the function indicates why it
+was called.  The convention for arguments is detailed in the description
+of @code{debug}.
+@end defvar
+
+@deffn Command backtrace &optional stream detailed
+@cindex run time stack
+@cindex call stack
+This function prints a trace of Lisp function calls currently active.
+This is the function used by @code{debug} to fill up the
+@samp{*Backtrace*} buffer.  It is written in C, since it must have access
+to the stack to determine which function calls are active.  The return
+value is always @code{nil}.
+
+The backtrace is normally printed to @code{standard-output}, but this
+can be changed by specifying a value for @var{stream}.  If
+@var{detailed} is non-@code{nil}, the backtrace also shows places where
+currently active variable bindings, catches, condition-cases, and
+unwind-protects were made as well as function calls.
+
+In the following example, a Lisp expression calls @code{backtrace}
+explicitly.  This prints the backtrace to the stream
+@code{standard-output}: in this case, to the buffer
+@samp{backtrace-output}.  Each line of the backtrace represents one
+function call.  The line shows the values of the function's arguments if
+they are all known.  If they are still being computed, the line says so.
+The arguments of special forms are elided.
+
+@smallexample
+@group
+(with-output-to-temp-buffer "backtrace-output"
+  (let ((var 1))
+    (save-excursion
+      (setq var (eval '(progn
+                         (1+ var)
+                         (list 'testing (backtrace))))))))
+
+     @result{} nil
+@end group
+
+@group
+----------- Buffer: backtrace-output ------------
+  backtrace()
+  (list ...computing arguments...)
+  (progn ...)
+  eval((progn (1+ var) (list (quote testing) (backtrace))))
+  (setq ...)
+  (save-excursion ...)
+  (let ...)
+  (with-output-to-temp-buffer ...)
+  eval-region(1973 2142 #<buffer *scratch*>)
+  byte-code("...  for eval-print-last-sexp ...")
+  eval-print-last-sexp(nil)
+* call-interactively(eval-print-last-sexp)
+----------- Buffer: backtrace-output ------------
+@end group
+@end smallexample
+
+The character @samp{*} indicates a frame whose debug-on-exit flag is
+set.
+@end deffn
+
+@ignore @c Not worth mentioning
+@defopt stack-trace-on-error
+@cindex stack trace
+This variable controls whether Lisp automatically displays a
+backtrace buffer after every error that is not handled.  A quit signal
+counts as an error for this variable.  If it is non-@code{nil} then a
+backtrace is shown in a pop-up buffer named @samp{*Backtrace*} on every
+error.  If it is @code{nil}, then a backtrace is not shown.
+
+When a backtrace is shown, that buffer is not selected.  If either
+@code{debug-on-quit} or @code{debug-on-error} is also non-@code{nil}, then
+a backtrace is shown in one buffer, and the debugger is popped up in
+another buffer with its own backtrace.
+
+We consider this feature to be obsolete and superseded by the debugger
+itself.
+@end defopt
+@end ignore
+
+@defvar debug-on-next-call
+@cindex @code{eval}, and debugging
+@cindex @code{apply}, and debugging
+@cindex @code{funcall}, and debugging
+If this variable is non-@code{nil}, it says to call the debugger before
+the next @code{eval}, @code{apply} or @code{funcall}.  Entering the
+debugger sets @code{debug-on-next-call} to @code{nil}.
+
+The @kbd{d} command in the debugger works by setting this variable.
+@end defvar
+
+@defun backtrace-debug level flag
+This function sets the debug-on-exit flag of the stack frame @var{level}
+levels down the stack, giving it the value @var{flag}.  If @var{flag} is
+non-@code{nil}, this will cause the debugger to be entered when that
+frame later exits.  Even a nonlocal exit through that frame will enter
+the debugger.
+
+This function is used only by the debugger.
+@end defun
+
+@defvar command-debug-status
+This variable records the debugging status of the current interactive
+command.  Each time a command is called interactively, this variable is
+bound to @code{nil}.  The debugger can set this variable to leave
+information for future debugger invocations during the same command.
+
+The advantage, for the debugger, of using this variable rather than
+another global variable is that the data will never carry over to a
+subsequent command invocation.
+@end defvar
+
+@defun backtrace-frame frame-number
+The function @code{backtrace-frame} is intended for use in Lisp
+debuggers.  It returns information about what computation is happening
+in the stack frame @var{frame-number} levels down.
+
+If that frame has not evaluated the arguments yet (or is a special
+form), the value is @code{(nil @var{function} @var{arg-forms}@dots{})}.
+
+If that frame has evaluated its arguments and called its function
+already, the value is @code{(t @var{function}
+@var{arg-values}@dots{})}.
+
+In the return value, @var{function} is whatever was supplied as the
+@sc{car} of the evaluated list, or a @code{lambda} expression in the
+case of a macro call.  If the function has a @code{&rest} argument, that
+is represented as the tail of the list @var{arg-values}.
+
+If @var{frame-number} is out of range, @code{backtrace-frame} returns
+@code{nil}.
+@end defun
+
+@node Syntax Errors
+@section 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
+evaluating an expression indicates an excess of open parentheses (or
+square brackets).  The reader detects this imbalance at the end of the
+file, but it cannot figure out where the close parenthesis should have
+been.  Likewise, ``Invalid read syntax: ")"'' indicates an excess close
+parenthesis or missing open parenthesis, but does not say where the
+missing parenthesis belongs.  How, then, to find what to change?
+
+  If the problem is not simply an imbalance of parentheses, a useful
+technique is to try @kbd{C-M-e} at the beginning of each defun, and see
+if it goes to the place where that defun appears to end.  If it does
+not, there is a problem in that defun.
+
+  However, unmatched parentheses are the most common syntax errors in
+Lisp, and we can give further advice for those cases.
+
+@menu
+* Excess Open::     How to find a spurious open paren or missing close.
+* Excess Close::    How to find a spurious close paren or missing open.
+@end menu
+
+@node Excess Open
+@subsection Excess Open Parentheses
+
+  The first step is to find the defun that is unbalanced.  If there is
+an excess open parenthesis, the way to do this is to insert a
+close parenthesis at the end of the file and type @kbd{C-M-b}
+(@code{backward-sexp}).  This will move you to the beginning of the
+defun that is unbalanced.  (Then type @kbd{C-@key{SPC} C-_ C-u
+C-@key{SPC}} to set the mark there, undo the insertion of the
+close parenthesis, and finally return to the mark.)
+
+  The next step is to determine precisely what is wrong.  There is no
+way to be sure of this except to study the program, but often the
+existing indentation is a clue to where the parentheses should have
+been.  The easiest way to use this clue is to reindent with @kbd{C-M-q}
+and see what moves.
+
+  Before you do this, make sure the defun has enough close parentheses.
+Otherwise, @kbd{C-M-q} will get an error, or will reindent all the rest
+of the file until the end.  So move to the end of the defun and insert a
+close parenthesis there.  Don't use @kbd{C-M-e} to move there, since
+that too will fail to work until the defun is balanced.
+
+  Now you can go to the beginning of the defun and type @kbd{C-M-q}.
+Usually all the lines from a certain point to the end of the function
+will shift to the right.  There is probably a missing close parenthesis,
+or a superfluous open parenthesis, near that point.  (However, don't
+assume this is true; study the code to make sure.)  Once you have found
+the discrepancy, undo the @kbd{C-M-q} with @kbd{C-_}, since the old
+indentation is probably appropriate to the intended parentheses.
+
+  After you think you have fixed the problem, use @kbd{C-M-q} again.  If
+the old indentation actually fit the intended nesting of parentheses,
+and you have put back those parentheses, @kbd{C-M-q} should not change
+anything.
+
+@node Excess Close
+@subsection Excess Close Parentheses
+
+  To deal with an excess close parenthesis, first insert an open
+parenthesis at the beginning of the file, back up over it, and type
+@kbd{C-M-f} to find the end of the unbalanced defun.  (Then type
+@kbd{C-@key{SPC} C-_ C-u C-@key{SPC}} to set the mark there, undo the
+insertion of the open parenthesis, and finally return to the mark.)
+
+  Then find the actual matching close parenthesis by typing @kbd{C-M-f}
+at the beginning of the defun.  This will leave you somewhere short of
+the place where the defun ought to end.  It is possible that you will
+find a spurious close parenthesis in that vicinity.
+
+  If you don't see a problem at that point, the next thing to do is to
+type @kbd{C-M-q} at the beginning of the defun.  A range of lines will
+probably shift left; if so, the missing open parenthesis or spurious
+close parenthesis is probably near the first of those lines.  (However,
+don't assume this is true; study the code to make sure.)  Once you have
+found the discrepancy, undo the @kbd{C-M-q} with @kbd{C-_}, since the
+old indentation is probably appropriate to the intended parentheses.
+
+  After you think you have fixed the problem, use @kbd{C-M-q} again.  If
+the old indentation actually fit the intended nesting of parentheses,
+and you have put back those parentheses, @kbd{C-M-q} should not change
+anything.
+
+@node Compilation Errors, Edebug, Syntax Errors, Debugging
+@section Debugging Problems in Compilation
+
+  When an error happens during byte compilation, it is normally due to
+invalid syntax in the program you are compiling.  The compiler prints a
+suitable error message in the @samp{*Compile-Log*} buffer, and then
+stops.  The message may state a function name in which the error was
+found, or it may not.  Either way, here is how to find out where in the
+file the error occurred.
+
+  What you should do is switch to the buffer @w{@samp{ *Compiler Input*}}.
+(Note that the buffer name starts with a space, so it does not show
+up in @kbd{M-x list-buffers}.)  This buffer contains the program being
+compiled, and point shows how far the byte compiler was able to read.
+
+  If the error was due to invalid Lisp syntax, point shows exactly where
+the invalid syntax was @emph{detected}.  The cause of the error is not
+necessarily near by!  Use the techniques in the previous section to find
+the error.
+
+  If the error was detected while compiling a form that had been read
+successfully, then point is located at the end of the form.  In this
+case, this technique can't localize the error precisely, but can still
+show you which function to check.
+
+@include edebug-inc.texi