From ae3a5adda7debf77e03c151b84c1062ae90b6970 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jo=C3=A3o=20T=C3=A1vora?= Date: Wed, 25 Oct 2017 19:27:15 +0100 Subject: [PATCH 4/4] Document changes to xref behavior in NEWS and texi manual (bug#28814) * doc/emacs/maintaining.texi (Looking Up Identifiers): Mention new bindings in *xref*, rework slightly to avoid repetition. (Xref Commands): Describe new bindings in *xref*. * etc/NEWS (Xref): New section describing bugfix and new bindings. --- doc/emacs/maintaining.texi | 52 ++++++++++++++++++++++++++-------------------- etc/NEWS | 20 ++++++++++++++++++ 2 files changed, 50 insertions(+), 22 deletions(-) diff --git a/doc/emacs/maintaining.texi b/doc/emacs/maintaining.texi index dc0a71511f..650419a855 100644 --- a/doc/emacs/maintaining.texi +++ b/doc/emacs/maintaining.texi @@ -1828,15 +1828,6 @@ Looking Up Identifiers to always prompt, customize @code{xref-prompt-for-identifier} to @code{t}.) -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 -variable by the same name), the command shows the candidate -definitions in a @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. - When entering the identifier argument to @kbd{M-.}, the usual minibuffer completion commands can be used (@pxref{Completion}), with the known identifier names as completion candidates. @@ -1860,21 +1851,34 @@ Looking Up Identifiers matching of identifiers instead of matching symbol names as fixed strings. - When any of the above commands finds more than one definition, it -presents the @file{*xref*} buffer showing the definition candidates. -In that buffer, you have several specialized commands, described in -@ref{Xref Commands}. +When any of these commands finds a unique definition for the specified +identifier, the command jumps to that location. If, however, the +identifier has more than one possible definition (e.g., in an +object-oriented language, or if there's a function and a variable by +the same name), the command shows the candidate definitions in a +@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. If you only want to display that buffer, but still remain +in @file{*xref*} window, you can also type @kbd{C-o} to do so. +Finally, if you're quite sure you're already at the definition you +want to jump to, you can press @kbd{@key{TAB}} to jump to the buffer +and dismiss the @file{*xref*} window. For a complete list of commands +available in this buffer, @ref{Xref Commands}. @kindex M-, @findex xref-pop-marker-stack @vindex xref-marker-ring-length - To go back to places @emph{from where} you found the definition, -use @kbd{M-,} (@code{xref-pop-marker-stack}). It jumps back to the -point of the last invocation of @kbd{M-.}. Thus you can find and -examine the definition of something with @kbd{M-.} and then return to -where you were with @kbd{M-,}. @kbd{M-,} allows you to retrace your -steps to a depth determined by the variable -@code{xref-marker-ring-length}, which defaults to 16. + Once you arrive at the desired definition, you may want to go back +to places @emph{from where} you found the definition. For this, use +@kbd{M-,} (@code{xref-pop-marker-stack}). It jumps back to the point +of the last invocation of @kbd{M-.}. Thus you can find and examine +the definition of something with @kbd{M-.} and then return to where +you were with @kbd{M-,}. @kbd{M-,} allows you to retrace your steps +to a depth determined by the variable @code{xref-marker-ring-length}, +which defaults to 16. @node Xref Commands @subsubsection Commands Available in the @file{*xref*} Buffer @@ -1887,8 +1891,7 @@ Xref Commands @table @kbd @item @key{RET} @itemx mouse-2 -Display the reference on the current line and bury the @file{*xref*} -buffer. +Display the reference on the current line. @item n @itemx . @findex xref-next-line @@ -1903,6 +1906,11 @@ Xref Commands @findex xref-show-location-at-point Display the reference on the current line in the other window (@code{xref-show-location-at-point}). +@item TAB +@itemx Q +@findex xref-quit-and-goto-xref +Display the reference on the current line and bury the @file{*xref*} +buffer (@code{xref-quit-and-goto-xref}). @findex xref-query-replace-in-results @item r @var{pattern} @key{RET} @var{replacement} @key{RET} Perform interactive query-replace on references that match diff --git a/etc/NEWS b/etc/NEWS index 82778932ab..b79a0019d8 100644 --- a/etc/NEWS +++ b/etc/NEWS @@ -1185,6 +1185,26 @@ New user options `term-char-mode-buffer-read-only' and are non-nil by default. Customize these options to nil if you want the previous behavior. +** Xref + +*** When an *xref* buffer is needed, window-switching intent is preserved + +This most visibly affects the commands +'xref-find-definitions-other-window' and +'xref-find-definitions-other-frame' bound to 'C-x 4 .' and 'C-x 5 .' +by default. When selecting a cross reference from the *xref* list, +Emacs remembers that the user's intention was keep the originally +selected window/frame's contents. Similarly, the original window is +always chosen by the regular 'xref-find-definitions' command, +regardless if an *xref* buffer is needed or not. + ++++ +*** New command 'xref-quit-and-goto-xref' quits and jumps to an xref + +This command is bound to 'Q' and 'TAB' by default. By quitting +the *xref* window, it makes space for new windows, just as if +the *xref* hadn't been necessary in the first place. + * New Modes and Packages in Emacs 26.1 -- 2.14.2