From: Eli Zaretskii <eliz@gnu.org>
To: npostavs@users.sourceforge.net
Cc: 24923@debbugs.gnu.org, stephen.berman@gmx.net
Subject: bug#24923: 25.1; Lisp watchpoints
Date: Sun, 20 Nov 2016 18:11:43 +0200 [thread overview]
Message-ID: <83lgwe9lmo.fsf@gnu.org> (raw)
In-Reply-To: <87wpfyjl1x.fsf@users.sourceforge.net> (npostavs@users.sourceforge.net)
> 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.
next prev parent reply other threads:[~2016-11-20 16:11 UTC|newest]
Thread overview: 22+ messages / expand[flat|nested] mbox.gz Atom feed top
2016-11-11 3:10 bug#24923: 25.1; Lisp watchpoints npostavs
2016-11-11 10:02 ` Eli Zaretskii
2016-11-12 4:34 ` npostavs
2016-11-12 7:19 ` Eli Zaretskii
2016-11-13 0:54 ` npostavs
2016-11-13 15:29 ` Eli Zaretskii
2016-11-20 2:12 ` npostavs
2016-11-20 10:49 ` Stephen Berman
2016-11-20 14:14 ` npostavs
2016-11-20 16:11 ` Eli Zaretskii [this message]
2016-11-20 19:26 ` npostavs
2016-11-20 19:36 ` Eli Zaretskii
2016-11-20 20:16 ` npostavs
2016-11-21 17:31 ` Eli Zaretskii
2016-12-03 1:47 ` npostavs
2016-12-03 3:49 ` Clément Pit--Claudel
2016-12-03 3:50 ` Clément Pit--Claudel
2016-12-03 5:01 ` Daniel Colascione
2016-12-03 14:11 ` npostavs
2016-11-20 15:58 ` Eli Zaretskii
2016-11-20 17:00 ` npostavs
2016-11-20 17:25 ` Eli Zaretskii
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
List information: https://www.gnu.org/software/emacs/
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=83lgwe9lmo.fsf@gnu.org \
--to=eliz@gnu.org \
--cc=24923@debbugs.gnu.org \
--cc=npostavs@users.sourceforge.net \
--cc=stephen.berman@gmx.net \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
Code repositories for project(s) associated with this public inbox
https://git.savannah.gnu.org/cgit/emacs.git
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).