From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.io!.POSTED.blaine.gmane.org!not-for-mail From: Eli Zaretskii Newsgroups: gmane.emacs.bugs Subject: bug#70077: An easier way to track buffer changes Date: Tue, 09 Apr 2024 06:56:07 +0300 Message-ID: <865xwrxk88.fsf@gnu.org> References: <86frvy51af.fsf@gnu.org> Injection-Info: ciao.gmane.io; posting-host="blaine.gmane.org:116.202.254.214"; logging-data="40326"; mail-complaints-to="usenet@ciao.gmane.io" Cc: acm@muc.de, yantar92@posteo.net, 70077@debbugs.gnu.org To: Stefan Monnier Original-X-From: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane-mx.org@gnu.org Tue Apr 09 05:57:19 2024 Return-path: Envelope-to: geb-bug-gnu-emacs@m.gmane-mx.org Original-Received: from lists.gnu.org ([209.51.188.17]) by ciao.gmane.io with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.92) (envelope-from ) id 1ru2bl-000AF9-Sk for geb-bug-gnu-emacs@m.gmane-mx.org; Tue, 09 Apr 2024 05:57:18 +0200 Original-Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1ru2bR-00013u-8o; Mon, 08 Apr 2024 23:56:57 -0400 Original-Received: from eggs.gnu.org ([2001:470:142:3::10]) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1ru2bP-00013N-3L for bug-gnu-emacs@gnu.org; Mon, 08 Apr 2024 23:56:55 -0400 Original-Received: from debbugs.gnu.org ([2001:470:142:5::43]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1ru2bO-0002ph-S3 for bug-gnu-emacs@gnu.org; Mon, 08 Apr 2024 23:56:54 -0400 Original-Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.84_2) (envelope-from ) id 1ru2bW-0005Xp-Ij for bug-gnu-emacs@gnu.org; Mon, 08 Apr 2024 23:57:02 -0400 X-Loop: help-debbugs@gnu.org Resent-From: Eli Zaretskii Original-Sender: "Debbugs-submit" Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Tue, 09 Apr 2024 03:57:02 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: followup 70077 X-GNU-PR-Package: emacs X-GNU-PR-Keywords: patch Original-Received: via spool by 70077-submit@debbugs.gnu.org id=B70077.171263499021137 (code B ref 70077); Tue, 09 Apr 2024 03:57:02 +0000 Original-Received: (at 70077) by debbugs.gnu.org; 9 Apr 2024 03:56:30 +0000 Original-Received: from localhost ([127.0.0.1]:48001 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1ru2b0-0005Uq-3e for submit@debbugs.gnu.org; Mon, 08 Apr 2024 23:56:30 -0400 Original-Received: from eggs.gnu.org ([2001:470:142:3::10]:47476) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1ru2av-0005Tp-SO for 70077@debbugs.gnu.org; Mon, 08 Apr 2024 23:56:28 -0400 Original-Received: from fencepost.gnu.org ([2001:470:142:3::e]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1ru2af-0002i1-DA; Mon, 08 Apr 2024 23:56:09 -0400 DKIM-Signature: v=1; a=rsa-sha256; q=dns/txt; c=relaxed/relaxed; d=gnu.org; s=fencepost-gnu-org; h=References:Subject:In-Reply-To:To:From:Date: mime-version; bh=iyy0Zl8A4/1Ds6HZjGUNuNy3AGqvxlAR1M1laPwo0Wo=; b=eqnOaBH2KCs4 b0gbALxp5wgyZKam3EXlD8KpqoMx6s/48a0CYGG2IrlPORgpv+9MTp9kkRS2Jc+SCAXg/KPXdOTlp bl18R0pAcyZDuF3iUrQrivkKLZjrS87h6UPOrRyCJ+9PoamQvH3Ft5OK+c8+7gGmo5CCeJdal7hKJ zsMbSD2MwGzy/WGNqC56pykt+VyiZG3c1HXQB1eQtdMtdYLP0Wp8OjlZg5M19SX3q3mYG1TRON7gt GQqivq4XS2MVbasvHotFtNfQSsDaubQ/Ze85uqGT6+4KuEqtuZv1WUr6jBGmJ45ggFsoKKv0yvfIi mQiCBHnEHf0elpjBzge2dg==; In-Reply-To: (message from Stefan Monnier on Mon, 08 Apr 2024 16:45:39 -0400) X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list 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-mx.org@gnu.org Original-Sender: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane-mx.org@gnu.org Xref: news.gmane.io gmane.emacs.bugs:282962 Archived-At: > From: Stefan Monnier > Cc: 70077@debbugs.gnu.org, acm@muc.de, yantar92@posteo.net > Date: Mon, 08 Apr 2024 16:45:39 -0400 > > >> Last, but not least: this needs suitable changes in NEWS and ELisp > >> manual. > > Working on it. > > Here it is (and aso on `scratch/track-changes`). Thanks. > +Using @code{before-change-functions} and @code{after-change-functions} > +can be difficult in practice because of a number of pitfalls, such as > +the fact that the two calls are not always properly paired, or some > +calls may be missing, either because of bugs in the C code or because of > +inappropriate use of @code{inhibit-modification-hooks}. I don't think we should talk about bugs in C code in the manual, at least not so explicitly. I would rephrase the fact that the two calls are not always properly paired, or some calls may be missing, either because some Emacs primitives cannot properly pair them or because of incorrect use of @code{inhibit-modification-hooks}. > +The start tracking changes, you have to call ^^^^^^^^^ "To start" > +@code{track-changes-register}, passing it a @var{signal} function as > +argument. This will return a tracker @var{id} which is used to identify > +your tracker to the other functions of the library. The other main > +function of the library is @code{track-changes-fetch} which lets you > +fetch the changes you have not yet processed. The last sentence is redundant, since you are about to describe track-changes-fetch shortly. > +When the buffer is modified, the library will call the @var{signal} > +function to inform you of that change and will immediately start > +accumulating subsequent changes into a single combined change. > +The @var{signal} function serves only to warn that a modification > +occurred but does not receive a description of the change. Also the > +library will not call it again until after you processed > +the change. The last sentence should IMO say "...until after you retrieved the change by calling @code{track-changes-fetch}." The important part here is to say what "process" means in practice, instead of leaving it unsaid. > +To process changes, you need to call @code{track-changes-fetch}, which That's not really "processing", that's "retrieval", right? Processing is what the program does after it retrieves the changes. > +@defun track-changes-register signal &key nobefore disjoint immediate > +This function creates a new @emph{tracker}. Trackers are kept abstract, I suggest to use "change tracker" instead of just "tracker". On my daytime job, "tracker" has a very different meaning, so I stumble each time I see this used like that. Also, I suggest to use @dfn for its markup (and add a @cindex for it for good measure). > +By default, the call to the @var{signal} function does not happen > +immediately, but is instead postponed with a 0 seconds timer. ^^^^^^^^^^^^^^^ A cross-reference to where timers are described is in order there. > +usually desired to make sure the @var{signal} function is not called too > +frequently and runs in a permissive context, freeing the client from > +performance concerns or worries about which operations might be > +problematic. If a client wants to have more control, they can provide > +a non-nil value as the @var{immediate} argument in which case the ^^^ @code{nil} > +If you're not interested in the actual previous content of the buffer, > +but are using this library only for its ability to combine many small > +changes into a larger one and to delay the processing to a more > +convenient time, you can specify a non-nil value for the @var{before} ^^^ Likewise. > +While you may like to accumulate many small changes into larger ones, > +you may not want to do that if the changes are too far apart. If you > +specify a non-nil value for the @var{disjoint} argument, the library ^^^ And likewise. > +modified region, but if you specified a non-nil @var{nobefore} argument ^^^ And likewise. > +In case no changes occurred since the last call, > +@code{track-changes-fetch} simply does not call @var{func} and returns > +nil. If changes did occur, it calls @var{func} and returns the value ^^^ And likewise. > +Once @var{func} finishes, @code{track-changes-fetch} re-enables the > +@var{signal} function so that it will be called the next time a change > +occurs. This is the reason why it calls @var{func} instead of returning > +a description: it makes sure that the @var{signal} function will not be > +called while you're still processing past changes. I think there's a subtler issue here that needs to be described explicitly: if the entire processing of the change is not done inside FUNC, there's no guarantee that by the time some other function processes it, the change is still valid and in particular SIGNAL will not have been called again. This is not a trivial aspect, since a program can use FUNC to do just some partial processing, like squirrel the changes to some buffer for later processing. > * New Modes and Packages in Emacs 30.1 > > +** New package Track-Changes. This should be marked with "+++".