[Emacs-diffs] /srv/bzr/emacs/trunk r107239: Update Debugging chapter of Lisp manual.

[Chong Yidong]

------------------------------------------------------------
revno: 107239
committer: Chong Yidong <address@hidden>
branch nick: trunk
timestamp: Sat 2012-02-11 14:17:22 +0800
message:
  Update Debugging chapter of Lisp manual.
  
  * doc/emacs/debugging.texi (Debugging): Copyedits.  Describe testcover, ERT.
  (Error Debugging): Note that debug-ignored-errors overrides list
  values of debug-on-error too.  Add xref to Signaling Errors.  Note
  that debug-on-signal is not customizable.  Mention
  condition-case-unless-debug.
  (Compilation Errors): Node deleted.
  
  * doc/emacs/compile.texi (Compiler Errors): Move a paragraph here from
  deleted node Compilation Errors.
modified:
  doc/lispref/ChangeLog
  doc/lispref/compile.texi
  doc/lispref/debugging.texi
  doc/lispref/elisp.texi
  doc/lispref/vol1.texi
  doc/lispref/vol2.texi

=== modified file 'doc/lispref/ChangeLog'
--- a/doc/lispref/ChangeLog     2012-02-10 15:59:29 +0000
+++ b/doc/lispref/ChangeLog     2012-02-11 06:17:22 +0000
@@ -1,3 +1,15 @@
+2012-02-11  Chong Yidong  <address@hidden>
+
+       * debugging.texi (Debugging): Copyedits.  Describe testcover, ERT.
+       (Error Debugging): Note that debug-ignored-errors overrides list
+       values of debug-on-error too.  Add xref to Signaling Errors.  Note
+       that debug-on-signal is not customizable.  Mention
+       condition-case-unless-debug.
+       (Compilation Errors): Node deleted.
+
+       * compile.texi (Compiler Errors): Move a paragraph here from
+       deleted node Compilation Errors.
+
 2012-02-10  Leo Liu  <address@hidden>
 
        * control.texi (Handling Errors): Change condition-case-no-debug

=== modified file 'doc/lispref/compile.texi'
--- a/doc/lispref/compile.texi  2012-02-10 15:50:11 +0000
+++ b/doc/lispref/compile.texi  2012-02-11 06:17:22 +0000
@@ -445,13 +445,22 @@
   Byte compilation outputs all errors and warnings into the buffer
 @samp{*Compile-Log*}.  The messages include file names and line
 numbers that identify the location of the problem.  The usual Emacs
-commands for operating on compiler diagnostics work properly on
-these messages.
-
-  However, the warnings about functions that were used but not
-defined are always ``located'' at the end of the file, so these
-commands won't find the places they are really used.  To do that,
-you must search for the function names.
+commands for operating on compiler diagnostics work properly on these
+messages.
+
+  When an error is due to invalid syntax in the program, the byte
+compiler might get confused about the errors' exact location.  One way
+to investigate is to switch to the buffer @address@hidden Input*}}.
+(This buffer name starts with a space, so it does not show up in
address@hidden list-buffers}.)  This buffer contains the program being
+compiled, and point shows how far the byte compiler was able to read;
+the cause of the error might be nearby.  @xref{Syntax Errors}, for
+some tips for locating syntax errors.
+
+  When the byte compiler warns about functions that were used but not
+defined, it always reports the line number for the end of the file,
+not the locations where the missing functions were called.  To find
+the latter, you must search for the function names.
 
   You can suppress the compiler warning for calling an undefined
 function @var{func} by conditionalizing the function call on an

=== modified file 'doc/lispref/debugging.texi'
--- a/doc/lispref/debugging.texi        2012-02-05 03:37:19 +0000
+++ b/doc/lispref/debugging.texi        2012-02-11 06:17:22 +0000
@@ -6,41 +6,46 @@
 @node Debugging, Read and Print, Advising Functions, Top
 @chapter Debugging Lisp Programs
 
-  There are three ways to investigate a problem in an Emacs Lisp program,
-depending on what you are doing with the program when the problem appears.
+  There are several ways to find and investigate problems in an Emacs
+Lisp program.
 
 @itemize @bullet
 @item
-If the problem occurs when you run the program, you can use a Lisp
-debugger to investigate what is happening during execution.  In addition
-to the ordinary debugger, Emacs comes with a source-level debugger,
-Edebug.  This chapter describes both of them.
-
address@hidden
-If the problem is syntactic, so that Lisp cannot even read the program,
-you can use the Emacs facilities for editing Lisp to localize it.
-
address@hidden
-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.
+If a problem occurs when you run the program, you can use the built-in
+Emacs Lisp debugger to suspend the Lisp evaluator, and examine and/or
+alter its internal state.
+
address@hidden
+You can use Edebug, a source-level debugger for Emacs Lisp.
+
address@hidden
+If a syntactic problem is preventing Lisp from even reading the
+program, you can locate it using Lisp editing commands.
+
address@hidden
+You can look at the error and warning messages produced by the byte
+compiler when it compiles the program.  @xref{Compiler Errors}.
+
address@hidden
+You can use the Testcover package to perform coverage testing on the
+program.
+
address@hidden
+You can use the ERT package to write regression tests for the program.
address@hidden,the ERT manual,, ERT, ERT: Emacs Lisp Regression Testing}.
 @end itemize
 
+  Other useful tools for debugging input and output problems are the
+dribble file (@pxref{Terminal Input}) and the @code{open-termscript}
+function (@pxref{Terminal Output}).
+
 @menu
-* Debugger::            How the Emacs Lisp debugger is implemented.
+* Debugger::            A debugger for the Emacs Lisp evaluator.
 * Edebug::              A source-level Emacs Lisp debugger.
 * Syntax Errors::       How to find syntax errors.
 * Test Coverage::       Ensuring you have tested all branches in your code.
-* Compilation Errors::  How to find errors that show up in byte compilation.
 @end menu
 
-  Another useful debugging tool is the dribble file.  When a dribble
-file is open, Emacs copies all keyboard input characters to that file.
-Afterward, you can examine the file to find out what input was used.
address@hidden Input}.
-
-  For debugging problems in terminal descriptions, the
address@hidden function can be useful.  @xref{Terminal Output}.
-
 @node Debugger
 @section The Lisp Debugger
 @cindex debugger for Emacs Lisp
@@ -76,25 +81,29 @@
 error.
 
   However, entry to the debugger is not a normal consequence of an
-error.  Many commands frequently cause Lisp errors when invoked
-inappropriately, and during ordinary editing it would be very
-inconvenient to enter the debugger each time this happens.  So if you
-want errors to enter the debugger, set the variable
address@hidden to address@hidden  (The command
address@hidden provides an easy way to do this.)
+error.  Many commands signal Lisp errors when invoked inappropriately,
+and during ordinary editing it would be very inconvenient to enter the
+debugger each time this happens.  So if you want errors to enter the
+debugger, set the variable @code{debug-on-error} to address@hidden
+(The command @code{toggle-debug-on-error} provides an easy way to do
+this.)
 
 @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 kinds of errors call the debugger, except those listed in
 @code{debug-ignored-errors} (see below).  If it is @code{nil}, none
-call the debugger.  (Note that @code{eval-expression-debug-on-error}
-affects the setting of this variable in some cases; see below.)
-
-The value can also be a list of error conditions that should call the
-debugger.  For example, if you set it to the list
address@hidden(void-variable)}, then only errors about a variable that has no
-value invoke the debugger.
+call the debugger.
+
+The value can also be a list of error conditions (@pxref{Signaling
+Errors}).  Then the debugger is called only for error conditions in
+this list (except those also listed in @code{debug-ignored-errors}).
+For example, if you set @code{debug-on-error} to the list
address@hidden(void-variable)}, the debugger is only called for errors about a
+variable that has no value.
+
+Note that @code{eval-expression-debug-on-error} overrides this
+variable in some cases; see below.
 
 When this variable is address@hidden, Emacs does not create an error
 handler around process filter functions and sentinels.  Therefore,
@@ -102,51 +111,49 @@
 @end defopt
 
 @defopt debug-ignored-errors
-This variable specifies certain kinds of errors that should not enter
-the debugger.  Its value is a list of error condition symbols and/or
-regular expressions.  If the error has any of those condition symbols,
-or if the error message matches any of the regular expressions, then
-that error does not enter the debugger, regardless of the value of
address@hidden
+This variable specifies errors which should not enter the debugger,
+regardless of the value of @code{debug-on-error}.  Its value is a list
+of error condition symbols and/or regular expressions.  If the error
+has any of those condition symbols, or if the error message matches
+any of the regular expressions, then that error does not enter the
+debugger.
 
-The normal value of this variable lists several errors that happen often
-during editing but rarely result from bugs in Lisp programs.  However,
-``rarely'' is not ``never''; if your program fails with an error that
-matches this list, you will need to change this list in order to debug
+The normal value of this variable lists several errors that happen
+often during editing but rarely result from bugs in Lisp programs.
+However, ``rarely'' is not ``never''; if your program fails with an
+error that matches this list, you may try changing this list to debug
 the error.  The easiest way is usually to set
 @code{debug-ignored-errors} to @code{nil}.
 @end defopt
 
 @defopt eval-expression-debug-on-error
-If this variable has a address@hidden value, then
address@hidden is set to @code{t} when evaluating with the
-command @code{eval-expression}.  If
address@hidden is @code{nil}, then the value of
address@hidden is not changed.  @xref{Lisp Eval,, Evaluating
+If this variable has a address@hidden value (the default), running the
+command @code{eval-expression} causes @code{debug-on-error} to be
+temporarily bound to to @code{t}.  @xref{Lisp Eval,, Evaluating
 Emacs-Lisp Expressions, emacs, The GNU Emacs Manual}.
address@hidden defopt
-
address@hidden debug-on-signal
-Normally, errors that are caught by @code{condition-case} never run the
-debugger, even if @code{debug-on-error} is address@hidden  In other
-words, @code{condition-case} gets a chance to handle the error before
-the debugger gets a chance.
-
-If you set @code{debug-on-signal} to a address@hidden value, then the
-debugger gets the first chance at every error; an error will invoke the
-debugger regardless of any @code{condition-case}, if it fits the
-criteria specified by the values of @code{debug-on-error} and
address@hidden
-
address@hidden:} This variable is strong medicine!  Various parts of
-Emacs handle errors in the normal course of affairs, and you may not
-even realize that errors happen there.  If you set
address@hidden to a address@hidden value, those errors will
-enter the debugger.
-
address@hidden:} @code{debug-on-signal} has no effect when
address@hidden is @code{nil}.
address@hidden defopt
+
+If @code{eval-expression-debug-on-error} is @code{nil}, then the value
+of @code{debug-on-error} is not changed during @code{eval-expression}.
address@hidden defopt
+
address@hidden debug-on-signal
+Normally, errors caught by @code{condition-case} never invoke the
+debugger.  The @code{condition-case} gets a chance to handle the error
+before the debugger gets a chance.
+
+If you change @code{debug-on-signal} to a address@hidden value, the
+debugger gets the first chance at every error, regardless of the
+presence of @code{condition-case}.  (To invoke the debugger, the error
+must still fulfill the criteria specified by @code{debug-on-error} and
address@hidden)
+
address@hidden:} Setting this variable to address@hidden may have
+annoying effects.  Various parts of Emacs catch errors in the normal
+course of affairs, and you may not even realize that errors happen
+there.  If you need to debug code wrapped in @code{condition-case},
+consider using @code{condition-case-unless-debug} (@pxref{Handling
+Errors}).
address@hidden defvar
 
 @defopt debug-on-event
 If you set @code{debug-on-event} to a special event (@pxref{Special
@@ -171,27 +178,26 @@
 @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 a @dfn{quit}.
+problem is to stop the loop.  On most operating systems, you can do
+this with @kbd{C-g}, which causes a @dfn{quit}.  @xref{Quitting}.
 
   Ordinary quitting gives no information about why the program was
 looping.  To get more information, you can set the variable
address@hidden to address@hidden  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.
address@hidden to address@hidden  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 may get enough information to solve the problem.
 
-  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.
+  Quitting with @kbd{C-g} is not considered an error, and
address@hidden has no effect on the handling of @kbd{C-g}.
+Likewise, @code{debug-on-quit} has no effect on errors.
 
 @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 address@hidden,
-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}.
+This variable determines whether the debugger is called when
address@hidden is signaled and not handled.  If @code{debug-on-quit} is
address@hidden, then the debugger is called whenever you quit (that
+is, type @kbd{C-g}).  If @code{debug-on-quit} is @code{nil} (the
+default), then the debugger is not called when you quit.
 @end defopt
 
 @node Function Debugging
@@ -337,8 +343,8 @@
 for examining the return value of a function.
 
   If a function name is underlined, that means the debugger knows
-where its source code is located.  You can click @kbd{Mouse-2} on that
-name, or move to it and type @key{RET}, to visit the source code.
+where its source code is located.  You can click with the mouse on
+that name, or move to it and type @key{RET}, to visit the source code.
 
   The debugger itself must be run byte-compiled, since it makes
 assumptions about how many stack frames are used for the debugger
@@ -790,29 +796,3 @@
   Edebug also has a coverage testing feature (@pxref{Coverage
 Testing}).  These features partly duplicate each other, and it would
 be cleaner to combine them.
-
address@hidden Compilation Errors
address@hidden Debugging Problems in Compilation
address@hidden 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
-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 @address@hidden *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.

=== modified file 'doc/lispref/elisp.texi'
--- a/doc/lispref/elisp.texi    2012-02-10 15:50:11 +0000
+++ b/doc/lispref/elisp.texi    2012-02-11 06:17:22 +0000
@@ -552,12 +552,10 @@
 
 Debugging Lisp Programs
 
-* Debugger::                How the Emacs Lisp debugger is implemented.
+* Debugger::                A debugger for the Emacs Lisp evaluator.
 * Edebug::                  A source-level Emacs Lisp debugger.
 * Syntax Errors::           How to find syntax errors.
 * Test Coverage::           Ensuring you have tested all branches in your code.
-* Compilation Errors::      How to find errors that show up in
-                              byte compilation.
 
 The Lisp Debugger
 

=== modified file 'doc/lispref/vol1.texi'
--- a/doc/lispref/vol1.texi     2012-02-10 15:50:11 +0000
+++ b/doc/lispref/vol1.texi     2012-02-11 06:17:22 +0000
@@ -572,12 +572,10 @@
 
 Debugging Lisp Programs
 
-* Debugger::                How the Emacs Lisp debugger is implemented.
+* Debugger::                A debugger for the Emacs Lisp evaluator.
 * Edebug::                  A source-level Emacs Lisp debugger.
 * Syntax Errors::           How to find syntax errors.
 * Test Coverage::           Ensuring you have tested all branches in your code.
-* Compilation Errors::      How to find errors that show up in
-                              byte compilation.
 
 The Lisp Debugger
 

=== modified file 'doc/lispref/vol2.texi'
--- a/doc/lispref/vol2.texi     2012-02-10 15:50:11 +0000
+++ b/doc/lispref/vol2.texi     2012-02-11 06:17:22 +0000
@@ -571,12 +571,10 @@
 
 Debugging Lisp Programs
 
-* Debugger::                How the Emacs Lisp debugger is implemented.
+* Debugger::                A debugger for the Emacs Lisp evaluator.
 * Edebug::                  A source-level Emacs Lisp debugger.
 * Syntax Errors::           How to find syntax errors.
 * Test Coverage::           Ensuring you have tested all branches in your code.
-* Compilation Errors::      How to find errors that show up in
-                              byte compilation.
 
 The Lisp Debugger