Re: [Emacs-diffs] emacs-25 f8208b6: Document the user-level features of the Xref package

[Eli Zaretskii <eliz@gnu.org>]

> Cc: emacs-devel@gnu.org
> From: Dmitry Gutov <dgutov@yandex.ru>
> Date: Sun, 10 Jan 2016 21:05:35 +0300
> 
> The text says: "Each such tool is used as a @dfn{backend} by commands 
> described in this section". This is untrue, they're not used as 
> "backends" in Xref terms. And most of them are only used by one command 
> (singular, not plural): xref-find-references, and only when an actual 
> backend doesn't provide a replacement logic.

AFAIU, that's not entirely true, because at least some of those can
produce etags-compatible TAGS tables.  It's hard to be 100% accurate
with this, as you see.

> > Is it that I used "backend" in a meaning
> > that's different from what the xref implementation uses?
> 
> Yes. You can call them "programs", or "external tools" like CEDET's docs 
> prefer to call them.

But some of them aren't programs or external tools at all, like the
elisp backend.  So that, too, is inaccurate.

> This part also makes using the term "backend" for them inaccurate: "Each 
> command detects which backends are available for the current major mode".
> 
> Xref backends *do* depend on the current major mode. Or can depend, at 
> least. But whether we use ggtags, cscope, or grep, doesn't depend on the 
> current major mode at all, just on whether there is an index file 
> generated by the respective external program, in some root directory.
> 
> semantic-symref-filepattern-alist uses the major-mode value to derive 
> the file wildcards to search for, but not, again the tools to use.

These are implementation details that are not relevant at this level,
IMO.

> > If so,
> > that's deliberate: this is a user manual, and that was the only
> > reasonable way I could think of to convey the idea of several backends
> > without talking about technicalities like xref-backend-references,
> > what symref does, when do we use the fallbacks, what are generic
> > functions, etc.
> 
> A backend is a value that can be returned by xref-find-backend.

The text uses "backend" in a different meaning than xref.el does.  We
are using the same word to refer to 2 different, though related,
beasts.

> > The idea the user will hopefully take out of this is that we use
> > several potential helpers under the hood some of which are based on
> > the mentioned tools that are not part of Emacs proper.  The tools are
> > mentioned to encourage the users to install them, so that their Emacs
> > environment is more complete and capable.
> 
> Let's call them "external tools", then.

They are not necessarily external, see above.

Believe me, I've been through all that already.  There are no easy
ways out here, at least I didn't find one.  Suggestions are welcome,
but what you suggest above is not better, IMO, it's just a different
type of inaccuracy.

> >>      +  The commands in this section visit and search all the files listed
> >>      +in the @code{xref} backend's database, one by one.  For these
> >>      +commands, the database serves only to specify a sequence of files to
> >>      +search.
> >>
> >> That may be true for tags-search, but that's never true for xref-find-references.
> >
> > It's true when xref-find-references uses IDUtils, for example.  And
> > even when it doesn't, the command does use _some_ database, even if
> > that database is made up of doc strings loaded into memory plus
> > load-history.
> 
> The specific sentence that isn't true is: "For these commands, the 
> database serves only to specify a sequence of files to search."
> 
> No, not only. It serves for more, IIUC.

What else does it serve for?

> > Once again, look at this from the user POV, not from the POV of
> > someone who knows how the implementation works.  Users need some
> > mental model of what's going on to make some sense and order out of a
> > heap of potentially unrelated features.  The above should provide
> > users with a conceptual framework that facilitates coming up with such
> > a mental model.  At least I hope it will.
> 
> I'd rather the imaginary framework didn't stray too far from reality.

I agree.  It doesn't.

> >> If the current backend defines xref-backend-references, then we just ask it, and show the results.
> >>
> >> If it doesn't, we delegate to the first available "CEDET tool", but they do perform the regexp search, not just list the files. Then, xref-collect-references takes the list of matches and verified, for each one, whether the match begins and ends on a symbol boundary (Grep can't check that).
> >
> > I'm not describing xref alone, I'm describing what xref _and_ its
> > backend do together.  Differentiating between the two parts of the job
> > is not useful for the purposes of the user manual.
> 
> You _don't know_ what an arbitrary backend does.

Of course, I do: I have the code of the existing backends, don't I?

> >> This makes it seem like tags-loop-continue is applicable for use after xref-find-* commands as well. But it isn't.
> >
> > Well, it explicitly references tags-search and comes directly after
> > the description of that command.  Would it be better if the first
> > sentence said that explicitly, like below?
> 
> Probably.

OK, I will make that change.

> > Is xref entirely not involved in completion-at-point-functions?
> 
> Entirely, yes. But I expect some major and minor modes will 
> simultaneously add elements to completion-at-point-functions and 
> xref-backend-functions, and those elements could dispatch to the same 
> underlying logic under the covers. But the APIs are separate.
> 
> > Do we
> > still use etags there?
> 
> etags by default, elisp-completion-at-point in emacs-lisp-buffers. Other 
> major and minor modes set their completion functions as well.

Thanks, I will fix that inaccuracy.

> >>        mode is enabled, it tries to use the Semantic parser data for
> >>        completion (@pxref{Semantic}).  If Semantic mode is not enabled or
> >>        fails at performing completion, it tries to complete using the
> >>      -selected tags table (@pxref{Tags}).  If in Emacs Lisp mode, it
> >>      +available @code{xref} backend (@pxref{Xref}).
> >>
> I wouldn't call the text entirely accurate before (since it only lists 
> Emacs Lisp mode as an exception, implying all other modes use etags for 
> completion). But it's the new text that I'm really worried about.

So would you say that this:

  If Semantic mode is not enabled or fails at performing completion,
  it tries to complete using the selected tags table

is accurate enough?  Or does it need any further fixes?

Thanks.