From d753b39096320b45ba3414272f4445587f4e6e7f Mon Sep 17 00:00:00 2001
From: Eli Zaretskii <eliz@gnu.org>
Date: Sat, 24 Apr 2021 12:54:44 +0300
Subject: [PATCH] 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.
---
 doc/emacs/maintaining.texi | 8 ++------
 etc/NEWS                   | 7 +++++++
 lisp/progmodes/xref.el     | 4 ++--
 3 files changed, 11 insertions(+), 8 deletions(-)

diff --git a/doc/emacs/maintaining.texi b/doc/emacs/maintaining.texi
index dfe4eb0ea30..880829aa5ad 100644
--- 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 7d600eb374d..a246be3086f 100644
--- 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 63d25de50a7..e80603f23e7 100644
--- 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)
-- 
2.39.5