From mboxrd@z Thu Jan  1 00:00:00 1970
Path: news.gmane.io!.POSTED.blaine.gmane.org!not-for-mail
From: Eli Zaretskii <eliz@gnu.org>
Newsgroups: gmane.emacs.bugs
Subject: bug#68958: [PATCH] Support bookmarking Xref results buffers
Date: Wed, 07 Feb 2024 14:25:36 +0200
Message-ID: <86le7wzcjj.fsf@gnu.org>
References: <m1h6ilgxee.fsf@dazzs-mbp.home>
Injection-Info: ciao.gmane.io; posting-host="blaine.gmane.org:116.202.254.214";
	logging-data="13119"; mail-complaints-to="usenet@ciao.gmane.io"
Cc: dmitry@gutov.dev, 68958@debbugs.gnu.org
To: Eshel Yaron <me@eshelyaron.com>
Original-X-From: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane-mx.org@gnu.org Wed Feb 07 13:27:07 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 1rXh19-0003AW-B5
	for geb-bug-gnu-emacs@m.gmane-mx.org; Wed, 07 Feb 2024 13:27:07 +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 1rXh0v-0002As-Rd; Wed, 07 Feb 2024 07:26:54 -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 1rXh0s-0002AZ-N3
 for bug-gnu-emacs@gnu.org; Wed, 07 Feb 2024 07:26:51 -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 1rXh0q-0008UN-TP
 for bug-gnu-emacs@gnu.org; Wed, 07 Feb 2024 07:26:49 -0500
Original-Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.84_2)
 (envelope-from <Debian-debbugs@debbugs.gnu.org>) id 1rXh14-0006qh-Dc
 for bug-gnu-emacs@gnu.org; Wed, 07 Feb 2024 07:27:02 -0500
X-Loop: help-debbugs@gnu.org
Resent-From: Eli Zaretskii <eliz@gnu.org>
Original-Sender: "Debbugs-submit" <debbugs-submit-bounces@debbugs.gnu.org>
Resent-CC: bug-gnu-emacs@gnu.org
Resent-Date: Wed, 07 Feb 2024 12:27:02 +0000
Resent-Message-ID: <handler.68958.B68958.170730876526241@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.170730876526241
 (code B ref 68958); Wed, 07 Feb 2024 12:27:02 +0000
Original-Received: (at 68958) by debbugs.gnu.org; 7 Feb 2024 12:26:05 +0000
Original-Received: from localhost ([127.0.0.1]:55826 helo=debbugs.gnu.org)
 by debbugs.gnu.org with esmtp (Exim 4.84_2)
 (envelope-from <debbugs-submit-bounces@debbugs.gnu.org>)
 id 1rXh08-0006pB-Ip
 for submit@debbugs.gnu.org; Wed, 07 Feb 2024 07:26:05 -0500
Original-Received: from eggs.gnu.org ([2001:470:142:3::10]:52876)
 by debbugs.gnu.org with esmtp (Exim 4.84_2)
 (envelope-from <eliz@gnu.org>) id 1rXh03-0006oa-Ik
 for 68958@debbugs.gnu.org; Wed, 07 Feb 2024 07:26:03 -0500
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 <eliz@gnu.org>)
 id 1rXgzk-0008M4-6e; Wed, 07 Feb 2024 07:25:40 -0500
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=s6fIWV0EG2bn0bUkurH+IW69zsLFzXhuBkIwIY45ATI=; b=JhDS5ezioQ5/
 tqSrqEfahxDp66d+c9ZeqTHS2wJMSMVwWCThwi5DpSIf0b0X6pD0hhmcWWj07GjAneZSIErhGCqxQ
 /AYi6KDE2WOm/99mdkdSBoZgG4eWBJD0gHCD9n7rkfkmaxvBDJ95HRGnkAxuuZ80xP9TcUJ+TnOAF
 OVzs4wEM2B5An9SGDKd4jxBFtcIyB0WrMQpDNitTzXaFHzlCPGApMQpH8qmHKiaRfcYATLZ5bTFSZ
 VdnKEHiXSPvKTi4k0xMjzfMy74pFj1ajfMY1ZNe8pOgnEOGajNRa00xRwymj8ze+/ninWukN5BNlI
 Xum+zlFVki8J7gJ12oromg==;
In-Reply-To: <m1h6ilgxee.fsf@dazzs-mbp.home> (bug-gnu-emacs@gnu.org)
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:279541
Archived-At: <http://permalink.gmane.org/gmane.emacs.bugs/279541>

> Cc: Dmitry Gutov <dmitry@gutov.dev>
> Date: Tue, 06 Feb 2024 21:17:45 +0100
> From:  Eshel Yaron via "Bug reports for GNU Emacs,
>  the Swiss army knife of text editors" <bug-gnu-emacs@gnu.org>
> 
> This patch adds support for bookmarking "*xref*" buffers and restoring
> them later, even across Emacs sessions.
> 
> To make this happen, we need to propagate some more information to the
> "*xref*" buffer (and any other Xref fronted).  We do this, without
> breaking compatibility, by setting a new variable from inside the xrefs
> fetcher function.  The frontend can examine this variable to learn all
> about the source of the fetched xrefs after invoking the fetcher.
> Namely, the "*xref*" buffer uses this information to create bookmarks.

Thanks.  Frankly, I'm surprised we need such a complex changeset for
supporting such a simple extension, but I'll let Dmitry judge that.

> --- a/doc/emacs/maintaining.texi
> +++ b/doc/emacs/maintaining.texi
> @@ -2466,6 +2466,10 @@ Xref Commands
>  @kbd{C-n}, and @kbd{C-p} are available for moving around the buffer
>  without displaying the references.
>  
> +You can also bookmark the @file{*xref*} buffer with @kbd{C-x r m} and
> +restore it from the same state later by jumping to that bookmark with
> +@kbd{C-x r b}.  @xref{Bookmarks}.

Since "C-x r m" and "C-x r b" are bookmark commands, they should not
be described here; instead, its description in "Bookmarks" should
mention any special features related to the Xref buffers (not that I
see what is there to mention, but maybe I'm missing something).  If
you think this capability is worth mentioning in the "Xref Commands"
node, you should do it in passage, like

  You can bookmark and restore your place in @file{*xref*} buffers,
  see @ref{Bookmarks}.

> +** New Xref generic functions for recording and restoring context.
> +Xref backends can now implement the generic function
> +'xref-backend-context' to change how Xref records the context used for
> +fetching cross-references when bookmarking Xref results for later use.
> +In addition, the new generic function 'xref-backend-restore' lets
> +backends change how Xref then restores this context.

I'm not sure this is for NEWS.  Either expand the documentation, place
it in the ELisp manual, and just mention the function's name in NEWS,
or simply don't mention it in NEWS.