[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: Dmitry Gutov
Subject: Re: [Emacs-diffs] emacs-25 f8208b6: Document the user-level features of the Xref package
Date: Sun, 10 Jan 2016 22:32:48 +0300
User-agent: Mozilla/5.0 (X11; Linux x86_64; rv:43.0) Gecko/20100101 Thunderbird/43.0

On 01/10/2016 09:59 PM, Eli Zaretskii wrote:

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.

That's an exotic use case, which can be described separately. But even if the user does produce a TAGS file through one of these tools, it's the Etags Xref backend that will be used to obtain information from it.

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.

Elisp backend is one of the two Xref backends we have. The rest of the "backends" you've described, are "external tools", which are used in a different way than "proper" Xref backends.

So I want the Elisp Xref backend to continue to be called an Xref backend, but I don't want GNU Global called that, until we actually have an Xref backend for it.

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

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

Yes. I'm just describing, in detail, how the current manual text is wrong.

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,

We shouldn't, they're really different.

Let's call them "external tools", then.

They are not necessarily external, see above.

They are. I'm not proposing to call the Elisp backend an external tool.

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.

I don't see how.

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?

When we use the GNU Global external tool to produce all references to a symbol, it consults its database, and returns the actual references to the symbol, not just the list of files.

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.

My point is, a large part of this description will be inaccurate if the current Xref backend does implement xref-backend-references.

You _don't know_ what an arbitrary backend does.

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

It's better to maintain the levels of abstraction: if we're describing Xref commands, we should describe what the commands are for, and what output the user should expect, but treat the backends as black boxes as much as possible.

And separately (maybe nearby, maybe in a different section), describe the actual backends that come with Emacs. What Xref commands they support, and what commands they don't support. What data sources they use (say, load-history for Elisp backend, and TAGS files for etags backend).

Going back to what this part of the subthread started from: "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."

This isn't true. It's halfway true when the current Xref backend does _not_ implement xref-backend-references. And even then, like I mentioned above, "search all the files listed in the @code{xref} backend's database, one by one" is a highly questionable description.

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?

It's better.

I feel that this entire mode of description is broken (instead, we should say that it completes using whatever completion-at-point-functions says to use; and its elements can be set by Semantic, etags, major modes, minor modes, etc), but that would require more changes.

And if the previous version of the manual didn't elicit any complaints, perhaps it was good enough.

reply via email to

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