bug#68958: [PATCH] Support bookmarking Xref results buffers

[Eshel Yaron]

Eli Zaretskii <eliz@gnu.org> writes:

>> 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.

Thanks for taking a look.

It's a simple extension, but unless I'm missing something in the code,
the Xref infrastructure needs these extra tweaks to accommodate for it.

>> --- 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}.

That makes sense.  I updated the text accordingly in the attached patch.

>> +** 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.

All right, I removed this bit.

Here's the updated patch (v2):

v2-0001-Support-bookmarking-Xref-results-buffers.patch
Description: Text Data