GNU bug report logs - #24923
Lisp watchpoints

Previous Next

Full log

View this message in rfc822 format

From: Eli Zaretskii <eliz <at> gnu.org>
To: npostavs <at> users.sourceforge.net
Cc: 24923 <at> debbugs.gnu.org, stephen.berman <at> gmx.net
Subject: bug#24923: 25.1; Lisp watchpoints
Date: Sun, 20 Nov 2016 18:11:43 +0200

> From: npostavs <at> users.sourceforge.net
> Cc: 24923 <at> debbugs.gnu.org,  Eli Zaretskii <eliz <at> gnu.org>
> Date: Sun, 20 Nov 2016 09:14:02 -0500
> 
> > There are a few typos in the documentation:
> 
> Thanks, reattaching just the fixed documentation commit.
> diff --git a/doc/lispref/debugging.texi b/doc/lispref/debugging.texi
> index 6c0908a..c047d45 100644
> --- a/doc/lispref/debugging.texi
> +++ b/doc/lispref/debugging.texi
> @@ -69,6 +69,7 @@ Debugger
>  * 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.
> +* Variable Debugging::    Entering it when a variable is modified.

This additional menu item should be also added to the master menu in
elisp.texi.

> +@deffn Command debug-on-variable-change variable
> +This function arranges for the debugger to be called whenever
> +@var{variable} is modified.
> +
> +It is implemented using the watchpoint mechanism, so it inherits the
> +same characteristics and limitations: all aliases of @var{variable}
> +will be watched together, only dynamic variables can be watched, and
> +changes to the objects referenced by variables are not detected.  For
> +details, see @xref{Watching Variables}.
                ^^^^^
@xref already generates "See", capitalized, so you want @ref here.

> diff --git a/doc/lispref/variables.texi b/doc/lispref/variables.texi
> index 418a416..1e0b098 100644
> --- a/doc/lispref/variables.texi
> +++ b/doc/lispref/variables.texi
> @@ -34,6 +34,7 @@ Variables
>  * Accessing Variables::         Examining values of variables whose names
>                              are known only at run time.
>  * Setting Variables::           Storing new values in variables.
> +* Watching Variables::          Running a function when a variable is changed.

Likewise, this should be added to the master menu.

> +@node Watching Variables
> +@section Running a function when a variable is changed.
> +@cindex variable watchpoints

I'd add here an index entry that begins with "watchpoint", like this:

  @cindex watchpoints for Lisp variables

That's for those who like using completion in Info-index command.

> +variable settings, and invoking the debugger to track down unexpected
> +changes to variables @pxref{Variable Debugging}.

I believe you meant to put @pxref in parentheses.

> +Each variable has a list of watch functions stored in its
> +@code{watchers} symbol property, @xref{Symbol Properties}.
                                    ^^^^^
Either "see @ref" or "@pxref", because @xref generates a capitalized
"See", and so is only appropriate at the beginning of a sentence.

> +@defun add-variable-watcher symbol watch-function
> +This function arranges for @var{watch-function} to be called whenever
> +@var{symbol} (or any of its aliases @pxref{Variable Aliases}) are
                                      ^
> +modified.

A comma is missing here.  Also, I believe "is modified" reads better
here.  Or maybe replace the parentheses with commas, then plural
should be okay, I think.

> +@defun get-variable-watchers symbol
> +This function returns the list of active watcher functions.

Please mention SYMBOL here.

Thanks.

Previous Next

GNU bug tracking system
Copyright (C) 1999 Darren O. Benham, 1997,2003 nCipher Corporation Ltd, 1994-97 Ian Jackson.