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

[Eshel Yaron]

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 :)