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#25111: (Inaccurate documentation of inhibit-modification-hooks) Date: Sun, 19 May 2019 20:31:19 +0000 Message-ID: <20190519203119.GA5309@ACM> References: <8360myl7ay.fsf@gnu.org> <87wpfbpual.fsf@russet.org.uk> <83eg1iiffm.fsf@gnu.org> <87pol1kon4.fsf@russet.org.uk> <83bmwlggix.fsf@gnu.org> <878trmxgjh.fsf@russet.org.uk> <83lgvlcet1.fsf@gnu.org> Mime-Version: 1.0 Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: 8bit Injection-Info: blaine.gmane.org; posting-host="blaine.gmane.org:195.159.176.226"; logging-data="25395"; mail-complaints-to="usenet@blaine.gmane.org" User-Agent: Mutt/1.10.1 (2018-07-13) Cc: 25111@debbugs.gnu.org, Phillip Lord To: Eli Zaretskii , Noam Postavsky Original-X-From: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane.org@gnu.org Sun May 19 22:35:22 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.0:RSA_AES_256_CBC_SHA1:256) (Exim 4.89) (envelope-from ) id 1hSSWe-0006Tn-Ve for geb-bug-gnu-emacs@m.gmane.org; Sun, 19 May 2019 22:35:21 +0200 Original-Received: from localhost ([127.0.0.1]:53066 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1hSSWd-0000pB-Vg for geb-bug-gnu-emacs@m.gmane.org; Sun, 19 May 2019 16:35:20 -0400 Original-Received: from eggs.gnu.org ([209.51.188.92]:49144) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1hSSTT-0007Dt-QZ for bug-gnu-emacs@gnu.org; Sun, 19 May 2019 16:32:04 -0400 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1hSSTS-0005Q3-NJ for bug-gnu-emacs@gnu.org; Sun, 19 May 2019 16:32:03 -0400 Original-Received: from debbugs.gnu.org ([209.51.188.43]:50316) by eggs.gnu.org with esmtps (TLS1.0:RSA_AES_128_CBC_SHA1:16) (Exim 4.71) (envelope-from ) id 1hSSTS-0005Pm-Iq for bug-gnu-emacs@gnu.org; Sun, 19 May 2019 16:32:02 -0400 Original-Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.84_2) (envelope-from ) id 1hSSTS-00064F-CU for bug-gnu-emacs@gnu.org; Sun, 19 May 2019 16:32:02 -0400 X-Loop: help-debbugs@gnu.org Resent-From: Alan Mackenzie Original-Sender: "Debbugs-submit" Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Sun, 19 May 2019 20:32:02 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: followup 25111 X-GNU-PR-Package: emacs Original-Received: via spool by 25111-submit@debbugs.gnu.org id=B25111.155829788523276 (code B ref 25111); Sun, 19 May 2019 20:32:02 +0000 Original-Received: (at 25111) by debbugs.gnu.org; 19 May 2019 20:31:25 +0000 Original-Received: from localhost ([127.0.0.1]:35627 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1hSSSr-00063M-0t for submit@debbugs.gnu.org; Sun, 19 May 2019 16:31:25 -0400 Original-Received: from colin.muc.de ([193.149.48.1]:19821 helo=mail.muc.de) by debbugs.gnu.org with smtp (Exim 4.84_2) (envelope-from ) id 1hSSSo-000637-Tx for 25111@debbugs.gnu.org; Sun, 19 May 2019 16:31:23 -0400 Original-Received: (qmail 4766 invoked by uid 3782); 19 May 2019 20:31:20 -0000 Original-Received: from acm.muc.de (p2E5D561D.dip0.t-ipconnect.de [46.93.86.29]) by colin.muc.de (tmda-ofmipd) with ESMTP; Sun, 19 May 2019 22:31:19 +0200 Original-Received: (qmail 5936 invoked by uid 1000); 19 May 2019 20:31:19 -0000 Content-Disposition: inline In-Reply-To: <83lgvlcet1.fsf@gnu.org> X-Delivery-Agent: TMDA/1.1.12 (Macallan) X-Primary-Address: acm@muc.de 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:159569 Archived-At: Hello, Eli and Noam. On Mon, Dec 12, 2016 at 18:06:34 +0200, Eli Zaretskii wrote: > > From: phillip.lord@russet.org.uk (Phillip Lord) > > Cc: 25111@debbugs.gnu.org > > Date: Sun, 11 Dec 2016 22:11:14 +0000 > > So, instead of this: > > If these functions modify the buffer, they should bind > > ‘inhibit-modification-hooks’ to ‘t’ around doing so, to avoid > > confusing the internal mechanism that calls these hooks. > > We could have: > > These functions should avoid unnecessarily modifying the buffer. > > Emacs binds 'inhibit-modification-hooks' to `t' during their > > evaluation, which means that any modifications will not be signalled > > to other hook functions listening for them. > > Perhaps a better solution would be: > > These functions should avoid unnecessarily modifying the buffer; see > > Change Hooks for further details. > > Then a new paragraph can be added to the Change Hooks section talking > > about the complexity of modifying buffers on these hooks, with > > alternatives. > > I am happy to draft something if you wish. > Sure, please do. > Thanks. OK, it was a while ago, and I'm not Phillip, but I recently got caught out with the inaccurate documentation of inhibit-modification-hooks, so I suggest the following, to get the discussion rolling again: diff --git a/doc/lispref/display.texi b/doc/lispref/display.texi index a2ed4b3891..b88702f2a2 100644 --- a/doc/lispref/display.texi +++ b/doc/lispref/display.texi @@ -1743,9 +1743,17 @@ Overlay Properties length is the number of characters deleted, and the post-change beginning and end are equal.) -If these functions modify the buffer, they should bind -@code{inhibit-modification-hooks} to @code{t} around doing so, to -avoid confusing the internal mechanism that calls these hooks. +@c If these functions modify the buffer, they should bind +@c @code{inhibit-modification-hooks} to @code{t} around doing so, to +@c avoid confusing the internal mechanism that calls these hooks. + +When these functions are called, @code{inhibit-modification-hooks} is +bound to non-@code{nil}. If the functions modify the buffer, you +might want to bind @code{inhibit-modification-hooks} to nil, so as to +cause the change hooks to run for these modifications. @xref{Change +Hooks}. However, doing this can sometimes confuse the internal +mechanism that calls all these hooks, leading, for example, to calling +them recursively, which is usually unwanted. Text properties also support the @code{modification-hooks} property, but the details are somewhat different (@pxref{Special Properties}). diff --git a/doc/lispref/text.texi b/doc/lispref/text.texi index 278bc3c268..fd4338ecdb 100644 --- a/doc/lispref/text.texi +++ b/doc/lispref/text.texi @@ -3621,9 +3621,14 @@ Special Properties hook will only be run when removing some characters, replacing them with others, or changing their text-properties. -If these functions modify the buffer, they should bind -@code{inhibit-modification-hooks} to @code{t} around doing so, to -avoid confusing the internal mechanism that calls these hooks. +@c If these functions modify the buffer, they should bind +@c @code{inhibit-modification-hooks} to @code{t} around doing so, to +@c avoid confusing the internal mechanism that calls these hooks. + +When Emacs calls these functions, @code{inhibit-modification-hooks} is +set to @code{nil}. If the functions modify the buffer, you should +consider binding this variable to non-@code{nil}, to avoid confusing +the internal mechanism that calls these hooks. @xref{Change Hooks}. Overlays also support the @code{modification-hooks} property, but the details are somewhat different (@pxref{Overlay Properties}). -- Alan Mackenzie (Nuremberg, Germany).