Obsolete the TAB binding in *xref* buffers

* doc/emacs/maintaining.texi (Xref Commands): Remove the
description of the TAB binding.  Enhance the description of the
RET binding.  (Bug#44611)

* etc/NEWS: Announce the obsolescence of TAB binding in XREF.

* lisp/progmodes/xref.el (xref-goto-xref): Improve doc string.

diff --git a/doc/emacs/maintaining.texi b/doc/emacs/maintaining.texi
index dfe4eb0ea302eb491b4e5e11a032b130da770354..880829aa5ad2f756ba43a7786a874adf58986e79 100644 (file)
--- a/doc/emacs/maintaining.texi
+++ b/doc/emacs/maintaining.texi
@@ -2213,7 +2213,8 @@ the special XREF mode:
 @table @kbd
 @item @key{RET}
 @itemx mouse-2
-Display the reference on the current line.
+Display the reference on the current line (@code{xref-goto-xref}).
+With prefix argument, also bury the @file{*xref*} buffer.
 
 @item n
 @itemx .
@@ -2242,11 +2243,6 @@ display it in the other window (@code{xref-prev-group}).
 Display the reference on the current line in the other window
 (@code{xref-show-location-at-point}).
 
-@item @key{TAB}
-@findex xref-quit-and-goto-xref
-Display the reference on the current line and bury the @file{*xref*}
-buffer (@code{xref-quit-and-goto-xref}).
-
 @item r @var{pattern} @key{RET} @var{replacement} @key{RET}
 Perform interactive query-replace on references that match
 @var{pattern} (@code{xref-query-replace-in-results}), replacing

diff --git a/etc/NEWS b/etc/NEWS
index 7d600eb374de077ffc0bdad500eb7aa63903753a..a246be3086fba09ee4df7530554ce16a89581979 100644 (file)
--- a/etc/NEWS
+++ b/etc/NEWS
@@ -1677,6 +1677,13 @@ choosing the exact definition to go to, and this should do TRT.
 If chosen, file names in "*xref*" buffers will be displayed relative
 to the 'project-root' of the current project, when available.
 
++++
+*** The TAB key binding in *xref* buffers is obsolete.
+The TAB binding in *xref* buffers is still supported, but we plan on
+removing it in a future version; at that time, the command
+'xref-quit-and-got-xref' will no longer have a key binding in
+'xref--xref-buffer-mode-map'.
+
 ** json.el
 
 ---

diff --git a/lisp/progmodes/xref.el b/lisp/progmodes/xref.el
index 63d25de50a7ed19502b7267dfed9c579c39866ce..e80603f23e77b04034babb934d2a8c7aef4f68c9 100644 (file)
--- a/lisp/progmodes/xref.el
+++ b/lisp/progmodes/xref.el
@@ -652,8 +652,8 @@ SELECT is `quit', also quit the *xref* window."
 
 (defun xref-goto-xref (&optional quit)
   "Jump to the xref on the current line and select its window.
-Non-interactively, non-nil QUIT, or interactively, with prefix argument
-means to first quit the *xref* buffer."
+If QUIT is non-nil (interactively, with prefix argument), also
+quit the *xref* buffer."
   (interactive "P")
   (let* ((buffer (current-buffer))
          (xref (or (xref--item-at-point)