From b02c9bccebb47ae83bfcca03d3f97db397861568 Mon Sep 17 00:00:00 2001 From: Eli Zaretskii Date: Tue, 7 Sep 2021 16:03:27 +0300 Subject: [PATCH] Improve documentation of new Xref options * lisp/progmodes/xref.el (xref-auto-jump-to-first-definition) (xref-auto-jump-to-first-xref): More accurate description in the doc strings. * doc/emacs/maintaining.texi (Looking Up Identifiers) (Identifier Search, List Identifiers, Project File Commands): Fix the documentation of 'xref-auto-jump-to-first-definition' and 'xref-auto-jump-to-first-xref' to be more accurate. * etc/NEWS: More accurate wording of the entry about 'xref-auto-jump-to-first-definition' and 'xref-auto-jump-to-first-xref'. --- doc/emacs/maintaining.texi | 44 +++++++++++++++++++++----------------- etc/NEWS | 19 ++++++++++------ lisp/progmodes/xref.el | 13 +++++++---- 3 files changed, 45 insertions(+), 31 deletions(-) diff --git a/doc/emacs/maintaining.texi b/doc/emacs/maintaining.texi index 5b33c9bd3e3..578ef0c716c 100644 --- a/doc/emacs/maintaining.texi +++ b/doc/emacs/maintaining.texi @@ -1747,10 +1747,12 @@ commands (@pxref{Xref Commands}). When invoked with a prefix argument, this command additionally prompts for the base directory from which to start the search; this allows, for example, to limit the search only to project files under a certain subdirectory of the -project root. +project root. The way this command displays the matches is affected +by the value of @code{xref-auto-jump-to-first-xref} (@pxref{Identifier +Search}). @findex project-search - @kbd{M-x project-search} is an interactive variant of + @kbd{M-x project-search} is an incremental variant of @code{project-find-regexp}. It prompts for a regular expression to search in the current project's files, but instead of finding all the matches and displaying them, it stops when it finds a match and visits @@ -2155,20 +2157,11 @@ 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. 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. The default -value is @code{nil}, which just shows the candidates in the -@file{*xref*} buffer, but doesn't select any of them. - -@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. The default value is -@code{nil}, which just shows the results in the @file{*xref*} buffer, -but doesn't select any of them. +of these candidates is automatically selected, and if it's @code{t} or +@code{show}, the first candidate is automatically shown; @code{t} also +selects the window showing the first candidate. The default value is +@code{nil}, which just shows the candidates in the @file{*xref*} +buffer, but doesn't select any of them. When entering the identifier argument to @kbd{M-.}, the usual minibuffer completion commands can be used (@pxref{Completion}), with @@ -2337,6 +2330,16 @@ identifier, showing the file name and the line where the identifier is referenced. The XREF mode commands are available in this buffer, see @ref{Xref Commands}. +@vindex xref-auto-jump-to-first-xref + If the value of the variable @code{xref-auto-jump-to-first-xref} is +@code{t}, @code{xref-find-references} automatically jumps to the first +result and selects the window where it is displayed. 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. The default value is @code{nil}, which just shows the results +in the @file{*xref*} buffer, but doesn't select any of them. + @findex xref-query-replace-in-results @kbd{M-x xref-query-replace-in-results} reads a regexp to match identifier names and a replacement string, just like ordinary @kbd{M-x @@ -2409,6 +2412,8 @@ selected tags table if one is loaded (@code{completion-at-point}). @item M-x xref-find-apropos @key{RET} @var{regexp} @key{RET} Display a list of all known identifiers matching @var{regexp}. +The way this command displays the matches is affected by the value of +@code{xref-auto-jump-to-first-xref} (@pxref{Identifier Search}). @item M-x list-tags @key{RET} @var{file} @key{RET} Display a list of the identifiers defined in the program file @@ -2435,10 +2440,9 @@ for the project to be available. @xref{Tags Tables}. If used interactively, the default tag is file name of the current buffer if used interactively. -@c Sadly, the new-and-improved Xref feature doesn't provide anything -@c close to the described below features of the now-obsoleted -@c tags-apropos. I'm leaving this here to encourage enhancements to -@c xref.el. +@c Sadly, the new-and-improved Xref feature doesn't provide some +@c of the features of the now-obsoleted tags-apropos. I'm leaving +@c this here to encourage enhancements to xref.el. @ignore @findex tags-apropos @vindex tags-apropos-verbose diff --git a/etc/NEWS b/etc/NEWS index 38a5749ec2b..52a1443c162 100644 --- a/etc/NEWS +++ b/etc/NEWS @@ -2309,13 +2309,18 @@ before navigating to the selected location. +++ *** New user options to automatically show the first Xref match. The new user 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 user 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. +behavior of 'xref-find-definitions' and related commands, like +'xref-find-definitions-other-windo': 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 user option 'xref-auto-jump-to-first-xref' changes the +behavior of Xref commands such as 'xref-find-references', +'xref-find-apropos', and 'project-find-regexp', which are expected to +display many match that the user would like to +visit. 'xref-auto-jump-to-first-xref' changes their behavior muuch 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 diff --git a/lisp/progmodes/xref.el b/lisp/progmodes/xref.el index d022baaf04c..f6d88e13cc0 100644 --- a/lisp/progmodes/xref.el +++ b/lisp/progmodes/xref.el @@ -420,7 +420,9 @@ elements is negated: these commands will NOT prompt." "If t, `xref-find-definitions' always jumps to the first result. `show' means to show the first result's location, but keep the focus on the Xref buffer's window. -`move' means to only move point to the first result." +`move' means to only move point to the first result. +This variable also affects commands similar to `xref-find-definitions', +such as `xref-find-definitions-other-window'." :type '(choice (const :tag "Jump" t) (const :tag "Show" show) (const :tag "Move point only" move) @@ -429,13 +431,16 @@ focus on the Xref buffer's window. :package-version '(xref . "1.2.0")) (defcustom xref-auto-jump-to-first-xref nil - "If t, xref commands always jump to the first result. + "If t, `xref-find-references' always jumps to the first result. `show' means to show the first result's location, but keep the focus on the Xref buffer's window. `move' means to only move point to the first result. +This variable also affects commands similar to `xref-find-definitions', +such as `xref-find-references-at-mouse', `xref-find-apropos', +and `project-find-regexp'. -Please be careful changing this value if you are using Emacs 27 -or earlier: it can break dired-do-find-regexp-and-replace." +Please be careful when changing the value if you are using Emacs 27 +or earlier: it can break `dired-do-find-regexp-and-replace'." :type '(choice (const :tag "Jump" t) (const :tag "Show" show) (const :tag "Move point only" move) -- 2.39.2