From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.io!.POSTED.blaine.gmane.org!not-for-mail From: Stefan Monnier via "Bug reports for GNU Emacs, the Swiss army knife of text editors" Newsgroups: gmane.emacs.bugs Subject: bug#70077: An easier way to track buffer changes Date: Mon, 08 Apr 2024 13:17:37 -0400 Message-ID: References: <86frvy51af.fsf@gnu.org> <86msq3yhot.fsf@gnu.org> Reply-To: Stefan Monnier Mime-Version: 1.0 Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: quoted-printable Injection-Info: ciao.gmane.io; posting-host="blaine.gmane.org:116.202.254.214"; logging-data="38831"; mail-complaints-to="usenet@ciao.gmane.io" User-Agent: Gnus/5.13 (Gnus v5.13) Cc: acm@muc.de, yantar92@posteo.net, 70077@debbugs.gnu.org To: Eli Zaretskii Original-X-From: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane-mx.org@gnu.org Mon Apr 08 19:18:20 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 1rtsdP-0009uH-4y for geb-bug-gnu-emacs@m.gmane-mx.org; Mon, 08 Apr 2024 19:18:19 +0200 Original-Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1rtsd4-0003XB-OQ; Mon, 08 Apr 2024 13:17:58 -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 1rtsd2-0003Ww-JZ for bug-gnu-emacs@gnu.org; Mon, 08 Apr 2024 13:17:56 -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 1rtsd2-0007BA-Bg for bug-gnu-emacs@gnu.org; Mon, 08 Apr 2024 13:17:56 -0400 Original-Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.84_2) (envelope-from ) id 1rtsd9-0006Zh-OV for bug-gnu-emacs@gnu.org; Mon, 08 Apr 2024 13:18:03 -0400 X-Loop: help-debbugs@gnu.org Resent-From: Stefan Monnier Original-Sender: "Debbugs-submit" Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Mon, 08 Apr 2024 17:18:03 +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.171259667925244 (code B ref 70077); Mon, 08 Apr 2024 17:18:03 +0000 Original-Received: (at 70077) by debbugs.gnu.org; 8 Apr 2024 17:17:59 +0000 Original-Received: from localhost ([127.0.0.1]:47538 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1rtsd5-0006Z5-65 for submit@debbugs.gnu.org; Mon, 08 Apr 2024 13:17:59 -0400 Original-Received: from mailscanner.iro.umontreal.ca ([132.204.25.50]:36878) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1rtsd1-0006Yj-1e for 70077@debbugs.gnu.org; Mon, 08 Apr 2024 13:17:58 -0400 Original-Received: from pmg1.iro.umontreal.ca (localhost.localdomain [127.0.0.1]) by pmg1.iro.umontreal.ca (Proxmox) with ESMTP id 386E21000DD; Mon, 8 Apr 2024 13:17:41 -0400 (EDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=iro.umontreal.ca; s=mail; t=1712596660; bh=xGWypuhh6SbD6ZvI4IwvfhQ+fbQU9hlauG6lKdXLz9w=; h=From:To:Cc:Subject:In-Reply-To:References:Date:From; b=QR42H4bZV1p907abQXrasSZiQVEOFjoDJqQvqlxI1vzy8HtiRl/attQqsmIv2PHsa usM13qPvXi57s7Ct0JhcqB3mmAD2ZBuV90B+1V6H2HlxvrQY5iGWppyPjVIM+lcbDG eKN74zq/5dYqbpzZs9NO1rbC2U/lYXVuhz89mVecpS71arZk8nmT97qRCQ8N2338VK Gqde0pU3AgJDx0BNsb2ScbTuiJUDaaWsZlqQXWSc2WXm6sRlgwonfDFnntsNHAitXH XhMdBNHf4+rrJeBTyCsMKr1aWo/mHXU7OZVWvd/8BsETV5lMv5TV37KyrFwfdaGmoO CdloiK11Cuvlg== Original-Received: from mail01.iro.umontreal.ca (unknown [172.31.2.1]) by pmg1.iro.umontreal.ca (Proxmox) with ESMTP id 3A25C100048; Mon, 8 Apr 2024 13:17:40 -0400 (EDT) Original-Received: from pastel (unknown [45.72.201.215]) by mail01.iro.umontreal.ca (Postfix) with ESMTPSA id 0F79B1202A2; Mon, 8 Apr 2024 13:17:40 -0400 (EDT) In-Reply-To: <86msq3yhot.fsf@gnu.org> (Eli Zaretskii's message of "Mon, 08 Apr 2024 18:53:22 +0300") 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:282947 Archived-At: >> Maybe `describe-type` should lists the slots first and the docstring >> underneath rather than other way around? > > That'd also be good. Then the doc string should say something like > > Object holding a description of a buffer state. > It has the following Allocated Slots: > > Name Type Default > =E2=80=94=E2=80=94=E2=80=94=E2=80=94 =E2=80=94=E2=80=94=E2= =80=94=E2=80=94 =E2=80=94=E2=80=94=E2=80=94=E2=80=94=E2=80=94=E2=80=94= =E2=80=94 > beg t (point-max) > end t (point-min) > before t nil > next t nil > > BEG..END is the area that was changed and BEFORE is its previous > content[...] OK, I'll switch the two, thanks. > (Btw, those "t" under "Type" are also somewhat mysterious. What do > they signify?) `C-h o t RET` says: t=E2=80=99s value is t =20=20=20=20 Not documented as a variable. =20=20=20=20 Probably introduced at or before Emacs version 16. =20=20=20=20 =20=20=20=20 =20=20=20=20 t is also a type. =20=20=20=20 t is a type (of kind =E2=80=98built-in-class=E2=80=99). Children =E2=80=98sequence=E2=80=99, =E2=80=98atom=E2=80=99. =20=20=20=20 Abstract supertype of everything. =20=20=20=20 This is a built-in type. =20=20=20=20 [back] We could put buttons in the "Type" column, but I'm not sure it'd be better or worse (I'm worried about turning everything into a button). >> >> +(cl-defun track-changes-register ( signal &key nobefore disjoint imm= ediate) >> >> + "Register a new tracker and return a new tracker ID. >> > Please mention SIGNAL in the first line of the doc string. >> Hmm... having trouble making that fit on a single line. > Register a new tracker whose change-tracking function is SIGNAL. > Return the ID of the new tracker. Thanks. >> >> +By default SIGNAL is called as soon as convenient after a change, wh= ich is >> > ^^^^^^^^^^^^^^^^^^^^^ >> > "as soon as it's convenient", I presume? >> Other than the extra " it's", what is the difference? > Nothing. I indeed thing "it's" is missing there. My local native-English representative says that "both work fine" (somewhat dismissively, I must add). > My point is that by referencing funcall-later you can avoid the need > to explain what is already explained in that function's doc string. OK. >> >> +In order to prevent the upcoming change from being combined with the= previous >> >> +changes, SIGNAL needs to call `track-changes-fetch' before it return= s." >> > >> > This seems to contradict what the doc string says previously: that >> > SIGNAL should NOT call track-changes-fetch. >>=20 >> I don't kow where you see the docstring saying that. >> The closest I can find is: >>=20 >> When IMMEDIATE is non-nil, the SIGNAL should preferably not always c= all >> `track-changes-fetch', since that would defeat the purpose of this l= ibrary. >>=20 >> Note the "When IMMEDIATE is non-nil", "preferably", and "not always", >> and the fact that the reason is not that something will break but that >> some other solution would probably work better. > > Then maybe the sentence on which I commented should say > > Except when IMMEDIATE is non-nil, if SIGNAL needs to prevent the > upcoming change from being combined with the previous ones, it > should call `track-changes-fetch' before it returns. But that wouldn't say what I want to say. It'd want to call `track-changes-fetch' before it returns even if IMMEDIATE is non-nil. It just probably wouldn't want to do that for all calls to the signal. E.g. only for those calls where the second argument is non-nil (i.e. the disjointness signals). > In general, when I want to create a clean slate, I don't care too much > about the dirt I remove. Why is it important to signal errors because > a state I am dumping had some errors? I don't understand why you think it will signal an error? More to the point, it should signal an error only if I made a mistake in `track-changes.el` or if you messed with the internals. Note also that this function is itself internal. >> >> +;;;; Extra candidates for the API. >> >> +;; This could be a good alternative to using a temp-buffer like I us= ed in >> > ^^^= ^^^ >> > "I"? >> Yes, that refers to the code I wrote. > We don't usually leave such style in long-term comments and > documentation. `grep " I " lisp/**/*.el` suggests otherwise. Stefan