[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,
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.
- Re: [Emacs-diffs] emacs-25 f8208b6: Document the user-level features of the Xref package, Dmitry Gutov, 2016/01/09
- Re: [Emacs-diffs] emacs-25 f8208b6: Document the user-level features of the Xref package, Eli Zaretskii, 2016/01/10
- Re: [Emacs-diffs] emacs-25 f8208b6: Document the user-level features of the Xref package, Dmitry Gutov, 2016/01/10
- Re: [Emacs-diffs] emacs-25 f8208b6: Document the user-level features of the Xref package,
Eli Zaretskii <=
- Re: [Emacs-diffs] emacs-25 f8208b6: Document the user-level features of the Xref package, Dmitry Gutov, 2016/01/10
- Re: [Emacs-diffs] emacs-25 f8208b6: Document the user-level features of the Xref package, Eli Zaretskii, 2016/01/10
- Re: [Emacs-diffs] emacs-25 f8208b6: Document the user-level features of the Xref package, Dmitry Gutov, 2016/01/10
- Re: [Emacs-diffs] emacs-25 f8208b6: Document the user-level features of the Xref package, Eli Zaretskii, 2016/01/10
- Re: [Emacs-diffs] emacs-25 f8208b6: Document the user-level features of the Xref package, Dmitry Gutov, 2016/01/11
- Re: [Emacs-diffs] emacs-25 f8208b6: Document the user-level features of the Xref package, Eli Zaretskii, 2016/01/11
- Re: [Emacs-diffs] emacs-25 f8208b6: Document the user-level features of the Xref package, Dmitry Gutov, 2016/01/11
- Re: [Emacs-diffs] emacs-25 f8208b6: Document the user-level features of the Xref package, Eli Zaretskii, 2016/01/11
- Re: [Emacs-diffs] emacs-25 f8208b6: Document the user-level features of the Xref package, Dmitry Gutov, 2016/01/11
- Re: [Emacs-diffs] emacs-25 f8208b6: Document the user-level features of the Xref package, Eli Zaretskii, 2016/01/11