From: Dmitry Gutov <dgutov@yandex.ru>
To: Eli Zaretskii <eliz@gnu.org>
Cc: emacs-devel@gnu.org
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 [thread overview]
Message-ID: <5692B1E0.8010100@yandex.ru> (raw)
In-Reply-To: <834melmfa4.fsf@gnu.org>
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.
next prev parent reply other threads:[~2016-01-10 19:32 UTC|newest]
Thread overview: 54+ messages / expand[flat|nested] mbox.gz Atom feed top
[not found] <20160109191428.26341.44105@vcs.savannah.gnu.org>
[not found] ` <E1aHyy4-0006rU-Td@vcs.savannah.gnu.org>
2016-01-10 3:02 ` [Emacs-diffs] emacs-25 f8208b6: Document the user-level features of the Xref package Dmitry Gutov
2016-01-10 15:50 ` Eli Zaretskii
2016-01-10 18:05 ` Dmitry Gutov
2016-01-10 18:59 ` Eli Zaretskii
2016-01-10 19:32 ` Dmitry Gutov [this message]
2016-01-10 20:51 ` Eli Zaretskii
2016-01-10 21:11 ` Dmitry Gutov
2016-01-11 3:33 ` Eli Zaretskii
2016-01-11 16:55 ` Dmitry Gutov
2016-01-11 17:52 ` Eli Zaretskii
2016-01-11 19:09 ` Dmitry Gutov
2016-01-11 19:31 ` Eli Zaretskii
2016-01-11 19:41 ` Dmitry Gutov
2016-01-11 20:14 ` Eli Zaretskii
2016-01-11 20:21 ` Dmitry Gutov
2016-01-18 17:31 ` Eli Zaretskii
2016-01-18 22:18 ` Dmitry Gutov
2016-01-19 17:41 ` Eli Zaretskii
2016-01-19 21:53 ` Dmitry Gutov
2016-01-20 4:43 ` Eli Zaretskii
2016-01-20 7:28 ` John Wiegley
2016-01-20 20:53 ` Dmitry Gutov
2016-01-20 21:03 ` John Wiegley
2016-01-20 21:09 ` Dmitry Gutov
2016-01-21 19:01 ` Stephen Leake
2016-01-21 20:32 ` Dmitry Gutov
2016-01-21 3:46 ` Eli Zaretskii
2016-01-21 3:28 ` Dmitry Gutov
2016-01-21 17:29 ` Eli Zaretskii
2016-01-21 18:46 ` Dmitry Gutov
2016-01-21 19:00 ` Eli Zaretskii
2016-01-21 19:46 ` Dmitry Gutov
2016-01-21 20:02 ` Eli Zaretskii
2016-01-21 20:10 ` Dmitry Gutov
2016-01-21 20:32 ` Eli Zaretskii
2016-01-21 21:40 ` Dmitry Gutov
2016-01-24 2:20 ` Dmitry Gutov
2016-01-24 15:29 ` Eli Zaretskii
2016-01-25 20:38 ` Ken Brown
2016-01-25 20:52 ` Eli Zaretskii
2016-01-25 21:29 ` Dmitry Gutov
2016-01-26 2:44 ` Ken Brown
2016-01-26 6:22 ` Dmitry Gutov
2016-01-21 19:19 ` Stephen Leake
2016-01-21 19:26 ` Dmitry Gutov
2016-01-22 7:40 ` Stephen Leake
2016-01-22 8:21 ` Eli Zaretskii
2016-01-22 10:46 ` Dmitry Gutov
2016-01-22 13:37 ` Eli Zaretskii
2016-01-22 10:07 ` Dmitry Gutov
2016-01-21 20:09 ` Eli Zaretskii
2016-01-22 18:16 ` John Yates
2016-01-19 5:36 ` John Wiegley
2016-01-19 5:47 ` Dmitry Gutov
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=5692B1E0.8010100@yandex.ru \
--to=dgutov@yandex.ru \
--cc=eliz@gnu.org \
--cc=emacs-devel@gnu.org \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
Code repositories for project(s) associated with this external index
https://git.savannah.gnu.org/cgit/emacs.git
https://git.savannah.gnu.org/cgit/emacs/org-mode.git
This is an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.