From 2ed2999ce59bb404509dd7f319c00f4085427cde Mon Sep 17 00:00:00 2001 From: Eli Zaretskii Date: Sun, 5 Sep 2021 10:59:07 +0300 Subject: [PATCH] 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 8c5d19dcddf..db5e00c4aad 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 91fc7df91b8..55fbcf2b645 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 --- @@ -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 -- 2.39.2