[Top][All Lists]

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

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

From: Eli Zaretskii
Subject: Re: [Emacs-diffs] emacs-25 f8208b6: Document the user-level features of the Xref package
Date: Sun, 10 Jan 2016 20:59:47 +0200

> Cc: address@hidden
> From: Dmitry Gutov <address@hidden>
> 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,

> > 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,

> > 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?


reply via email to

[Prev in Thread] Current Thread [Next in Thread]