bug#24923: 25.1; Lisp watchpoints

[Eli Zaretskii]

> From: npostavs@users.sourceforge.net
> Cc: 24923@debbugs.gnu.org,  Eli Zaretskii <eliz@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.