From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!.POSTED.blaine.gmane.org!not-for-mail From: Alan Mackenzie Newsgroups: gmane.emacs.bugs Subject: bug#38205: Unhelpful documentation for add-variable-watcher. 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 Injection-Info: blaine.gmane.org; posting-host="blaine.gmane.org:195.159.176.226"; logging-data="45429"; mail-complaints-to="usenet@blaine.gmane.org" User-Agent: Mutt/1.10.1 (2018-07-13) To: 38205@debbugs.gnu.org Original-X-From: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane.org@gnu.org Thu Nov 14 08:39:11 2019 Return-path: Envelope-to: geb-bug-gnu-emacs@m.gmane.org Original-Received: from lists.gnu.org ([209.51.188.17]) by blaine.gmane.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.89) (envelope-from ) id 1iV9ig-000Bgc-Ub for geb-bug-gnu-emacs@m.gmane.org; Thu, 14 Nov 2019 08:39:11 +0100 Original-Received: from localhost ([::1]:54114 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1iV9if-000443-OX for geb-bug-gnu-emacs@m.gmane.org; Thu, 14 Nov 2019 02:39:09 -0500 Original-Received: from eggs.gnu.org ([2001:470:142:3::10]:60531) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1iV9iY-00043w-VA for bug-gnu-emacs@gnu.org; Thu, 14 Nov 2019 02:39:04 -0500 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1iV9iY-0001Y1-0R for bug-gnu-emacs@gnu.org; Thu, 14 Nov 2019 02:39:02 -0500 Original-Received: from debbugs.gnu.org ([209.51.188.43]:52043) by eggs.gnu.org with esmtps (TLS1.0:RSA_AES_128_CBC_SHA1:16) (Exim 4.71) (envelope-from ) id 1iV9iX-0001XS-TP for bug-gnu-emacs@gnu.org; Thu, 14 Nov 2019 02:39:01 -0500 Original-Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.84_2) (envelope-from ) id 1iV9iX-0004mw-QG for bug-gnu-emacs@gnu.org; Thu, 14 Nov 2019 02:39:01 -0500 X-Loop: help-debbugs@gnu.org 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-Debbugs-Original-To: bug-gnu-emacs@gnu.org Original-Received: via spool by submit@debbugs.gnu.org id=B.157371712218377 (code B ref -1); Thu, 14 Nov 2019 07:39:01 +0000 Original-Received: (at submit) by debbugs.gnu.org; 14 Nov 2019 07:38:42 +0000 Original-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 Original-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 Original-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 Original-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 Original-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 Original-Received: (qmail 85375 invoked by uid 3782); 14 Nov 2019 07:38:36 -0000 Original-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 Original-Received: (qmail 9556 invoked by uid 1000); 14 Nov 2019 07:38:35 -0000 Content-Disposition: inline X-Delivery-Agent: TMDA/1.1.12 (Macallan) X-Primary-Address: acm@muc.de X-detected-operating-system: by eggs.gnu.org: FreeBSD 9.x [fuzzy] X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.2.x-3.x [generic] X-Received-From: 209.51.188.43 X-BeenThere: bug-gnu-emacs@gnu.org List-Id: "Bug reports for GNU Emacs, the Swiss army knife of text editors" List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane.org@gnu.org Original-Sender: "bug-gnu-emacs" Xref: news.gmane.org gmane.emacs.bugs:171557 Archived-At: 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).