Improve documentation of new Xref options

* doc/emacs/maintaining.texi (Looking Up Identifiers):
* etc/NEWS: Document the new Xref user options.  Move a lost
Xref-related entry to the rest of them.

diff --git a/doc/emacs/maintaining.texi b/doc/emacs/maintaining.texi
index 8c5d19dcddf7ec7ce53039520b0ea3b5cdded6e3..db5e00c4aadbc350c2adfe5b271439379c344e97 100644 (file)
--- a/doc/emacs/maintaining.texi
+++ b/doc/emacs/maintaining.texi
@@ -2145,6 +2145,7 @@ identifier at point, it prompts for the identifier.  (If you want it
 to always prompt, customize @code{xref-prompt-for-identifier} to
 @code{t}.)
 
+@vindex xref-auto-jump-to-first-definition
 If the specified identifier has only one definition, the command jumps
 to it.  If the identifier has more than one possible definition (e.g.,
 in an object-oriented language, or if there's a function and a
@@ -2152,7 +2153,18 @@ variable by the same name), the command shows the candidate
 definitions in the @file{*xref*} buffer, together with the files in
 which these definitions are found.  Selecting one of these candidates
 by typing @kbd{@key{RET}} or clicking @kbd{mouse-2} will pop a buffer
-showing the corresponding definition.
+showing the corresponding definition.  If the value of the variable
+@code{xref-auto-jump-to-first-definition} is @code{move}, the first
+candidate is automatically selected, and if it's @code{t} or
+@code{show}, the first candidate is automatically shown.
+
+@vindex xref-auto-jump-to-first-xref
+  If the value of the variable @code{xref-auto-jump-to-first-xref} is
+@code{t}, @emph{all} Xref commands automatically jump to the first result.
+If the value is @code{show}, the first result is shown, but the window
+showing the @file{*xref*} buffer is left selected.  If the value is
+@code{move}, the first result is selected in the @file{*xref*} buffer,
+but is not shown.
 
   When entering the identifier argument to @kbd{M-.}, the usual
 minibuffer completion commands can be used (@pxref{Completion}), with

diff --git a/etc/NEWS b/etc/NEWS
index 91fc7df91b880c3fda2f25f3be3b4620da78e09b..55fbcf2b64507929d3a4ba6ed9f50f5bebdf72f1 100644 (file)
--- a/etc/NEWS
+++ b/etc/NEWS
@@ -2152,13 +2152,24 @@ sub-directory.
 *** 'project-find-file' doesn't use the string at point as default input.
 Now it's only suggested as part of the "future history".
 
-** xref
+** Xref
 
 ---
 *** Prefix arg of 'xref-goto-xref' quits the "*xref*" buffer.
 So typing 'C-u RET' in the "*xref*" buffer quits its window
 before navigating to the selected location.
 
++++
+*** New user options to automatically show the first Xref match.
+The new option 'xref-auto-jump-to-first-definition' controls the
+behavior of 'xref-find-definitions' and related commands: if it's t or
+'show', the first match is automatically displayed; if it's 'move',
+point in the *xref* buffer is automatically moved to the first match
+without displaying it.
+The new option 'xref-auto-jump-to-first-xref' changes the behavior of
+all Xref commands in the same way as 'xref-auto-jump-to-first-definition'
+affects the "find-definitions" commands.
+
 *** New user options 'xref-search-program' and 'xref-search-program-alist'.
 So far 'grep' and 'ripgrep' are supported.  'ripgrep' seems to offer better
 performance in certain cases, in particular for case-insensitive
@@ -2194,6 +2205,11 @@ supported, but we plan on removing it in a future version; at that
 time, the command 'xref-quit-and-goto-xref' will no longer have a key
 binding in 'xref--xref-buffer-mode-map'.
 
+---
+*** New user option 'etags-xref-prefer-current-file'.
+When non-nil, 'M-.' matches for identifiers in the file visited by the
+current buffer will be shown first in the "*xref*" buffer.
+
 ** json.el
 
 ---
@@ -3937,11 +3953,6 @@ unsaved changes, but this has apparently not worked for several
 decades, so the documented semantics of this variable has been changed
 to match the behaviour.)
 
----
-** New user option 'etags-xref-prefer-current-file'.
-When non-nil, matches for identifiers in the file visited by the
-current buffer will be shown first in the "*xref*" buffer.
-
 ---
 ** New variable 'inhibit-mouse-event-check'.
 If bound to non-nil, a command with '(interactive "e")' doesn't signal