From mboxrd@z Thu Jan  1 00:00:00 1970
Path: news.gmane.io!.POSTED.blaine.gmane.org!not-for-mail
From: Eshel Yaron via "Bug reports for GNU Emacs,
 the Swiss army knife of text editors" <bug-gnu-emacs@gnu.org>
Newsgroups: gmane.emacs.bugs
Subject: bug#68958: [PATCH] Support bookmarking Xref results buffers
Date: Sun, 11 Feb 2024 12:13:40 +0100
Message-ID: <m1r0hj2qzf.fsf@dazzs-mbp.home>
References: <m1h6ilgxee.fsf@dazzs-mbp.home> <86le7wzcjj.fsf@gnu.org>
 <0b3f4669-180e-466f-96f3-7eeae994581f@gutov.dev>
 <m1cyt35xrj.fsf@dazzs-mbp.home>
Reply-To: Eshel Yaron <me@eshelyaron.com>
Mime-Version: 1.0
Content-Type: text/plain
Injection-Info: ciao.gmane.io; posting-host="blaine.gmane.org:116.202.254.214";
	logging-data="17448"; mail-complaints-to="usenet@ciao.gmane.io"
User-Agent: Gnus/5.13 (Gnus v5.13)
Cc: Eli Zaretskii <eliz@gnu.org>, 68958@debbugs.gnu.org
To: Dmitry Gutov <dmitry@gutov.dev>
Original-X-From: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane-mx.org@gnu.org Sun Feb 11 12:23:11 2024
Return-path: <bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane-mx.org@gnu.org>
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 <bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane-mx.org@gnu.org>)
	id 1rZ7vT-0004Iq-4R
	for geb-bug-gnu-emacs@m.gmane-mx.org; Sun, 11 Feb 2024 12:23:11 +0100
Original-Received: from localhost ([::1] helo=lists1p.gnu.org)
	by lists.gnu.org with esmtp (Exim 4.90_1)
	(envelope-from <bug-gnu-emacs-bounces@gnu.org>)
	id 1rZ7v6-00024D-G5; Sun, 11 Feb 2024 06:22:48 -0500
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 <Debian-debbugs@debbugs.gnu.org>)
 id 1rZ7v4-00023k-9g
 for bug-gnu-emacs@gnu.org; Sun, 11 Feb 2024 06:22:46 -0500
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 <Debian-debbugs@debbugs.gnu.org>)
 id 1rZ7v4-0001si-1L
 for bug-gnu-emacs@gnu.org; Sun, 11 Feb 2024 06:22:46 -0500
Original-Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.84_2)
 (envelope-from <Debian-debbugs@debbugs.gnu.org>) id 1rZ7vJ-0006nJ-Sj
 for bug-gnu-emacs@gnu.org; Sun, 11 Feb 2024 06:23:01 -0500
X-Loop: help-debbugs@gnu.org
Resent-From: Eshel Yaron <me@eshelyaron.com>
Original-Sender: "Debbugs-submit" <debbugs-submit-bounces@debbugs.gnu.org>
Resent-CC: bug-gnu-emacs@gnu.org
Resent-Date: Sun, 11 Feb 2024 11:23:01 +0000
Resent-Message-ID: <handler.68958.B68958.170765057726102@debbugs.gnu.org>
Resent-Sender: help-debbugs@gnu.org
X-GNU-PR-Message: followup 68958
X-GNU-PR-Package: emacs
X-GNU-PR-Keywords: patch
Original-Received: via spool by 68958-submit@debbugs.gnu.org id=B68958.170765057726102
 (code B ref 68958); Sun, 11 Feb 2024 11:23:01 +0000
Original-Received: (at 68958) by debbugs.gnu.org; 11 Feb 2024 11:22:57 +0000
Original-Received: from localhost ([127.0.0.1]:40325 helo=debbugs.gnu.org)
 by debbugs.gnu.org with esmtp (Exim 4.84_2)
 (envelope-from <debbugs-submit-bounces@debbugs.gnu.org>)
 id 1rZ7vE-0006mv-Rn
 for submit@debbugs.gnu.org; Sun, 11 Feb 2024 06:22:57 -0500
Original-Received: from mail.eshelyaron.com ([107.175.124.16]:49466 helo=eshelyaron.com)
 by debbugs.gnu.org with esmtp (Exim 4.84_2)
 (envelope-from <me@eshelyaron.com>) id 1rZ7uy-0006m6-37
 for 68958@debbugs.gnu.org; Sun, 11 Feb 2024 06:22:55 -0500
DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=eshelyaron.com;
 s=mail; t=1707650023;
 bh=xg/m9qIqCDgejKVl2K5z2LZow8YXl1/tvG7IBKec6wE=;
 h=From:To:Cc:Subject:In-Reply-To:References:Date:From;
 b=jfDHG7QLhYeR+5k2t45BTZN3RUcsnUUPyWB8Dl4Yw6PbdamnWfCIvbwjK2JPxz519
 EqMFB5BWM6u36xu9PSyB0H4ehn+Eb0dMXeGznB8BhfU8KXO3TxfPThd6Oco5MhTFmW
 9VzeQeiEjdc7KlMpuBGAvxwQqQq7XgdMmmXXp8Jd23t/x69B312zGyXu6TCK7OIAAc
 Zyj+pAWXZ10wN4cpLjIA3LIKYgySCYBlkA0XkcSNqBBLcMn0X72ATcrwwDOl3bi6/F
 1F5Vo5eQiBwRlmhkmnaSSDQ3emVolGa4gtuwBGLo1rULk9pdaigFMuQK/KLcJ3XdFu
 Rc4SYrXppFi8A==
In-Reply-To: <m1cyt35xrj.fsf@dazzs-mbp.home> (Eshel Yaron's message of "Sun,
 11 Feb 2024 07:18:56 +0100")
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" <bug-gnu-emacs.gnu.org>
List-Unsubscribe: <https://lists.gnu.org/mailman/options/bug-gnu-emacs>,
 <mailto:bug-gnu-emacs-request@gnu.org?subject=unsubscribe>
List-Archive: <https://lists.gnu.org/archive/html/bug-gnu-emacs>
List-Post: <mailto:bug-gnu-emacs@gnu.org>
List-Help: <mailto:bug-gnu-emacs-request@gnu.org?subject=help>
List-Subscribe: <https://lists.gnu.org/mailman/listinfo/bug-gnu-emacs>,
 <mailto:bug-gnu-emacs-request@gnu.org?subject=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:279832
Archived-At: <http://permalink.gmane.org/gmane.emacs.bugs/279832>

I wrote:

> Dmitry Gutov <dmitry@gutov.dev> writes:
>
>> A lot of changes seem to stem from the desire to add detailed info
>> into the bookmarks's name (including the identifier being searched,
>> the search type, and the xref backend in use).
>
> That's not the case.  The changes are all meant to facilitate creating
> bookmarks that you can restore at a later session.  AFAICT the backend,
> identifier and search type (kind) are a required for that, no?  We use
> them to suggest a meaningful bookmark name, but that's just a bonus.
>
>> At the moment our code doesn't save all of those separately, just
>> combines them in xref--fetcher.
>>
>> So whether the patch has to be complex would depend on whether we
>> really need to have bookmark names look exactly like proposed. Though
>> I'd rewrite it a little even in that case.
>
> Again, the name of the bookmark is really not the focus here.  We can't
> persist the value of xref--fetcher, since it's an anonymous function, so
> we get all the info needed to /recreate/ that function to the frontend.
> If there's another (simpler?) way to provide this feature, please do tell.

Perhaps I can explain the reasoning behind this patch a little better:

The goal is to be able to persistently save (bookmark) your state in an
*xref* results buffer, perhaps as part of a long refactoring effort for
some code base, and restore it later, perhaps in another Emacs session.

Basically we want the following to work:

1. Use M-? to get a list of references in the *xref* buffer.
2. Do something with some of them, but not all.
3. Hit C-x r m to bookmark your position.
4. Quit the *xref* buffer, and close Emacs.
5. Open Emacs again, type C-x r b and select a bookmark to get an *xref* buffer
   corresponding to the same search as before, with point on the same
   reference that you where on when you created the bookmark, if possible.

Crucially, looking at step 3, we need to have the data needed to create
such a persistent bookmark available in the *xref* buffer, long after
the execution of the command that created this buffer.  So, what data do
we need?  IIUC, to replicate the saved search we need to invoke the same
backend, with the same type of search, for the same input.  Since Xref
backends may (and do) use the position of point and other buffer context
to guide the search, we want to preserve and restore that extra context
as well.

So in this patch, we add the new xref-fetcher-alist variable that allows
the fetcher function to communicate all this information to the
frontend, so when we create the *xref* buffer we can store it in
buffer-local variables, and then use them to create a bookmark record
when the user types C-x r m.  This record includes all of the data
needed to perform the same Xref search in a new Emacs session, and in
most cases to get back to same position.  We also let the backend
override what extra context exactly gets saved and restored, and how.

Hope this makes it clearer :)