lispref/debugging.texi patch.

lispref/debugging.texi patch.

[Lute Kamstra]

I've updated lispref/debugging.texi.  Shall I commit my changes?

Lute.


2005-02-28  Lute Kamstra  <lute@gnu.org>

	* debugging.texi (Debugging): Fix typo.
	(Error Debugging): Document eval-expression-debug-on-error.
	(Function Debugging): Update example.
	(Using Debugger): Mention starred stack frames.
	(Debugger Commands): Document `j' and `l'.
	(Invoking the Debugger): `d' and `j' exit recursive edit too.
	Update the messages that the debugger displays.
	(Internals of Debugger): Add cross reference.  Update example.
	(Excess Open): Minor improvement.
	(Excess Close): Minor improvement.


*** lispref/debugging.texi	16 Nov 2004 17:26:18 -0000	1.25
--- lispref/debugging.texi	28 Feb 2005 10:40:15 -0000
***************
*** 1,6 ****
  @c -*-texinfo-*-
  @c This is part of the GNU Emacs Lisp Reference Manual.
! @c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1998, 1999
  @c   Free Software Foundation, Inc.
  @c See the file elisp.texi for copying conditions.
  @setfilename ../info/debugging
--- 1,6 ----
  @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 See the file elisp.texi for copying conditions.
  @setfilename ../info/debugging
***************
*** 14,20 ****
  @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.
  
  @item
--- 14,20 ----
  @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.
  
  @item
***************
*** 117,122 ****
--- 117,131 ----
  @code{debug-ignored-errors} to @code{nil}.
  @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
+ 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
+ Emacs-Lisp Expressions, emacs, The GNU Emacs Manual}.
+ @end defopt
+ 
  @defopt debug-on-signal
  Normally, errors that are caught by @code{condition-case} never run the
  debugger, even if @code{debug-on-error} is non-@code{nil}.  In other
***************
*** 240,253 ****
  
  @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
  
--- 249,260 ----
  
  @group
  ------ Buffer: *Backtrace* ------
! Debugger entered--entering a function:
  * fact(3)
!   eval((fact 3))
!   eval-last-sexp-1(nil)
    eval-last-sexp(nil)
!   call-interactively(eval-last-sexp)
  ------ Buffer: *Backtrace* ------
  @end group
  
***************
*** 317,323 ****
  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.
  
    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
--- 324,332 ----
  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.  If a line starts with a star, that means
! that exiting that frame will call the debugger again.  This is useful
! 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
***************
*** 328,335 ****
  itself.  These assumptions are false if the debugger is running
  interpreted.
  
- @need 3000
- 
  @node Debugger Commands
  @subsection Debugger Commands
  @cindex debugger command list
--- 337,342 ----
***************
*** 378,383 ****
--- 385,399 ----
  cancels a @kbd{b} command on that frame.  The visible effect is to
  remove the star from the line in the backtrace buffer.
  
+ @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.
+ 
  @item e
  Read a Lisp expression in the minibuffer, evaluate it, and print the
  value in the echo area.  The debugger alters certain important
***************
*** 410,415 ****
--- 426,438 ----
  effect as @kbd{c}, and the specified return value does not matter.
  
  You can't use @kbd{r} when the debugger was entered due to an error.
+ 
+ @item l
+ Display a list of functions that will invoke the debugger when called.
+ This is a list of functions that are set to break on entry by means of
+ @code{debug-on-entry}.  @strong{Warning:} if you redefine such a
+ function and thus cancel the effect of @code{debug-on-entry}, it may
+ erroneously show up in this list.
  @end table
  
  @node Invoking the Debugger
***************
*** 425,434 ****
  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.
  
  The use of the @var{debugger-args} is that @code{debug} displays the
  rest of its arguments at the top of the @samp{*Backtrace*} buffer, so
--- 448,457 ----
  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}, @kbd{d}, @kbd{j}, 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.
  
  The use of the @var{debugger-args} is that @code{debug} displays the
  rest of its arguments at the top of the @samp{*Backtrace*} buffer, so
***************
*** 443,483 ****
  @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:} in 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
--- 466,506 ----
  @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{Debugger
! entered--entering a function:} 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{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-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.
  
  @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{Debugger
! entered--returning value:} in 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{Debugger entered--Lisp error:}
! followed by the error signaled and any arguments to @code{signal}.
! For example,
  
  @example
  @group
***************
*** 487,493 ****
  
  @group
  ------ Buffer: *Backtrace* ------
! Signaling: (arith-error)
    /(1 0)
  ...
  ------ Buffer: *Backtrace* ------
--- 510,516 ----
  
  @group
  ------ Buffer: *Backtrace* ------
! Debugger entered--Lisp error: (arith-error)
    /(1 0)
  ...
  ------ Buffer: *Backtrace* ------
***************
*** 522,528 ****
  
  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
--- 545,551 ----
  
  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} (@pxref{Invoking the Debugger}).
  @end defvar
  
  @deffn Command backtrace
***************
*** 567,583 ****
    (save-excursion ...)
    (let ...)
    (with-output-to-temp-buffer ...)
!   eval-region(1973 2142 #<buffer *scratch*>)
!   byte-code("...  for eval-print-last-sexp ...")
  @group
!   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
--- 590,603 ----
    (save-excursion ...)
    (let ...)
    (with-output-to-temp-buffer ...)
!   eval((with-output-to-temp-buffer ...))
!   eval-last-sexp-1(nil)
  @group
!   eval-last-sexp(nil)
!   call-interactively(eval-last-sexp)
  ----------- Buffer: backtrace-output ------------
  @end group
  @end smallexample
  @end deffn
  
  @ignore @c Not worth mentioning
***************
*** 687,694 ****
  
    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 go to the end of
! the file and type @kbd{C-u C-M-u}.  This will move you to the beginning
! of the defun that is unbalanced.
  
    The next step is to determine precisely what is wrong.  There is no
  way to be sure of this except by studying the program, but often the
--- 707,714 ----
  
    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 go to the end of
! the file and type @kbd{C-u C-M-u}.  This will move you to the
! beginning of the first defun that is unbalanced.
  
    The next step is to determine precisely what is wrong.  There is no
  way to be sure of this except by studying the program, but often the
***************
*** 719,727 ****
  @node Excess Close
  @subsection Excess Close Parentheses
  
!   To deal with an excess close parenthesis, first go to the beginning of
! the file, then type @kbd{C-u -1 C-M-u} to find the end of the unbalanced
! defun.
  
    Then find the actual matching close parenthesis by typing @kbd{C-M-f}
  at the beginning of that defun.  This will leave you somewhere short of
--- 739,747 ----
  @node Excess Close
  @subsection Excess Close Parentheses
  
!   To deal with an excess close parenthesis, first go to the beginning
! of the file, then type @kbd{C-u -1 C-M-u} to find the end of the first
! unbalanced defun.
  
    Then find the actual matching close parenthesis by typing @kbd{C-M-f}
  at the beginning of that defun.  This will leave you somewhere short of