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: Mon, 24 Jun 2019 12:52:49 +0000 Message-ID: <20190624125249.GB4781@ACM> References: <20190519203119.GA5309@ACM> <87y32u908k.fsf@gmail.com> <20190525134407.GA10864@ACM> <87sgt28ut4.fsf@gmail.com> <20190527143109.GA5863@ACM> <20190603191549.GA4009@ACM> <85tvd6bhch.fsf@gmail.com> <20190604093241.GA5790@ACM> <838suhto2r.fsf@gnu.org> <83muirarzj.fsf@gnu.org> 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="191641"; mail-complaints-to="usenet@blaine.gmane.org" User-Agent: Mutt/1.10.1 (2018-07-13) Cc: 25111@debbugs.gnu.org, phillip.lord@russet.org.uk To: Eli Zaretskii , npostavs@gmail.com Original-X-From: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane.org@gnu.org Mon Jun 24 14:54:10 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 1hfOU6-000nlw-Ak for geb-bug-gnu-emacs@m.gmane.org; Mon, 24 Jun 2019 14:54:10 +0200 Original-Received: from localhost ([::1]:50924 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.86_2) (envelope-from ) id 1hfOU5-0003Du-8e for geb-bug-gnu-emacs@m.gmane.org; Mon, 24 Jun 2019 08:54:09 -0400 Original-Received: from eggs.gnu.org ([2001:470:142:3::10]:57930) by lists.gnu.org with esmtp (Exim 4.86_2) (envelope-from ) id 1hfOTz-0003Dg-EG for bug-gnu-emacs@gnu.org; Mon, 24 Jun 2019 08:54:04 -0400 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1hfOTy-0006DQ-6R for bug-gnu-emacs@gnu.org; Mon, 24 Jun 2019 08:54:03 -0400 Original-Received: from debbugs.gnu.org ([209.51.188.43]:42237) by eggs.gnu.org with esmtps (TLS1.0:RSA_AES_128_CBC_SHA1:16) (Exim 4.71) (envelope-from ) id 1hfOTy-0006Bw-0w for bug-gnu-emacs@gnu.org; Mon, 24 Jun 2019 08:54:02 -0400 Original-Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.84_2) (envelope-from ) id 1hfOTx-0006iz-SL for bug-gnu-emacs@gnu.org; Mon, 24 Jun 2019 08:54:01 -0400 X-Loop: help-debbugs@gnu.org Resent-From: Alan Mackenzie Original-Sender: "Debbugs-submit" Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Mon, 24 Jun 2019 12:54:01 +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.156138078325780 (code B ref 25111); Mon, 24 Jun 2019 12:54:01 +0000 Original-Received: (at 25111) by debbugs.gnu.org; 24 Jun 2019 12:53:03 +0000 Original-Received: from localhost ([127.0.0.1]:55780 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1hfOT0-0006hk-MH for submit@debbugs.gnu.org; Mon, 24 Jun 2019 08:53:02 -0400 Original-Received: from colin.muc.de ([193.149.48.1]:30074 helo=mail.muc.de) by debbugs.gnu.org with smtp (Exim 4.84_2) (envelope-from ) id 1hfOSy-0006hJ-Fu for 25111@debbugs.gnu.org; Mon, 24 Jun 2019 08:53:01 -0400 Original-Received: (qmail 56003 invoked by uid 3782); 24 Jun 2019 12:52:50 -0000 Original-Received: from acm.muc.de (p4FE15E6F.dip0.t-ipconnect.de [79.225.94.111]) by colin.muc.de (tmda-ofmipd) with ESMTP; Mon, 24 Jun 2019 14:52:49 +0200 Original-Received: (qmail 4176 invoked by uid 1000); 24 Jun 2019 12:52:49 -0000 Content-Disposition: inline In-Reply-To: <83muirarzj.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:161207 Archived-At: Hello, Eli and Noam (but mainly Noam). It's about time we finally got this matter tidied up, so... On Sun, Jun 09, 2019 at 15:00:16 +0300, Eli Zaretskii wrote: > OK, after re-reading the discussions and the code, I don't think we > should make the incompatible change suggested by Alan. We haven't > bound inhibit-modification-hooks to t in the text-property hooks since > the day the code was written, 24 years ago, so it makes no sense to me > to do that now. Let's document the exception and move on. > Noam's last patch LGTM, with the single minor gotcha: > > +When Emacs calls these functions, @code{inhibit-modification-hooks} is > > +set to @code{nil}, unlike for change hooks. > This is from the part that changes the "Special Properties" node, and > it's inaccurate: we don't bind inhibit-modification-hooks to nil, we > just leave it at its previous binding. This distinction is important > in recursive calls, when the caller caused inhibit-modification-hooks > to be bound to non-nil. I've corrected this bit by saying that "Unlike with other similar hooks, when Emacs calls these functions, `inhibit-modification-hooks' does _not_ get bound to non-`nil'". I've also added bits to the descriptions of insert-{in-front,behind}-hooks, the text property version of them, documenting that inhibit-modification-hooks gets bound to non-nil. [ .... ] I think the changes as now formulated are right. Perhaps one or both of you might like to give the following patch a quick review. Thanks! diff --git a/doc/lispref/display.texi b/doc/lispref/display.texi index 7e8abb0440..68f40b55d8 100644 --- a/doc/lispref/display.texi +++ b/doc/lispref/display.texi @@ -1752,9 +1752,12 @@ 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. +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. However, doing +this may call your own change hook recursively, so be sure to prepare +for that. @xref{Change Hooks}. 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 2e7c497f57..95ed758914 100644 --- a/doc/lispref/text.texi +++ b/doc/lispref/text.texi @@ -3621,9 +3621,12 @@ 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. +Unlike with other similar hooks, when Emacs calls these functions, +@code{inhibit-modification-hooks} does @emph{not} get bound to +non-@code{nil}. If the functions modify the buffer, you should +consider binding this variable to non-@code{nil} to prevent any buffer +changes running the change hooks. Otherwise, you must be prepared for +recursive calls. @xref{Change Hooks}. Overlays also support the @code{modification-hooks} property, but the details are somewhat different (@pxref{Overlay Properties}). @@ -3639,6 +3642,13 @@ Special Properties beginning and end of the inserted text. The functions are called @emph{after} the actual insertion takes place. +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. However, doing +this may call your own change hook recursively, so be sure to prepare +for that. + See also @ref{Change Hooks}, for other hooks that are called when you change text in a buffer. @@ -5650,5 +5660,8 @@ Change Hooks a modification hook does not cause other modification hooks to be run. If you do want modification hooks to be run in a particular piece of code that is itself run from a modification hook, then rebind locally -@code{inhibit-modification-hooks} to @code{nil}. +@code{inhibit-modification-hooks} to @code{nil}. However, doing this +may cause recursive calls to the modification hooks, so be sure to +prepare for that (for example, by binding some variable which tells +your hook to do nothing). @end defvar -- Alan Mackenzie (Nuremberg, Germany).