From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!not-for-mail From: Dmitry Gutov Newsgroups: gmane.emacs.devel 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 Message-ID: <5692B1E0.8010100@yandex.ru> References: <20160109191428.26341.44105@vcs.savannah.gnu.org> <5691C9D2.7080905@yandex.ru> <83egdpmo1j.fsf@gnu.org> <56929D6F.2050508@yandex.ru> <834melmfa4.fsf@gnu.org> NNTP-Posting-Host: plane.gmane.org Mime-Version: 1.0 Content-Type: text/plain; charset=windows-1252; format=flowed Content-Transfer-Encoding: 7bit X-Trace: ger.gmane.org 1452454393 17103 80.91.229.3 (10 Jan 2016 19:33:13 GMT) X-Complaints-To: usenet@ger.gmane.org NNTP-Posting-Date: Sun, 10 Jan 2016 19:33:13 +0000 (UTC) Cc: emacs-devel@gnu.org To: Eli Zaretskii Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Sun Jan 10 20:33:13 2016 Return-path: Envelope-to: ged-emacs-devel@m.gmane.org Original-Received: from lists.gnu.org ([208.118.235.17]) by plane.gmane.org with esmtp (Exim 4.69) (envelope-from ) id 1aILjf-0002hL-IV for ged-emacs-devel@m.gmane.org; Sun, 10 Jan 2016 20:33:07 +0100 Original-Received: from localhost ([::1]:48867 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1aILje-0000up-T5 for ged-emacs-devel@m.gmane.org; Sun, 10 Jan 2016 14:33:06 -0500 Original-Received: from eggs.gnu.org ([2001:4830:134:3::10]:58756) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1aILjS-0000ug-Tl for emacs-devel@gnu.org; Sun, 10 Jan 2016 14:32:56 -0500 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1aILjO-0003fT-SQ for emacs-devel@gnu.org; Sun, 10 Jan 2016 14:32:54 -0500 Original-Received: from mail-lb0-x22c.google.com ([2a00:1450:4010:c04::22c]:33638) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1aILjO-0003f8-HN; Sun, 10 Jan 2016 14:32:50 -0500 Original-Received: by mail-lb0-x22c.google.com with SMTP id sv6so237046583lbb.0; Sun, 10 Jan 2016 11:32:50 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20120113; h=sender:subject:to:references:cc:from:message-id:date:user-agent :mime-version:in-reply-to:content-type:content-transfer-encoding; bh=muxYTFc4wrJ+IGMqupkwXM+nrwZ35S/iicQe+KafIC4=; b=PqKdAbF5LLXmRaHnf3BScH2rUEt9Ly1vQtrf+Sw0c1mbprlCyR9S2ZOzmq2MC4xtb6 FwOd5w9HiJvyRcYZWCNtuOoC0ZqKCBR0iCFzrYVUmrVKssaCjgS5aEUMKAZxBHypuNcm eChR/AYFQEUi05A//gpEcFGbmw4dCg6KGzFp+IVI3qOInoeeitWmhy10oCxfhr27GHzs Zp4grWLO9MMNcfJ8KEt1fworH3jlKAlcgv2QPW04cr8fH3U7wjyIx35SxV4c7bEPyVtu y9FtD0ZOoD6HpfCPz7FJtPz9oNupKvX3AlDkxWdI3kTTsusA08IlHOZ0epXpHVVu8aok B1NQ== X-Received: by 10.112.143.227 with SMTP id sh3mr25327062lbb.55.1452454369591; Sun, 10 Jan 2016 11:32:49 -0800 (PST) Original-Received: from [192.168.1.190] ([178.252.127.222]) by smtp.googlemail.com with ESMTPSA id i127sm3991154lfd.3.2016.01.10.11.32.48 (version=TLSv1/SSLv3 cipher=OTHER); Sun, 10 Jan 2016 11:32:48 -0800 (PST) User-Agent: Mozilla/5.0 (X11; Linux x86_64; rv:43.0) Gecko/20100101 Thunderbird/43.0 In-Reply-To: <834melmfa4.fsf@gnu.org> X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.2.x-3.x [generic] X-Received-From: 2a00:1450:4010:c04::22c X-BeenThere: emacs-devel@gnu.org X-Mailman-Version: 2.1.14 Precedence: list List-Id: "Emacs development discussions." List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Original-Sender: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Xref: news.gmane.org gmane.emacs.devel:197997 Archived-At: 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.