From 03dcceeeeeda6cefe4c0a79be328dd44b289b20b Mon Sep 17 00:00:00 2001
From: Lars Ingebrigtsen <larsi@gnus.org>
Date: Tue, 31 Aug 2021 04:50:18 +0200
Subject: [PATCH] Rename xref--mouse-2 and adjust documentation

* doc/emacs/maintaining.texi (Xref Commands): `mouse-1' is bound
to `xref-goto-xref', not `mouse-2' (bug#35376).
(Xref Commands): Mention what `mouse-2' does.

* lisp/progmodes/xref.el (xref--button-map): Adjust.
(xref-select-and-goto-xref): Rename from xref--mouse-2 (bug#35376).
---
 doc/emacs/maintaining.texi | 7 ++++++-
 lisp/progmodes/xref.el     | 9 ++++++---
 2 files changed, 12 insertions(+), 4 deletions(-)

diff --git a/doc/emacs/maintaining.texi b/doc/emacs/maintaining.texi
index 3205e6dbdf7..008639d1a9a 100644
--- a/doc/emacs/maintaining.texi
+++ b/doc/emacs/maintaining.texi
@@ -2218,10 +2218,15 @@ the special XREF mode:
 
 @table @kbd
 @item @key{RET}
-@itemx mouse-2
+@itemx mouse-1
 Display the reference on the current line (@code{xref-goto-xref}).
 With prefix argument, also bury the @file{*xref*} buffer.
 
+@item mouse-2
+The same as @code{mouse-1}, but make the window displaying the
+@file{*xref*} buffer the selected window
+(@code{xref-select-and-goto-xref}).
+
 @item n
 @itemx .
 @findex xref-next-line
diff --git a/lisp/progmodes/xref.el b/lisp/progmodes/xref.el
index d004a0c32c5..d495a4e2926 100644
--- a/lisp/progmodes/xref.el
+++ b/lisp/progmodes/xref.el
@@ -898,17 +898,20 @@ beginning of the line."
 (defvar xref--button-map
   (let ((map (make-sparse-keymap)))
     (define-key map [mouse-1] #'xref-goto-xref)
-    (define-key map [mouse-2] #'xref--mouse-2)
+    (define-key map [mouse-2] #'xref-select-and-goto-xref)
     map))
 
-(defun xref--mouse-2 (event)
-  "Move point to the button and show the xref definition."
+(defun xref-select-and-goto-xref (event)
+  "Move point to the button and show the xref definition.
+The window showing the xref buffer will be selected."
   (interactive "e")
   (mouse-set-point event)
   (forward-line 0)
   (or (get-text-property (point) 'xref-item)
       (xref--search-property 'xref-item))
   (xref-show-location-at-point))
+(define-obsolete-function-alias
+  'xref--mouse-2 #'xref-select-and-goto-xref "28.1")
 
 (defcustom xref-truncation-width 400
   "The column to visually \"truncate\" each Xref buffer line to."
-- 
2.39.2