bug#35737: xref--original-command

bug#35737: xref--original-command

[Juri Linkov]

Remembering the command that created the *xref* buffer
will allow such customization to treat RET differently,
i.e. it makes sense for RET to quit the transient xref buffer
displayed momentarily while navigating code with xref-find-definitions,
whereas leaving the xref buffer visible while navigating matches
in the xref buffer created by e.g. project-find-regexp:

(define-key xref--button-map [(control ?m)]
  (lambda ()
    (interactive)
    (if (memq xref--original-command '(xref-find-definitions))
        (call-interactively 'xref-quit-and-goto-xref)
      (call-interactively 'xref-goto-xref))))

Better ideas?

diff --git a/lisp/progmodes/xref.el b/lisp/progmodes/xref.el
index bf999aeb0d..5c38cac164 100644
--- a/lisp/progmodes/xref.el
+++ b/lisp/progmodes/xref.el
@@ -477,6 +477,9 @@ xref--original-window-intent
 (defvar-local xref--original-window nil
   "The original window this xref buffer was created from.")
 
+(defvar-local xref--original-command nil
+  "The original command that created this xref buffer.")
+
 (defun xref--show-pos-in-buf (pos buf)
   "Goto and display position POS of buffer BUF in a window.
 Honor `xref--original-window-intent', run `xref-after-jump-hook'
@@ -777,7 +788,8 @@ xref--analyze
         (pop-to-buffer (current-buffer))
         (goto-char (point-min))
         (setq xref--original-window (assoc-default 'window alist)
-              xref--original-window-intent (assoc-default 'display-action alist))
+              xref--original-window-intent (assoc-default 'display-action alist)
+              xref--original-command this-command)
         (current-buffer)))))
 

bug#35737: xref--original-command

[Dmitry Gutov]

On 14.05.2019 23:53, Juri Linkov wrote:
> Remembering the command that created the *xref* buffer
> will allow such customization to treat RET differently,
> i.e. it makes sense for RET to quit the transient xref buffer
> displayed momentarily while navigating code with xref-find-definitions,
> whereas leaving the xref buffer visible while navigating matches
> in the xref buffer created by e.g. project-find-regexp:
> 
> (define-key xref--button-map [(control ?m)]
>    (lambda ()
>      (interactive)
>      (if (memq xref--original-command '(xref-find-definitions))
>          (call-interactively 'xref-quit-and-goto-xref)
>        (call-interactively 'xref-goto-xref))))

I'm all for customizability, but as I said in a past discussion on the 
subject, I don't think this by itself would be a good default behavior.

Having two buffers that looks basically the same but react to RET 
differently is not great for usability.

> Better ideas?

Ideally, the "transient" buffer should look differently from the 
"persistent" one.

To take VS Code as an example (I just to see how it behaves exactly), a 
search for references opens search results in the sidebar.

Whereas for definitions they have both "Go To Definition" and "Peek 
Definition". The latter shows the definitions kind of inline, in a 
not-exactly-a-popup kind of way 
(https://stackoverflow.com/questions/55599177/go-to-definition-in-vscode-preview-window-ruins-the-edito), 
and there, if you type RET, that triggers navigation to the selected 
definition. "Go To Definition", when there are several definitions, also 
switches to "Peek" mode by default.

Not sure how best to implement this different kind of display in Emacs, 
but the idea makes a lot of sense to me.

In Sublime, IIRC, for this they used the dropdown from their 
top-of-the-window command line, the same one that becomes active once 
one presses Ctrl-P.

> diff --git a/lisp/progmodes/xref.el b/lisp/progmodes/xref.el
> index bf999aeb0d..5c38cac164 100644
> --- a/lisp/progmodes/xref.el
> +++ b/lisp/progmodes/xref.el
> @@ -477,6 +477,9 @@ xref--original-window-intent
>   (defvar-local xref--original-window nil
>     "The original window this xref buffer was created from.")
>   
> +(defvar-local xref--original-command nil
> +  "The original command that created this xref buffer.")
> +
>   (defun xref--show-pos-in-buf (pos buf)
>     "Goto and display position POS of buffer BUF in a window.
>   Honor `xref--original-window-intent', run `xref-after-jump-hook'
> @@ -777,7 +788,8 @@ xref--analyze
>           (pop-to-buffer (current-buffer))
>           (goto-char (point-min))
>           (setq xref--original-window (assoc-default 'window alist)
> -              xref--original-window-intent (assoc-default 'display-action alist))
> +              xref--original-window-intent (assoc-default 'display-action alist)
> +              xref--original-command this-command)
>           (current-buffer)))))

I'm good with this patch, though, if you find it helpful for personal 
customization.

When we implement two different display strategies, though, we might 
choose between them inside xref--show-xrefs straight away, instead of 
saving the original command for later.

bug#35737: xref--original-command

[Juri Linkov]

>> Remembering the command that created the *xref* buffer
>> will allow such customization to treat RET differently,
>> i.e. it makes sense for RET to quit the transient xref buffer
>> displayed momentarily while navigating code with xref-find-definitions,
>> whereas leaving the xref buffer visible while navigating matches
>> in the xref buffer created by e.g. project-find-regexp:
>>
>> (define-key xref--button-map [(control ?m)]
>>    (lambda ()
>>      (interactive)
>>      (if (memq xref--original-command '(xref-find-definitions))
>>          (call-interactively 'xref-quit-and-goto-xref)
>>        (call-interactively 'xref-goto-xref))))
>
> I'm all for customizability, but as I said in a past discussion on the
> subject, I don't think this by itself would be a good default behavior.

I don't propose to change its default behavior.  Just allowing its
customization would be good.

> Having two buffers that looks basically the same but react to RET
> differently is not great for usability.

Using display-buffer-in-direction, they don't look the same: after
customization xref-find-definitions can display the xref buffer below,
whereas other xref command can display in the side window.

>> Better ideas?
>
> Ideally, the "transient" buffer should look differently from the
> "persistent" one.
>
> To take VS Code as an example (I just to see how it behaves exactly),
> a search for references opens search results in the sidebar.

Emacs has side windows too.

> Whereas for definitions they have both "Go To Definition" and "Peek
> Definition". The latter shows the definitions kind of inline, in
> a not-exactly-a-popup kind of way
> (https://stackoverflow.com/questions/55599177/go-to-definition-in-vscode-preview-window-ruins-the-edito),
> and there, if you type RET, that triggers navigation to the selected
> definition. "Go To Definition", when there are several definitions, also
> switches to "Peek" mode by default.
>
> Not sure how best to implement this different kind of display in Emacs, but
> the idea makes a lot of sense to me.
>
> In Sublime, IIRC, for this they used the dropdown from their
> top-of-the-window command line, the same one that becomes active once one
> presses Ctrl-P.

We have Completions for the same purpose.

bug#35737: xref--original-command

[Dmitry Gutov]

On 16.05.2019 0:04, Juri Linkov wrote:

> I don't propose to change its default behavior.  Just allowing its
> customization would be good.

OK.

But please wait a little, I'd like to show a patch for bug#35702 that 
can also provide a basic for the same distinction in functionality but 
without this variable.

>> Having two buffers that looks basically the same but react to RET
>> differently is not great for usability.
> 
> Using display-buffer-in-direction, they don't look the same: after
> customization xref-find-definitions can display the xref buffer below,
> whereas other xref command can display in the side window.

OK. Still look very similar, but at least the behavior appears different 
from the outset.

If you look at Atom's behavior, it actually shows regexp search results 
in a pane below the main area. The same direction where you want to show 
the definitions search result. Just something to keep in mind.

>> To take VS Code as an example (I just to see how it behaves exactly),
>> a search for references opens search results in the sidebar.
> 
> Emacs has side windows too.

You mean like Speedbar? That's the part which I didn't exactly like.

>> Whereas for definitions they have both "Go To Definition" and "Peek
>> Definition". The latter shows the definitions kind of inline, in
>> a not-exactly-a-popup kind of way
>> (https://stackoverflow.com/questions/55599177/go-to-definition-in-vscode-preview-window-ruins-the-edito),
>> and there, if you type RET, that triggers navigation to the selected
>> definition. "Go To Definition", when there are several definitions, also
>> switches to "Peek" mode by default.
>>
>> Not sure how best to implement this different kind of display in Emacs, but
>> the idea makes a lot of sense to me.

BTW, there's a third-party package that implements something like that 
for LSP users: https://github.com/emacs-lsp/lsp-ui#lsp-ui-peek

Not sure how likely we are to have this contributed to the core, though.

>> In Sublime, IIRC, for this they used the dropdown from their
>> top-of-the-window command line, the same one that becomes active once one
>> presses Ctrl-P.
> 
> We have Completions for the same purpose.

Except we have a UI for it which is expected to be usable without using 
arrow keys. And the completion entries in this case can contain spaces, 
parens, and basically any other characters. They can also be fairly 
long. So completing-read doesn't seem to fit the bill.

I'm open to ideas.

bug#35737: xref--original-command

[Juri Linkov]

> But please wait a little, I'd like to show a patch for bug#35702 that can
> also provide a basic for the same distinction in functionality but without
> this variable.

OK.

>> Emacs has side windows too.
>
> You mean like Speedbar? That's the part which I didn't exactly like.

I don't like Speedbar too because it's too intrusive.  But maybe
it can be rewritten using real side windows as documented in
(info "(elisp) Side Windows")

bug#35737: xref--original-command

[Dmitry Gutov]

On 16.05.2019 22:58, Juri Linkov wrote:
>> But please wait a little, I'd like to show a patch for bug#35702 that can
>> also provide a basic for the same distinction in functionality but without
>> this variable.
> 
> OK.

Please see the latest commits.

In particular, there is now a xref-show-definitions-function.

So in addition to display-buffer-alist, you can change it to give 
xref-find-definitions a particular behavior.

Or to propose a new default behavior, suggest a patch for 
xref--show-defs-buffer. It could do its own things instead of delegating 
to xref--show-xref-buffer, i.e. use a distinct new major mode and 
somewhat different keymap. And also call pop-to-buffer with different 
arguments.

>>> Emacs has side windows too.
>>
>> You mean like Speedbar? That's the part which I didn't exactly like.
> 
> I don't like Speedbar too because it's too intrusive.  But maybe
> it can be rewritten using real side windows as documented in
> (info "(elisp) Side Windows")

It's hard to comment without seeing, but those windows being to the side 
is, again, probably not my favorite feature. I think Emacs is doing fine 
showing Grep results in regular windows. But please show the patch if 
it's easy, of course.

bug#35737: xref--original-command

[Juri Linkov]

>>> But please wait a little, I'd like to show a patch for bug#35702 that can
>>> also provide a basic for the same distinction in functionality but without
>>> this variable.
>>
>> OK.
>
> Please see the latest commits.

Thanks, I tried xref revert and it works fine.
Also I agree with Eli regarding the command name,
documentation and NEWS.

> In particular, there is now a xref-show-definitions-function.
>
> So in addition to display-buffer-alist, you can change it to give
> xref-find-definitions a particular behavior.

But I don't want to write a new function.  I just need to check
if the xref buffer was created by a particular command.

If the solution requires writing a new function, then much easier
would be to use 'advice-add':

  (advice-add 'xref-find-definitions :after
              (lambda (&rest _args)
                (with-current-buffer (window-buffer)
                  (setq-local xref--original-command 'xref-find-definitions))))

> Or to propose a new default behavior, suggest a patch for
> xref--show-defs-buffer. It could do its own things instead of delegating to
> xref--show-xref-buffer, i.e. use a distinct new major mode and somewhat
> different keymap. And also call pop-to-buffer with different arguments.

If despite a chain of indirections, xref still can't distinguish
different commands that created the xref buffer, I'd rather close
this feature request and use 'advice-add' in customization.

bug#35737: xref--original-command

[Dmitry Gutov]

On 24.05.2019 21:40, Juri Linkov wrote:

> Thanks, I tried xref revert and it works fine.
> Also I agree with Eli regarding the command name,
> documentation and NEWS.

Should be good now.

> But I don't want to write a new function.  I just need to check
> if the xref buffer was created by a particular command.

I think you need to make a choice here.

Do you want to customize your personal Emacs, or do you want to improve 
the default behavior?

If it's the former, I think the advice you posted will work as well as 
any other solution.

I was kind of expecting the latter.

> If despite a chain of indirections, xref still can't distinguish
> different commands that created the xref buffer, I'd rather close
> this feature request and use 'advice-add' in customization.

Do we really need to be able to distinguish between xref-find-references 
and project-find-regexp as well?

TBH, xref--original-command is easy to add, but then we'll have an 
internal variable that isn't used anywhere. Somebody will just delete it 
someday.

bug#35737: xref--original-command

[Juri Linkov]

>> Thanks, I tried xref revert and it works fine.
>> Also I agree with Eli regarding the command name,
>> documentation and NEWS.
>
> Should be good now.

Thanks.  I wonder why you renamed xref--revert-xref-buffer
to a such strange name xref-refresh-results?  Why not simply
xref-revert-buffer?

>> But I don't want to write a new function.  I just need to check
>> if the xref buffer was created by a particular command.
>
> I think you need to make a choice here.
>
> Do you want to customize your personal Emacs, or do you want to improve the
> default behavior?
>
> If it's the former, I think the advice you posted will work as well as any
> other solution.
>
> I was kind of expecting the latter.

The goal was to improve the default behavior to make customization easier.

>> If despite a chain of indirections, xref still can't distinguish
>> different commands that created the xref buffer, I'd rather close
>> this feature request and use 'advice-add' in customization.
>
> Do we really need to be able to distinguish between xref-find-references
> and project-find-regexp as well?
>
> TBH, xref--original-command is easy to add, but then we'll have an internal
> variable that isn't used anywhere. Somebody will just delete it someday.

The idea was to make xref more customizable differently for different
commands: xref-find-definitions, xref-find-references, project-find-regexp.

bug#35737: xref--original-command

[Dmitry Gutov]

On 27.05.2019 22:59, Juri Linkov wrote:

> Thanks.  I wonder why you renamed xref--revert-xref-buffer
> to a such strange name xref-refresh-results?  Why not simply
> xref-revert-buffer?

Strange?

I had to think how to describe the new command in NEWS, and these are 
the terms I came up with. Hence the name. Do you not think these words 
are appropriate?

"revert buffer" sounds like undoing changes, and we're repeating a 
search and refreshing (or maybe reloading) the results.

> The goal was to improve the default behavior to make customization easier.

That's why I added xref-show-definitions-function.

Customizing display-buffer-alist is an arcane art. The hook this 
variable provides should be easier to understand for an average user.

So, to clarify, you're not interested in changing the *visible* default 
behavior, at least for now?

>> TBH, xref--original-command is easy to add, but then we'll have an internal
>> variable that isn't used anywhere. Somebody will just delete it someday.
> 
> The idea was to make xref more customizable differently for different
> commands: xref-find-definitions, xref-find-references, project-find-regexp.

I get the idea, but not the goal. I know why we'd want to make 
xref-find-definitions and project-find-regexp to behave differently. The 
rest, I'm not so clear.

Anyway, I was hoping my efforts in improving the default behavior would 
benefit your goals as well, but it seems the split between 
xref--show-xrefs and xref--show-defs goes against them. That's too bad.

You still have your alternative solution, though.

bug#35737: xref--original-command

[Dmitry Gutov]

[-- Attachment #1: Type: text/plain, Size: 182 bytes --]

To be clear, here's the kind of change I was thinking of.

Though maybe instead of changing xref--show-defs-buffer, we'd add a new 
function named like xref--show-defs-buffer-below.

[-- Attachment #2: xref-find-definitions-at-bottom.diff --]
[-- Type: text/x-patch, Size: 3051 bytes --]

diff --git a/lisp/progmodes/xref.el b/lisp/progmodes/xref.el
index 58c0119a54..80f80cdd75 100644
--- a/lisp/progmodes/xref.el
+++ b/lisp/progmodes/xref.el
@@ -704,6 +704,16 @@ xref--xref-buffer-mode
   (setq next-error-function #'xref--next-error-function)
   (setq next-error-last-buffer (current-buffer)))
 
+(defvar xref--definitions-buffer-mode-map
+  (let ((map (make-sparse-keymap)))
+    (define-key map (kbd "RET") #'xref-quit-and-goto-xref)
+    (set-keymap-parent map xref--xref-buffer-mode-map)
+    map))
+
+(define-derived-mode xref--definitions-buffer-mode
+  xref--xref-buffer-mode
+  "XREF Defs")
+
 (defun xref--next-error-function (n reset?)
   (when reset?
     (goto-char (point-min)))
@@ -725,7 +735,6 @@ xref--next-error-function
 
 (defvar xref--button-map
   (let ((map (make-sparse-keymap)))
-    (define-key map [(control ?m)] #'xref-goto-xref)
     (define-key map [mouse-1] #'xref-goto-xref)
     (define-key map [mouse-2] #'xref--mouse-2)
     map))
@@ -789,18 +798,21 @@ xref--show-xref-buffer
            (funcall fetcher)))
          (xref-alist (xref--analyze xrefs)))
     (with-current-buffer (get-buffer-create xref-buffer-name)
-      (setq buffer-undo-list nil)
-      (let ((inhibit-read-only t)
-            (buffer-undo-list t))
-        (erase-buffer)
-        (xref--insert-xrefs xref-alist)
-        (xref--xref-buffer-mode)
-        (pop-to-buffer (current-buffer))
-        (goto-char (point-min))
-        (setq xref--original-window (assoc-default 'window alist)
-              xref--original-window-intent (assoc-default 'display-action alist))
-        (setq xref--fetcher fetcher)
-        (current-buffer)))))
+      (xref--show-common-initialize xref-alist fetcher alist)
+      (xref--xref-buffer-mode)
+      (pop-to-buffer (current-buffer))
+      (current-buffer))))
+
+(defun xref--show-common-initialize (xref-alist fetcher alist)
+  (setq buffer-undo-list nil)
+  (let ((inhibit-read-only t)
+        (buffer-undo-list t))
+    (erase-buffer)
+    (xref--insert-xrefs xref-alist)
+    (goto-char (point-min))
+    (setq xref--original-window (assoc-default 'window alist)
+          xref--original-window-intent (assoc-default 'display-action alist))
+    (setq xref--fetcher fetcher)))
 
 (defun xref-refresh-results ()
   "Refresh the search results in the current buffer."
@@ -826,9 +838,12 @@ xref--show-defs-buffer
       (xref--pop-to-location (car xrefs)
                              (assoc-default 'display-action alist)))
      (t
-      (xref--show-xref-buffer fetcher
-                              (cons (cons 'fetched-xrefs xrefs)
-                                    alist))))))
+      (with-current-buffer (get-buffer-create xref-buffer-name)
+        (xref--show-common-initialize (xref--analyze xrefs) fetcher alist)
+        (xref--definitions-buffer-mode)
+        (pop-to-buffer (current-buffer)
+                       '(display-buffer-in-direction . ((direction . below))))
+        (current-buffer))))))
 
 \f
 (defvar xref-show-xrefs-function 'xref--show-xref-buffer

bug#35737: xref--original-command

[Eli Zaretskii]

> From: Dmitry Gutov <dgutov@yandex.ru>
> Date: Tue, 28 May 2019 00:13:34 +0300
> Cc: 35737@debbugs.gnu.org
> 
> "revert buffer" sounds like undoing changes, and we're repeating a 
> search and refreshing (or maybe reloading) the results.

In Emacs, "reverting" a buffer means re-loading it from its source.
If that source has been updated outside of Emacs, then reverting
doesn't mean undoing changes, it means something else.  There are
examples of such reverting elsewhere in Emacs: in Dired and Info
buffers, for example.

bug#35737: xref--original-command

[Dmitry Gutov]

On 28.05.2019 5:41, Eli Zaretskii wrote:

> In Emacs, "reverting" a buffer means re-loading it from its source.
> If that source has been updated outside of Emacs, then reverting
> doesn't mean undoing changes, it means something else.  There are
> examples of such reverting elsewhere in Emacs: in Dired and Info
> buffers, for example.

Right. But I figured I'd be a little more explicit.

I don't have a strong opinion on this, though, so just say the word, and 
I'll rename the command.

bug#35737: xref--original-command

[Eli Zaretskii]

> Cc: 35737@debbugs.gnu.org, juri@linkov.net
> From: Dmitry Gutov <dgutov@yandex.ru>
> Date: Tue, 28 May 2019 10:46:40 +0300
> 
> I don't have a strong opinion on this, though, so just say the word, and 
> I'll rename the command.

I don't have a strong opinion, either, or I'd have talked already.  I
did remember raising a brow when reading that function, but that's
all.

bug#35737: xref--original-command

[Juri Linkov]

> "revert buffer" sounds like undoing changes, and we're repeating a search
> and refreshing (or maybe reloading) the results.

"revert buffer" is a standard term for updating an Emacs buffer.

> I get the idea, but not the goal. I know why we'd want to make
> xref-find-definitions and project-find-regexp to behave differently. The
> rest, I'm not so clear.
>
> Anyway, I was hoping my efforts in improving the default behavior would
> benefit your goals as well, but it seems the split between xref--show-xrefs
> and xref--show-defs goes against them. That's too bad.

Thanks for your efforts.  Your recent changes would be useful for other goals,
e.g. making the xref output to use grep-like output format.

>> The goal was to improve the default behavior to make customization easier.
>
> That's why I added xref-show-definitions-function.
>
> Customizing display-buffer-alist is an arcane art. The hook this variable
> provides should be easier to understand for an average user.
>
> So, to clarify, you're not interested in changing the *visible* default
> behavior, at least for now?

No, not a visual change this time.  I'd also close bug#33992 because
it's also leading nowhere.  But maybe your recent patch with
xref--definitions-buffer-mode is an improvement, I don't know.

I'm looking at xref from customization's point of view, and I see no more
improvements that could simplify xref customization.

bug#35737: xref--original-command

[Dmitry Gutov]

On 28.05.2019 23:30, Juri Linkov wrote:
>> "revert buffer" sounds like undoing changes, and we're repeating a search
>> and refreshing (or maybe reloading) the results.
> 
> "revert buffer" is a standard term for updating an Emacs buffer.

OK, renamed.

bug#35737: xref--original-command

[Dmitry Gutov]

On 28.05.2019 23:30, Juri Linkov wrote:

>> Anyway, I was hoping my efforts in improving the default behavior would
>> benefit your goals as well, but it seems the split between xref--show-xrefs
>> and xref--show-defs goes against them. That's too bad.
> 
> Thanks for your efforts.  Your recent changes would be useful for other goals,
> e.g. making the xref output to use grep-like output format.

Not sure what you mean, but if you mean altering the behavior for 
all-commands-except-xref-find-definitions, then sure. Not sure why you 
think the split is helpful for this but not your present goal, though.

>> So, to clarify, you're not interested in changing the *visible* default
>> behavior, at least for now?
> 
> No, not a visual change this time.  I'd also close bug#33992 because
> it's also leading nowhere.  But maybe your recent patch with
> xref--definitions-buffer-mode is an improvement, I don't know.

That patch is a lateral move, to make experimenting with this particular 
behavior change easier. I've installed in the meantime.

> I'm looking at xref from customization's point of view, and I see no more
> improvements that could simplify xref customization.

OK. If you have any further ideas, please don't hesitate to bring them up.