From unknown Sat Jun 14 19:13:57 2025 X-Loop: help-debbugs@gnu.org Subject: bug#38205: Unhelpful documentation for add-variable-watcher. Resent-From: Alan Mackenzie Original-Sender: "Debbugs-submit" Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Thu, 14 Nov 2019 07:39:01 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: report 38205 X-GNU-PR-Package: emacs X-GNU-PR-Keywords: To: 38205@debbugs.gnu.org X-Debbugs-Original-To: bug-gnu-emacs@gnu.org Received: via spool by submit@debbugs.gnu.org id=B.157371712218377 (code B ref -1); Thu, 14 Nov 2019 07:39:01 +0000 Received: (at submit) by debbugs.gnu.org; 14 Nov 2019 07:38:42 +0000 Received: from localhost ([127.0.0.1]:60864 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1iV9iE-0004mL-1O for submit@debbugs.gnu.org; Thu, 14 Nov 2019 02:38:42 -0500 Received: from lists.gnu.org ([209.51.188.17]:60516) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1iV9iC-0004mD-Ix for submit@debbugs.gnu.org; Thu, 14 Nov 2019 02:38:41 -0500 Received: from eggs.gnu.org ([2001:470:142:3::10]:60464) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1iV9iB-00041D-Ij for bug-gnu-emacs@gnu.org; Thu, 14 Nov 2019 02:38:40 -0500 X-Spam-Checker-Version: SpamAssassin 3.3.2 (2011-06-06) on eggs.gnu.org X-Spam-Level: X-Spam-Status: No, score=0.8 required=5.0 tests=BAYES_50 autolearn=disabled version=3.3.2 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1iV9iA-0001Hq-ED for bug-gnu-emacs@gnu.org; Thu, 14 Nov 2019 02:38:39 -0500 Received: from colin.muc.de ([193.149.48.1]:24491 helo=mail.muc.de) by eggs.gnu.org with smtp (Exim 4.71) (envelope-from ) id 1iV9iA-0001Gt-3q for bug-gnu-emacs@gnu.org; Thu, 14 Nov 2019 02:38:38 -0500 Received: (qmail 85375 invoked by uid 3782); 14 Nov 2019 07:38:36 -0000 Received: from acm.muc.de (p4FE1564A.dip0.t-ipconnect.de [79.225.86.74]) by colin.muc.de (tmda-ofmipd) with ESMTP; Thu, 14 Nov 2019 08:38:35 +0100 Received: (qmail 9556 invoked by uid 1000); 14 Nov 2019 07:38:35 -0000 Date: Thu, 14 Nov 2019 07:38:35 +0000 Message-ID: <20191114073835.GA4935@ACM> MIME-Version: 1.0 Content-Type: text/plain; charset=us-ascii Content-Disposition: inline User-Agent: Mutt/1.10.1 (2018-07-13) X-Delivery-Agent: TMDA/1.1.12 (Macallan) From: Alan Mackenzie X-Primary-Address: acm@muc.de X-detected-operating-system: by eggs.gnu.org: FreeBSD 9.x [fuzzy] X-Received-From: 193.149.48.1 X-Spam-Score: -1.6 (-) X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: -2.6 (--) Hello, Emacs. The doc string for add-variable-watcher wrongly states: Cause WATCH-FUNCTION to be called when SYMBOL is set. . Correct would be either Cause WATCH-FUNCTION to be called just before SYMBOL is set. or Cause WATCH-FUNCTION to be called just after SYMBOL is set. . I'm guessing that the first of these applies, but I shouldn't have to guess. The difference is whether one can get the old value from SYMBOL or not. The documentation in the Elisp manual is similarly ambiguous. It uses the conjunction "whenever". -- Alan Mackenzie (Nuremberg, Germany). From unknown Sat Jun 14 19:13:57 2025 MIME-Version: 1.0 X-Mailer: MIME-tools 5.505 (Entity 5.505) X-Loop: help-debbugs@gnu.org From: help-debbugs@gnu.org (GNU bug Tracking System) To: Alan Mackenzie Subject: bug#38205: closed (Re: bug#38205: Unhelpful documentation for add-variable-watcher.) Message-ID: References: <83v9rl336u.fsf@gnu.org> <20191114073835.GA4935@ACM> X-Gnu-PR-Message: they-closed 38205 X-Gnu-PR-Package: emacs Reply-To: 38205@debbugs.gnu.org Date: Fri, 15 Nov 2019 09:22:02 +0000 Content-Type: multipart/mixed; boundary="----------=_1573809722-5124-1" This is a multi-part message in MIME format... ------------=_1573809722-5124-1 Content-Disposition: inline Content-Transfer-Encoding: quoted-printable Content-Type: text/plain; charset="utf-8" Your bug report #38205: Unhelpful documentation for add-variable-watcher. which was filed against the emacs package, has been closed. The explanation is attached below, along with your original report. If you require more details, please reply to 38205@debbugs.gnu.org. --=20 38205: http://debbugs.gnu.org/cgi/bugreport.cgi?bug=3D38205 GNU Bug Tracking System Contact help-debbugs@gnu.org with problems ------------=_1573809722-5124-1 Content-Type: message/rfc822 Content-Disposition: inline Content-Transfer-Encoding: 7bit Received: (at 38205-done) by debbugs.gnu.org; 15 Nov 2019 09:21:51 +0000 Received: from localhost ([127.0.0.1]:35661 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1iVXnb-0001KI-6G for submit@debbugs.gnu.org; Fri, 15 Nov 2019 04:21:51 -0500 Received: from eggs.gnu.org ([209.51.188.92]:40160) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1iVXnZ-0001K5-8i for 38205-done@debbugs.gnu.org; Fri, 15 Nov 2019 04:21:49 -0500 Received: from fencepost.gnu.org ([2001:470:142:3::e]:41674) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1iVXnT-0001hy-S4; Fri, 15 Nov 2019 04:21:43 -0500 Received: from [176.228.60.248] (port=3959 helo=home-c4e4a596f7) by fencepost.gnu.org with esmtpsa (TLS1.2:RSA_AES_256_CBC_SHA1:256) (Exim 4.82) (envelope-from ) id 1iVXnT-0001vn-E9; Fri, 15 Nov 2019 04:21:43 -0500 Date: Fri, 15 Nov 2019 11:21:29 +0200 Message-Id: <83v9rl336u.fsf@gnu.org> From: Eli Zaretskii To: Alan Mackenzie In-reply-to: <20191114073835.GA4935@ACM> (message from Alan Mackenzie on Thu, 14 Nov 2019 07:38:35 +0000) Subject: Re: bug#38205: Unhelpful documentation for add-variable-watcher. References: <20191114073835.GA4935@ACM> X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.2.x-3.x [generic] X-Spam-Score: -2.3 (--) X-Debbugs-Envelope-To: 38205-done Cc: 38205-done@debbugs.gnu.org X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: -3.3 (---) > Date: Thu, 14 Nov 2019 07:38:35 +0000 > From: Alan Mackenzie > > The doc string for add-variable-watcher wrongly states: > > Cause WATCH-FUNCTION to be called when SYMBOL is set. > > . Correct would be either > > Cause WATCH-FUNCTION to be called just before SYMBOL is set. > > or > > Cause WATCH-FUNCTION to be called just after SYMBOL is set. Well, the doc string goes on to say NEWVAL is the value it will be changed to. ^^^^^^^ which is a clear hint to what actually happens. But I made this even more clear in the doc string, thanks. > The documentation in the Elisp manual is similarly ambiguous. It uses > the conjunction "whenever". Fixed that as well. ------------=_1573809722-5124-1 Content-Type: message/rfc822 Content-Disposition: inline Content-Transfer-Encoding: 7bit Received: (at submit) by debbugs.gnu.org; 14 Nov 2019 07:38:42 +0000 Received: from localhost ([127.0.0.1]:60864 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1iV9iE-0004mL-1O for submit@debbugs.gnu.org; Thu, 14 Nov 2019 02:38:42 -0500 Received: from lists.gnu.org ([209.51.188.17]:60516) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1iV9iC-0004mD-Ix for submit@debbugs.gnu.org; Thu, 14 Nov 2019 02:38:41 -0500 Received: from eggs.gnu.org ([2001:470:142:3::10]:60464) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1iV9iB-00041D-Ij for bug-gnu-emacs@gnu.org; Thu, 14 Nov 2019 02:38:40 -0500 X-Spam-Checker-Version: SpamAssassin 3.3.2 (2011-06-06) on eggs.gnu.org X-Spam-Level: X-Spam-Status: No, score=0.8 required=5.0 tests=BAYES_50 autolearn=disabled version=3.3.2 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1iV9iA-0001Hq-ED for bug-gnu-emacs@gnu.org; Thu, 14 Nov 2019 02:38:39 -0500 Received: from colin.muc.de ([193.149.48.1]:24491 helo=mail.muc.de) by eggs.gnu.org with smtp (Exim 4.71) (envelope-from ) id 1iV9iA-0001Gt-3q for bug-gnu-emacs@gnu.org; Thu, 14 Nov 2019 02:38:38 -0500 Received: (qmail 85375 invoked by uid 3782); 14 Nov 2019 07:38:36 -0000 Received: from acm.muc.de (p4FE1564A.dip0.t-ipconnect.de [79.225.86.74]) by colin.muc.de (tmda-ofmipd) with ESMTP; Thu, 14 Nov 2019 08:38:35 +0100 Received: (qmail 9556 invoked by uid 1000); 14 Nov 2019 07:38:35 -0000 Date: Thu, 14 Nov 2019 07:38:35 +0000 To: bug-gnu-emacs@gnu.org Subject: Unhelpful documentation for add-variable-watcher. Message-ID: <20191114073835.GA4935@ACM> MIME-Version: 1.0 Content-Type: text/plain; charset=us-ascii Content-Disposition: inline User-Agent: Mutt/1.10.1 (2018-07-13) X-Delivery-Agent: TMDA/1.1.12 (Macallan) From: Alan Mackenzie X-Primary-Address: acm@muc.de X-detected-operating-system: by eggs.gnu.org: FreeBSD 9.x [fuzzy] X-Received-From: 193.149.48.1 X-Spam-Score: -1.6 (-) X-Debbugs-Envelope-To: submit X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: -2.6 (--) Hello, Emacs. The doc string for add-variable-watcher wrongly states: Cause WATCH-FUNCTION to be called when SYMBOL is set. . Correct would be either Cause WATCH-FUNCTION to be called just before SYMBOL is set. or Cause WATCH-FUNCTION to be called just after SYMBOL is set. . I'm guessing that the first of these applies, but I shouldn't have to guess. The difference is whether one can get the old value from SYMBOL or not. The documentation in the Elisp manual is similarly ambiguous. It uses the conjunction "whenever". -- Alan Mackenzie (Nuremberg, Germany). ------------=_1573809722-5124-1-- From unknown Sat Jun 14 19:13:57 2025 X-Loop: help-debbugs@gnu.org Subject: bug#38205: Unhelpful documentation for add-variable-watcher. Resent-From: Alan Mackenzie Original-Sender: "Debbugs-submit" Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Sat, 16 Nov 2019 12:37:02 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: followup 38205 X-GNU-PR-Package: emacs X-GNU-PR-Keywords: To: Eli Zaretskii Cc: 38205-done@debbugs.gnu.org Received: via spool by 38205-done@debbugs.gnu.org id=D38205.15739077625797 (code D ref 38205); Sat, 16 Nov 2019 12:37:02 +0000 Received: (at 38205-done) by debbugs.gnu.org; 16 Nov 2019 12:36:02 +0000 Received: from localhost ([127.0.0.1]:37821 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1iVxJ4-0001VG-3P for submit@debbugs.gnu.org; Sat, 16 Nov 2019 07:36:02 -0500 Received: from colin.muc.de ([193.149.48.1]:34966 helo=mail.muc.de) by debbugs.gnu.org with smtp (Exim 4.84_2) (envelope-from ) id 1iVxJ2-0001Ut-2Z for 38205-done@debbugs.gnu.org; Sat, 16 Nov 2019 07:36:00 -0500 Received: (qmail 71748 invoked by uid 3782); 16 Nov 2019 12:35:58 -0000 Received: from acm.muc.de (p2E5D55F4.dip0.t-ipconnect.de [46.93.85.244]) by colin.muc.de (tmda-ofmipd) with ESMTP; Sat, 16 Nov 2019 13:35:57 +0100 Received: (qmail 6721 invoked by uid 1000); 16 Nov 2019 12:35:57 -0000 Date: Sat, 16 Nov 2019 12:35:57 +0000 Message-ID: <20191116123557.GA6711@ACM> References: <20191114073835.GA4935@ACM> <83v9rl336u.fsf@gnu.org> MIME-Version: 1.0 Content-Type: text/plain; charset=us-ascii Content-Disposition: inline In-Reply-To: <83v9rl336u.fsf@gnu.org> User-Agent: Mutt/1.10.1 (2018-07-13) X-Delivery-Agent: TMDA/1.1.12 (Macallan) From: Alan Mackenzie X-Primary-Address: acm@muc.de X-Spam-Score: 0.0 (/) X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: -1.0 (-) Hello, Eli. On Fri, Nov 15, 2019 at 11:21:29 +0200, Eli Zaretskii wrote: > > Date: Thu, 14 Nov 2019 07:38:35 +0000 > > From: Alan Mackenzie > > The doc string for add-variable-watcher wrongly states: > > Cause WATCH-FUNCTION to be called when SYMBOL is set. > > . Correct would be either > > Cause WATCH-FUNCTION to be called just before SYMBOL is set. > > or > > Cause WATCH-FUNCTION to be called just after SYMBOL is set. > Well, the doc string goes on to say > NEWVAL is the value it will be changed to. > ^^^^^^^ > which is a clear hint to what actually happens. But I made this even > more clear in the doc string, thanks. > > The documentation in the Elisp manual is similarly ambiguous. It uses > > the conjunction "whenever". > Fixed that as well. Thanks! -- Alan Mackenzie (Nuremberg, Germany).