bug#20487: 25.0.50; Format and behavior of *xref* buffer is non-standard

bug#20487: 25.0.50; Format and behavior of *xref* buffer is non-standard

[Vitalie Spinu]

Hi,

*xref* buffer doesn't look nor behaves like other buffers that display
references (*grep*, occur*, *compilation*).

Particularly

  - on RET *xref* is buried. That's not that other modes do and it's
    rather inconvenient IMO.

  - Display is inneficient. Currently two lines are used to display one
    item:

       /home/vspinu/bin/r-source/src/library/stats/src/port.c
         nlminb_iterate(double b[], double d[], double fx, double g[], double h[],
       /home/vspinu/bin/r-source/src/include/R_ext/stats_stubs.h
         S_nlminb_iterate(double b[], double d[], double fx, double g[], double	h[],

    I would rather prefer the way *grep* does that.


As we are on this, would be nice if *grep* and *xref* cold abbreviate
file-names by replacing home directory with ~/.

Thanks,

  Vitalie

bug#20487: 25.0.50; Format and behavior of *xref* buffer is non-standard

[Dmitry Gutov]

On 05/03/2015 01:20 AM, Vitalie Spinu wrote:

>    - on RET *xref* is buried. That's not that other modes do and it's
>      rather inconvenient IMO.

That's valid complaint, but it's very convenient to bury the xref buffer 
upon jumping to a location, if the list was displayed by 
`xref-find-definitions', primarily because "jump to definition" usually 
means we only want to visit one location.

Further, on more than one occasion I needed to only jump to one location 
in *grep* and *compile* buffers, preferably in the same window, in order 
to hide the said *grep* or *compile* buffer. We don't have an easy way 
to do that.

I'd welcome suggestions taking this into account.

>    - Display is inneficient. Currently two lines are used to display one
>      item:
>
>         /home/vspinu/bin/r-source/src/library/stats/src/port.c
>           nlminb_iterate(double b[], double d[], double fx, double g[], double h[],
>         /home/vspinu/bin/r-source/src/include/R_ext/stats_stubs.h
>           S_nlminb_iterate(double b[], double d[], double fx, double g[], double	h[],
>
>      I would rather prefer the way *grep* does that.

So, you'd call displaying the same file name over and over for each 
location inside it, "efficient"? Do you favor vertical splits?

Someone can implement a different rendering method for xref buffer (and 
set xref-show-xrefs-function to it), but I'm against making it default.

That rendering method will also encounter difficulties if xref groups 
will sometimes have 2 levels of nesting (or more?).

> As we are on this, would be nice if *grep* and *xref* cold abbreviate
> file-names by replacing home directory with ~/.

Grep would probably have to do it with font-lock (patch welcome, I guess).

In xref, currently it falls on the shoulders of each backend, because 
the location groups are simply strings, and as far as UI is concerned, 
they can contain anything. This can change if groups become proper objects.

bug#20487: 25.0.50; Format and behavior of *xref* buffer is non-standard

[Vitalie Spinu]

 >>> Dmitry Gutov on Sun, 3 May 2015 17:30:43 +0300 wrote:

 > On 05/03/2015 01:20 AM, Vitalie Spinu wrote:
 >> - on RET *xref* is buried. That's not that other modes do and it's
 >> rather inconvenient IMO.

 > That's valid complaint, but it's very convenient to bury the xref buffer upon
 > jumping to a location, 

Not for me. Now I am using xref for what I would normally use grep
before - locate stuff around and familiarize myself with the code. So I
would like to keep it open.

 > Further, on more than one occasion I needed to only jump to one location in
 > *grep* and *compile* buffers, preferably in the same window, in order to hide
 > the said *grep* or *compile* buffer. We don't have an easy way to do that.

I never have problems with that. Emacs pops buffers in a variety of ways
but rarely hides them. I think people are used to manage their own
buffers as they see fit. I don't think xref should "help" them with
that.

Systems like HELM have their own consistent but different dynamics. I
would really leave hiding buffers to HELM on this occasion.

 > I'd welcome suggestions taking this into account.

I think if a new behavior is contentious the default should be
consistent with how other similar modes behave.

 >> I would rather prefer the way *grep* does that.

 > So, you'd call displaying the same file name over and over for each
 > location inside it, "efficient"? 

Are you questioning efficiency of *grep* displays?

I like the files being repeated. but that's not quite my point. I want
xref to place symbol description on the same line with the file (as
other modes do).

Repeated files have an advantage that you can immediately see which
symbol is in what file.

 > Do you favor vertical splits?

No. My splits are horizontal.

 > Someone can implement a different rendering method for xref buffer
 > (and set xref-show-xrefs-function to it), but I'm against making it
 > default.

Well. Xref already has broken a bunch of emacs UI standards. I think
this one is already one too many.

You can go against Emacs conventions but you cannot go against unix
world. You cannot change how grep outputs stuff in terminal. People are
used to standard displays and new mode better be considerate of that.

 > That rendering method will also encounter difficulties if xref groups
 > will sometimes have 2 levels of nesting (or more?).

What's the problem more concretely? You can still display hierarchical
information like this:

file1:23: Class foo
file1:25: -- Method boo {
              some more stuff her
            }
file1:26: -- Method baz
file2:70: Class foo


  Vitalie

bug#20487: 25.0.50; Format and behavior of *xref* buffer is non-standard

[Dmitry Gutov]

On 05/03/2015 07:39 PM, Vitalie Spinu wrote:

> Not for me. Now I am using xref for what I would normally use grep
> before - locate stuff around and familiarize myself with the code. So I
> would like to keep it open.

It has different uses. I'd probably also prefer if xref-find-apropos and 
xref-find-references output buffers behaved like you're asking, though.

> I never have problems with that. Emacs pops buffers in a variety of ways
> but rarely hides them. I think people are used to manage their own
> buffers as they see fit. I don't think xref should "help" them with
> that.

Helmut, thoughts?

> I think if a new behavior is contentious the default should be
> consistent with how other similar modes behave.

Considering we can translate Grep output into data xref expects, we 
could the latter the common UI. So, sooner or later, discussing better 
defaults might be worthwhile.

> Are you questioning efficiency of *grep* displays?

Yes, obviously. Not to mention a lot of GUI applications, have you tried 
Ack or Ag? They both use the grouped output by default.

> Repeated files have an advantage that you can immediately see which
> symbol is in what file.

I don't have any problems moving my eyes by a line or two to read it.

> No. My splits are horizontal.

That's odd. Assuming your files are 80 columns wide, and your windows 
are tuned to that width, if the file name is printed on every line, it 
would push the matched lines to the right, often leading to wrapping or 
truncation.

In certain environments (like Java, where file paths are long), this can 
be a bigger problem than in others.

> Well. Xref already has broken a bunch of emacs UI standards. I think
> this one is already one too many.

This one I'm feeling strongly about.

It's not like the handling of Grep output in Emacs was the result of 
some big design. I bet that it simply was the easiest (while still 
useful) one to implement in the command-line tool, and then when Emacs 
integration was done, it was simpler to add highlighting and 
clickability to it, instead of parsing and reformatting.

> You can go against Emacs conventions but you cannot go against unix
> world. You cannot change how grep outputs stuff in terminal. People are
> used to standard displays and new mode better be considerate of that.

Well, like I said, the output can be customizable. I'm sure some people 
will appreciate if you implement the flat output.

> What's the problem more concretely? You can still display hierarchical
> information like this:

Yes, that doesn't look too bad. I somehow thought you'd want the method 
name to be mentioned on each line, too, but there's no real need for 
that. Good to know.

bug#20487: 25.0.50; Format and behavior of *xref* buffer is non-standard

[Dmitry Gutov]

On 05/03/2015 08:33 PM, Dmitry Gutov wrote:

> Considering we can translate Grep output into data xref expects, we
> could the latter the common UI.
         ^ make

bug#20487: 25.0.50; Format and behavior of *xref* buffer is non-standard

[Vitalie Spinu]

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

 >>> Dmitry Gutov on Sun, 3 May 2015 20:33:17 +0300 wrote:

 > On 05/03/2015 07:39 PM, Vitalie Spinu wrote:

 > Considering we can translate Grep output into data xref expects, we could the
 > latter the common UI. So, sooner or later, discussing better defaults might be
 > worthwhile.

I would be happy with that. As long as all buffers looks the same, have
same UI and use space wisely.

Colours and line number display should also be the same. There is no
much point to strain people to get used to different displays for the
same type of information.

Currently file paths in *xref* are not highlighted with
compilation-info-face like grep and others do. For me files are bold and
items are also bold. So my whole buffer is in *bold*. This makes it
appear dirty and difficult to read. I think bold font should never be
used for large regions. I attach a sample.


 >> Are you questioning efficiency of *grep* displays?

 > Yes, obviously. Not to mention a lot of GUI applications, have you tried Ack or
 > Ag? They both use the grouped output by default.

I am using ack but still prefer grep output due to more efficient
vertical display.

Note that grep, ack etc commonly need to output multiple occurrences per
file. With xref most of the symbols will have one-to-one correspondence
to the file. So it makes a lot of sense for *xref* to have file and
object on one line.

 >> No. My splits are horizontal.

 > That's odd. Assuming your files are 80 columns wide, 

Right. Long file names are indeed a problem. An inconvenience which I
will get down to eventually if no one else does before me.

Good example is helm-do-grep in which file names are abbreviated and are
not intrusive at all.

  Vitalie



[-- Attachment #2: xref1.png --]
[-- Type: image/png, Size: 15018 bytes --]

bug#20487: 25.0.50; Format and behavior of *xref* buffer is non-standard

[Dmitry Gutov]

On 05/03/2015 09:46 PM, Vitalie Spinu wrote:

> Colours and line number display should also be the same. There is no
> much point to strain people to get used to different displays for the
> same type of information.

That's a good goal to strive for.

> Currently file paths in *xref* are not highlighted with
> compilation-info-face like grep and others do. For me files are bold and

Okay, let's highlight all group headings this way for now.

> items are also bold. So my whole buffer is in *bold*. This makes it
> appear dirty and difficult to read. I think bold font should never be
> used for large regions. I attach a sample.

It wasn't bold for me (font-lock-keyword-face is apparently bold in your 
non-default theme). This one is harder, because *grep* leaves the line 
contents in the default face.

I've done that too for now, but our text is clickable, whereas in *grep* 
you can only click on the file paths. That will need to be resolved.

Line numbers are difficult for now, since they're simply a part of the 
description string. Maybe if we move them to a separate field.

> I am using ack but still prefer grep output due to more efficient
> vertical display.

Personal preferences aside, I hope you can admit that the authors of 
modern-ish tools prefer the grouped display.

> Note that grep, ack etc commonly need to output multiple occurrences per
> file. With xref most of the symbols will have one-to-one correspondence
> to the file. So it makes a lot of sense for *xref* to have file and
> object on one line.

I'm not sure why you've made that conclusion.

It may be true for xref-find-definitions, but then the numbers of those 
results should be small anyway, so you're not running out of vertical space.

In the xref-find-references output, on the other hand, you are likely to 
observe the opposite. Not just multiple matches per file, but even 
multiple matches per function (if we showed them).

> Good example is helm-do-grep in which file names are abbreviated and are
> not intrusive at all.

Not every file name can be easily abbreviated. While you can compress 
the path down to what makes each segment unique (like the fish shell 
does in prompt), or even omit some, the segment names might by 
themselves be valuable to the user, on occasion.

bug#20487: 25.0.50; Format and behavior of *xref* buffer is non-standard

[Vitalie Spinu]

 >>> Dmitry Gutov on Mon, 4 May 2015 00:52:16 +0300 wrote:

 > Okay, let's highlight all group headings this way for now.
 
Thanks for considering this!

 > > items are also bold. So my whole buffer is in *bold*. This makes it
 > > appear dirty and difficult to read. I think bold font should never be
 > > used for large regions. I attach a sample.
 
 > It wasn't bold for me (font-lock-keyword-face is apparently bold in
 > your non-default theme). This one is harder, because *grep* leaves
 > the line contents in the default face.


Keywords usually have striking colors and are often bold. It's fine for
short identifiers but if you highlight the whole line it clutters the
view. Maybe font-lock-variable-name-face as an alternative?
 
 > Personal preferences aside, I hope you can admit that the authors of
 > modern-ish tools prefer the grouped display.

Sure thing. I don't mind this part that much.

It's just that, in case of xref-find-definitions, grouping is done
mostly for one observation which still doesn't make much sense to
me. But you are right; there are xref-find-references and
xref-find-apropos out there and making separate interfaces for those
would be silly.

  Vitalie

bug#20487: 25.0.50; Format and behavior of *xref* buffer is non-standard

[Dmitry Gutov]

On 05/04/2015 01:20 AM, Vitalie Spinu wrote:

> Keywords usually have striking colors and are often bold. It's fine for
> short identifiers but if you highlight the whole line it clutters the
> view. Maybe font-lock-variable-name-face as an alternative?

I think let's keep the default for now. It has a plus side: the backends 
can return buffer lines with syntax highlighting applied. 
semantic-symref looks like that too.

An added face might be nice, but probably one that sets the background 
color.

> It's just that, in case of xref-find-definitions, grouping is done
> mostly for one observation which still doesn't make much sense to
> me. But you are right; there are xref-find-references and
> xref-find-apropos out there and making separate interfaces for those
> would be silly.

I think so. And hopefully, the "find definitions" search will result in 
one unique result most of the time.

bug#20487: 25.0.50; Format and behavior of *xref* buffer is non-standard

[Hielmut Eller]

On Sun, May 03 2015, Dmitry Gutov wrote:

>> I never have problems with that. Emacs pops buffers in a variety of ways
>> but rarely hides them. I think people are used to manage their own
>> buffers as they see fit. I don't think xref should "help" them with
>> that.
>
> Helmut, thoughts?

*Completion* buffers are automatically closed after the selection is
made.  The *xref* buffer is similar in purpose: select a candidate from
a list.  I think it's rarely an advantage but often a annoyance to have
to close the *xref* buffer manually.  We could always have an
alternative key say SPC that jumps to the location without closing the
*xref* buffer.

Helmut

bug#20487: 25.0.50; Format and behavior of *xref* buffer is non-standard

[Vitalie Spinu]

 >>> Hielmut Eller on Sun, 03 May 2015 22:05:02 +0200 wrote:

 > On Sun, May 03 2015, Dmitry Gutov wrote:
 >>> I never have problems with that. Emacs pops buffers in a variety of ways
 >>> but rarely hides them. I think people are used to manage their own
 >>> buffers as they see fit. I don't think xref should "help" them with
 >>> that.
 >> 
 >> Helmut, thoughts?

 > *Completion* buffers are automatically closed after the selection is
 > made.

??? Not for me.

Just tried in emacs -q wit byte-compile-file on .el and makeinfo on
.texi and none quits.


  Vitalie

  

bug#20487: 25.0.50; Format and behavior of *xref* buffer is non-standard

[Dmitry Gutov]

On 05/03/2015 11:30 PM, Vitalie Spinu wrote:

>   > *Completion* buffers are automatically closed after the selection is
>   > made.
>
> ??? Not for me.
>
> Just tried in emacs -q wit byte-compile-file on .el and makeinfo on
> .texi and none quits.

It does for me: either click on a completion, or move into that window 
and press C-m on one, it inserts the completion and quits.

But I'm not sure *Completions* is like xref, in the general case: the 
former contains no references; we're pretty sure the user only needs one 
value from it at a time.

Which is usually true for xref-find-definitions, for me. Bot not 
necessarily for xref-find-apropos, or the (newly implemented) 
xref-find-references.

bug#20487: 25.0.50; Format and behavior of *xref* buffer is non-standard

[Vitalie Spinu]

 >>> Dmitry Gutov on Sun, 3 May 2015 23:48:25 +0300 wrote:


 > But I'm not sure *Completions* is like xref, in the general case: the former
 > contains no references; we're pretty sure the user only needs one value from it
 > at a time.

Sorry. I misread *Compilation* instead of *Completions*.

*Completion* and *Compilation* are very dissimilar in terms of behavior
and purpose. But I think I see your point. You try to make a case for an
electric *xref*. That quite could be, but I would rather not have that
as a default.

As I have said before, there are common electric interfaces (Helm, Ido
etc.) that will surely pick xref up later. I would prefer to have a
*standard* default alternative which is not electric.

Thanks,

  Vitalie

bug#20487: 25.0.50; Format and behavior of *xref* buffer is non-standard

[Dmitry Gutov]

On 05/04/2015 12:49 AM, Vitalie Spinu wrote:

> *Completion* and *Compilation* are very dissimilar in terms of behavior
> and purpose. But I think I see your point. You try to make a case for an
> electric *xref*. That quite could be, but I would rather not have that
> as a default.
>
> As I have said before, there are common electric interfaces (Helm, Ido
> etc.) that will surely pick xref up later. I would prefer to have a
> *standard* default alternative which is not electric.

And it's not electric anymore. With that, I think it's time to close 
this bug: the other request, switching to the non-grouped display, is 
not going to happen in the default presentation.

Thanks for the discussion!

bug#20487: 25.0.50; Format and behavior of *xref* buffer is non-standard

[Stefan Monnier]

>> Do you favor vertical splits?
> No. My splits are horizontal.

[ I'm always shocked to see how people can be sure what the other one
  meant with, say, "vertical splits".  ]

Which one of those refers to windows that are stacked vertically on top
of each other, rather than side by side?


        Stefan

bug#20487: 25.0.50; Format and behavior of *xref* buffer is non-standard

[Dmitry Gutov]

On 05/04/2015 05:18 AM, Stefan Monnier wrote:

> [ I'm always shocked to see how people can be sure what the other one
>    meant with, say, "vertical splits".  ]
>
> Which one of those refers to windows that are stacked vertically on top
> of each other, rather than side by side?

I check what C-h k C-x 3 says, every time. "on top of each other" would 
be the vertical one.

bug#20487: 25.0.50; Format and behavior of *xref* buffer is non-standard

[Vitalie Spinu]

 >>> Dmitry Gutov on Mon, 4 May 2015 05:29:16 +0300 wrote:

 > On 05/04/2015 05:18 AM, Stefan Monnier wrote:
 >> [ I'm always shocked to see how people can be sure what the other one
 >> meant with, say, "vertical splits".  ]
 >> 
 >> Which one of those refers to windows that are stacked vertically on top
 >> of each other, rather than side by side?

 > I check what C-h k C-x 3 says, every time. "on top of each other" would be the
 > vertical one.

:) I did the same but the command is now called split-window-right. So I
had to C-h f split-window-vertically to find (once again) what "vertical
split" means.

  Vitalie

bug#20487: 25.0.50; Format and behavior of *xref* buffer is non-standard

[Dmitry Gutov]

On 05/04/2015 02:15 PM, Vitalie Spinu wrote:

> :) I did the same but the command is now called split-window-right. So I
> had to C-h f split-window-vertically to find (once again) what "vertical
> split" means.

Oh. :) Right. I was looking at my own wrappers for those commands, and 
they haven't been renamed yet.