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

[Eli Zaretskii <eliz@gnu.org>]

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