master 2ed2999: Improve documentation of new Xref options

[Eli Zaretskii]

branch: master
commit 2ed2999ce59bb404509dd7f319c00f4085427cde
Author: Eli Zaretskii <eliz@gnu.org>
Commit: Eli Zaretskii <eliz@gnu.org>

    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.
---
 doc/emacs/maintaining.texi | 14 +++++++++++++-
 etc/NEWS                   | 23 +++++++++++++++++------
 2 files changed, 30 insertions(+), 7 deletions(-)

diff --git a/doc/emacs/maintaining.texi b/doc/emacs/maintaining.texi
index 8c5d19d..db5e00c 100644
--- 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 91fc7df..55fbcf2 100644
--- 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
 
 ---
@@ -3938,11 +3954,6 @@ 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
 an error when invoked by input event that is not a mouse click (e.g.,