bug#19468: 25.0.50; UI inconveniences with M-.

[Eli Zaretskii]

> From: Stefan Monnier <monnier@IRO.UMontreal.CA>
> Cc: dgutov@yandex.ru, 19468@debbugs.gnu.org
> Date: Mon, 27 Apr 2015 17:54:30 -0400
> 
> > Emacs 24 also had "C-u M-." to go to the next one.  This one doesn't;
> > moreover, if you try "C-u M-.", you get prompted for the symbol again,
> > and if you type the same one, you get nowhere.  The other matches are
> > only available via completion, see below.
> 
> Maybe we should write an xref-old-ui-mode.

I didn't ask for the old UI.  (If I want it, I can still have it,
since the etags.el commands are still available.)  I'm okay with the
new UI.  This bug report is about the new UI, and its goal is to make
the new UI better.

> It would make M-. always prompt and it would always jump to the first
> entry and then let you use C-u M-. to jump to the next match.

That's not what I meant by the above.  It was you who mentioned the
old UI, not me.  What I wanted to point out in response was that the
old UI was consistent and complete: it always displayed the first/next
match and provided a command to go to the next/previous one.  By
contrast, the new UI is inconsistent: with some back-ends it shows the
list of matches and allows to navigate it, with others it shows only
the first match and does not give any way to get the next match.

> >> But popping up the *xref* buffer when there's only one element in it
> >> doesn't make much sense I think.
> > Oh, but there shouldn't be only one element: you will see the others
> > if you type TAB instead of RET.
> 
> No: there's only one definition of `find-tag' so Elisp's xref backend
> just returns that one and that's it.

There's more than one matching definition, see below.

But that's largely immaterial: this bug report is not about the
back-end, it's about the UI.  The UI should be independent of the
back-end, otherwise the users will be confused when they switch
between languages.  (If it turns out that some back-ends need to be
augmented so that they allow the front-end to present similar UI for
the same query, then those back-ends should be enhanced.)

> > IOW, the elisp-mode back-end does know about the other candidates, it
> > just doesn't show them in *xref*.
> 
> None of the others are definitions of `find-tag'.

At least one is, the one in org-ctags.  And I can make a case for the
others as well, because no one said partial matches found by etags are
not legitimate, even if you personally don't consider them to be.

> Arguably, the find-tag advice in org-ctags.el could be offered as well,
> if org-ctags.el happens to be loaded

??? Why should the xref matches depend on what is and isn't loaded?
That would make xref exactly equivalent to "M-x apropos", which means
this mode of operation would make xref entirely redundant.  To say
nothing of the fact that this doesn't scale to any language except
ELisp.

We could offer this mode as an optional feature, but it certainly
shouldn't be the default.  (One of my worst annoyances is to type a
C-h command and be presented with "[No match]", because some package
is not loaded or some function is not available in the Emacs
configuration I happen to be using.)

> > It somehow decided for me that I want only the exact match.
> 
> It's rather that the old etags interface was not sure enough of itself,
> so it offered anything that had "find-tag" as a substring somewhere,
> i.e. lots and lots of false positives.

That's one way of looking at it.  Another is to say that etags gave
you more information and thus allowed to find more loose matches,
which is helpful when your memory is failing you.

But in the context of this bug report, that, too, is immaterial: if we
think the etags back-end gives too much information, by all means
let's filter it before presenting the matches.  Bonus points for
making the filtering optional, since some people might like that, and
in some situations even you might need it.

The important point for the purposes of this bug report is that the
stuff presented by the UI for the same query does not differ so
radically when you switch the back-end.

> > And btw, there is another confusing difference between these back-ends
> > that somehow bubbles up to the UI level: the elisp-mode back-end only
> > supports finding multiple matches via completion,
> 
> No.  `semantic-symref-find-tags-by-name' is not a match for "show me the
> definition of find-tag" and neither is "find-tag-tag". The problem here
> is that the current etags xref backend returns confusingly many
> so-called "matches" which are really irrelevant and should only be
> included in the completions.

Then let's fix the results we display with the etags back-end to show
only the relevant ones.  Please don't forget that currently, and
probably for the foreseeable future, the etags back-end is the only
one we have for most languages, so the things you dislike about it are
pretty much in our face for months, if not years, to come.  If we
think this back-end "needs work", let's do that now.  Saying that the
back-end returns a confusingly large amount of bogus matches, and then
switching to a UI that assumes much smarter back-ends (which don't
really exist) makes very little sense to me.

Whatever we do, let's make the UI more consistent and independent of
the back-ends.  Otherwise, we have a significant usability problem
waiting to happen.

> There's a difference between:
> 
>   I know the name, I need to find out its definition.
> 
> and
> 
>   I remember the name includes something like "find-tag"
> 
> The old code did not distinguish between the two, but the new code does.

The old code attempted to support both use cases, by showing the exact
match(es) first, followed by less likely ones.  We do similar things
in other commands.  The advantages of such a method are that (1) you
don't need to second-guess the user, (2) you provide only one command
for the user to remember, and (3) if the user only _thinks_ she knows
the name, but really doesn't, she can find the information without
having to invoke another command.

> I think that's an important feature of the new code in this respect.

But it is incomplete without a means to get to the other possible
matches in this case.

To summarize my points in this sub-thread:

  . the UI should depend much less on the back-end, ideally not at all

  . there should be a way to go to the next/previous match if the
    *xref* buffer is not displayed (or not created in the first
    place); if this happens because there's only one match, we should
    say so explicitly

  . when there are more than one possible match, the UI should behave
    similarly, i.e. display the *xref* buffer; when there's only one
    match, it should _never_ display *xref*, and should display an
    indication of the fact that there's only one match

  . if the criteria for filtering of the matches are very different
    between the possible back-ends, there should be some agreed-upon
    uniform default that returns roughly the same number of matches
    with all back-ends, and the rest should be controlled by user
    options