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

[Dmitry Gutov <dgutov@yandex.ru>]

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

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

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.