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 address@hidden 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): "
============================================================