debugging.texi

debugging.texi

[Luc Teirlinck]

I propose the following changes to debugging.texi.  The current doc of
eval-expression-debug-on-error gives the impression that the
default value is nil, whereas it is t.

I can install if desired.

===File ~/debugging.texi-diff===============================
*** debugging.texi	05 Mar 2005 12:12:17 -0600	1.29
--- debugging.texi	09 Jun 2005 16:49:10 -0500	
***************
*** 118,125 ****
  @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
--- 118,125 ----
  @end defopt
  
  @defopt eval-expression-debug-on-error
! 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
***************
*** 267,277 ****
  @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 break-on-entry for all
  functions.
  
  Calling @code{cancel-debug-on-entry} does nothing to a function which is
--- 267,277 ----
  @end example
  @end deffn
  
! @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
! omitted, @code{nil} or the empty string, it cancels break-on-entry for all
  functions.
  
  Calling @code{cancel-debug-on-entry} does nothing to a function which is
============================================================

Re: debugging.texi

[Richard Stallman]

      @var{function-name} in the minibuffer.  If @var{function-name} is
    ! omitted, @code{nil} or the empty string, it cancels break-on-entry for all

You need a comment after @code{nil} to eliminate a misreading.  With
that change, please install.

Re: debugging.texi

[Luc Teirlinck]

Richard Stallman wrote:

	 @var{function-name} in the minibuffer.  If @var{function-name} is
       ! omitted, @code{nil} or the empty string, it cancels break-on-entry for all

   You need a comment after @code{nil} to eliminate a misreading.  With
   that change, please install.

I assumed that you meant "comma" instead of "comment" and installed.
However, at closer look I believe that further changes are needed.

One reason is that the reference to the empty string in the above
could give the wrong impression that one can specify the name of a
function as a string.  The patch below reformulates things to make it
clear that the empty string is a special case, used for internal purposes.

More fundamentally, the description of the return value is inaccurate
if FUNCTION-NAME is nil.  I also propose some changes to the
docstrings in debug.el and a patch for those is included as well.

I can install the patches if desired.

===File ~/debugging.texi-diff===============================
*** debugging.texi	10 Jun 2005 20:55:09 -0500	1.30
--- debugging.texi	10 Jun 2005 21:40:18 -0500	
***************
*** 271,282 ****
  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
! omitted, @code{nil}, or the empty string, 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}.
  @end deffn
  
  @node Explicit Debug
--- 271,289 ----
  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
! 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.
! 
! If specified, @var{function-name} should normally be a symbol with a
! function definition or @code{nil}, but, for internal technical
! reasons, an empty string can be used as a substitute for @code{nil}.
! 
! If @var{function-name} is a non-@code{nil} symbol with a function
! definition, this command returns @var{function-name}, even if
! @var{function-name} was not previously set up to break on entry.  If
! @var{function-name} is omitted, @code{nil}, or an empty string, it
! returns a list of all functions for which break-on-entry was canceled.
  @end deffn
  
  @node Explicit Debug
============================================================

===File ~/debug.el-diff=====================================
*** debug.el	09 Jun 2005 10:33:14 -0500	1.83
--- debug.el	10 Jun 2005 22:14:23 -0500	
***************
*** 656,666 ****
  ;;;###autoload
  (defun debug-on-entry (function)
    "Request FUNCTION to invoke debugger each time it is called.
  If you tell the debugger to continue, FUNCTION's execution proceeds.
  This works by modifying the definition of FUNCTION,
  which must be written in Lisp, not predefined.
  Use \\[cancel-debug-on-entry] to cancel the effect of this command.
! Redefining FUNCTION also cancels it."
    (interactive "aDebug on entry (to function): ")
    (when (and (subrp (symbol-function function)) 
  	     (eq (cdr (subr-arity (symbol-function function))) 'unevalled))
--- 656,667 ----
  ;;;###autoload
  (defun debug-on-entry (function)
    "Request FUNCTION to invoke debugger each time it is called.
+ When called interactively, prompt for FUNCTION in the minibuffer.
  If you tell the debugger to continue, FUNCTION's execution proceeds.
  This works by modifying the definition of FUNCTION,
  which must be written in Lisp, not predefined.
  Use \\[cancel-debug-on-entry] to cancel the effect of this command.
! Redefining FUNCTION also cancels it.  This command returns FUNCTION."
    (interactive "aDebug on entry (to function): ")
    (when (and (subrp (symbol-function function)) 
  	     (eq (cdr (subr-arity (symbol-function function))) 'unevalled))
***************
*** 692,698 ****
  ;;;###autoload
  (defun cancel-debug-on-entry (&optional function)
    "Undo effect of \\[debug-on-entry] on FUNCTION.
! If argument is nil or an empty string, cancel for all functions."
    (interactive
     (list (let ((name
  		(completing-read "Cancel debug on entry (to function): "
--- 693,708 ----
  ;;;###autoload
  (defun cancel-debug-on-entry (&optional function)
    "Undo effect of \\[debug-on-entry] on FUNCTION.
! If argument is nil or an empty string, cancel for all functions.
! When called interactively, prompt for FUNCTION in the minibuffer.
! To specify a nil argument interactively, exit with an empty minibuffer.
! 
! If specified, FUNCTION must be a symbol with a function definition,
! nil, or an empty string.  If FUNCTION is a non-nil symbol with
! a function definition, the return value is FUNCTION, even if FUNCTION
! was not previously set up to break on entry.  If FUNCTION is omitted,
! nil, or an empty string the return value is a list of all functions
! for which break-on-entry was canceled."
    (interactive
     (list (let ((name
  		(completing-read "Cancel debug on entry (to function): "
============================================================

Re: debugging.texi

[Lute Kamstra]

Luc Teirlinck <teirllm@dms.auburn.edu> writes:

> Richard Stallman wrote:
>
> 	 @var{function-name} in the minibuffer.  If @var{function-name} is
>        ! omitted, @code{nil} or the empty string, it cancels break-on-entry for all
>
>    You need a comment after @code{nil} to eliminate a misreading.  With
>    that change, please install.
>
> I assumed that you meant "comma" instead of "comment" and installed.
> However, at closer look I believe that further changes are needed.
>
> One reason is that the reference to the empty string in the above
> could give the wrong impression that one can specify the name of a
> function as a string.  The patch below reformulates things to make it
> clear that the empty string is a special case, used for internal purposes.

I think the empty string argument is a kludge.  Maybe we should just
not document it and tell people to use a symbol or nil from lisp and
the name of the function or no name (i.e., the empty string)
interactively.  Then we could fix the function in the future by not
letting it accept the empty string as an argument.

I like your patch for the docstring of debug-on-entry and I agree with
you that the docstring of cancel-debug-on-entry should be elaborated.

Lute.

Re: debugging.texi

[Richard Stallman]

    I think the empty string argument is a kludge.  Maybe we should just
    not document it and tell people to use a symbol or nil from lisp and
    the name of the function or no name (i.e., the empty string)
    interactively.

I agree.  It is a mistake to try to document every detail of the
behavior.  We only document what we really want users to use.

    ! 
    ! If specified, @var{function-name} should normally be a symbol with a
    ! function definition or @code{nil}, but, for internal technical
    ! reasons, an empty string can be used as a substitute for @code{nil}.
    ! 
    ! If @var{function-name} is a non-@code{nil} symbol with a function
    ! definition, this command returns @var{function-name}, even if
    ! @var{function-name} was not previously set up to break on entry.  If
    ! @var{function-name} is omitted, @code{nil}, or an empty string, it
    ! returns a list of all functions for which break-on-entry was canceled.

There's no need to mention all those details.

Re: debugging.texi

[Richard Stallman]

      (defun debug-on-entry (function)
	"Request FUNCTION to invoke debugger each time it is called.
    + When called interactively, prompt for FUNCTION in the minibuffer.

That is useful to add.

      If you tell the debugger to continue, FUNCTION's execution proceeds.
      This works by modifying the definition of FUNCTION,
      which must be written in Lisp, not predefined.
      Use \\[cancel-debug-on-entry] to cancel the effect of this command.
    ! Redefining FUNCTION also cancels it.  This command returns FUNCTION."

There's no need for that change.

      (defun cancel-debug-on-entry (&optional function)
	"Undo effect of \\[debug-on-entry] on FUNCTION.
    ! If argument is nil or an empty string, cancel for all functions.
    ! When called interactively, prompt for FUNCTION in the minibuffer.
    ! To specify a nil argument interactively, exit with an empty minibuffer.

That is useful.

    ! 
    ! If specified, FUNCTION must be a symbol with a function definition,
    ! nil, or an empty string.  If FUNCTION is a non-nil symbol with
    ! a function definition, the return value is FUNCTION, even if FUNCTION
    ! was not previously set up to break on entry.  If FUNCTION is omitted,
    ! nil, or an empty string the return value is a list of all functions
    ! for which break-on-entry was canceled."

That is not needed.

Re: debugging.texi

[Luc Teirlinck]

What about the following additional change:

===File ~/debug.el-diff=====================================
*** debug.el	11 Jun 2005 18:36:43 -0500	1.84
--- debug.el	11 Jun 2005 19:22:48 -0500	
***************
*** 698,706 ****
  To specify a nil argument interactively, exit with an empty minibuffer."
    (interactive
     (list (let ((name
! 		(completing-read "Cancel debug on entry (to function): "
! 				 (mapcar 'symbol-name debug-function-list)
! 				 nil t nil)))
  	   (if name (intern name)))))
    (if (and function (not (string= function "")))
        (progn
--- 698,706 ----
  To specify a nil argument interactively, exit with an empty minibuffer."
    (interactive
     (list (let ((name
! 		(completing-read
! 		 "Cancel debug on entry to function (default: all functions): "
! 		 (mapcar 'symbol-name debug-function-list) nil t nil)))
  	   (if name (intern name)))))
    (if (and function (not (string= function "")))
        (progn
============================================================

Re: debugging.texi

[Lute Kamstra]

Luc Teirlinck <teirllm@dms.auburn.edu> writes:

> What about the following additional change:

I like it,

  Lute.

Re: debugging.texi

[Richard Stallman]

	  @var{function-name} in the minibuffer.  If @var{function-name} is
	! omitted, @code{nil} or the empty string, it cancels break-on-entry for all

    You need a comment after @code{nil} to eliminate a misreading.  With
    that change, please install.

Correction--you need a comma after...

debugging.texi

[Luc Teirlinck]

What about the following additional change to debugging.texi?  It may
not be that surprising that if you can not step through a
byte-compiled function, you can not step through a primitive function
either, but it may not hurt to explicitly mention it.

I can install if desired.

===File ~/debugging.texi-diff===============================
*** debugging.texi	14 Jun 2005 08:19:54 -0500	1.32
--- debugging.texi	15 Jun 2005 13:33:13 -0500	
***************
*** 350,356 ****
  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.)
  
    Here is a list of Debugger mode commands:
  
--- 350,357 ----
  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.)  There is no way to step through
! a primitive function.
  
    Here is a list of Debugger mode commands:
  
============================================================

Re: debugging.texi

[Lute Kamstra]

Luc Teirlinck <teirllm@dms.auburn.edu> writes:

> What about the following additional change to debugging.texi?  It may
> not be that surprising that if you can not step through a
> byte-compiled function, you can not step through a primitive function
> either, but it may not hurt to explicitly mention it.

I think your formulation is a bit misleading.  Emacs' debugger can't
step through a primitive, gdb can.

Lute.

Re: debugging.texi

[Luc Teirlinck]

Lute Kamstra wrote:

   I think your formulation is a bit misleading.  Emacs' debugger can't
   step through a primitive, gdb can.

So what about:

===File ~/debugging.texi-diff===============================
*** debugging.texi	14 Jun 2005 08:19:54 -0500	1.32
--- debugging.texi	15 Jun 2005 18:16:03 -0500	
***************
*** 350,356 ****
  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.)
  
    Here is a list of Debugger mode commands:
  
--- 350,357 ----
  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.)  You can not use the Lisp debugger
! to step through a primitive function.
  
    Here is a list of Debugger mode commands:
  
============================================================

Re: debugging.texi

[Lute Kamstra]

Luc Teirlinck <teirllm@dms.auburn.edu> writes:

> Lute Kamstra wrote:
>
>    I think your formulation is a bit misleading.  Emacs' debugger can't
>    step through a primitive, gdb can.
>
> So what about:

[...]

> ! type @kbd{C-M-x} on its definition.)  You can not use the Lisp debugger
> ! to step through a primitive function.

That's fine with me.

Thanks,

  Lute.