From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!not-for-mail From: Eli Zaretskii 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 20:59:47 +0200 Message-ID: <834melmfa4.fsf@gnu.org> References: <20160109191428.26341.44105@vcs.savannah.gnu.org> <5691C9D2.7080905@yandex.ru> <83egdpmo1j.fsf@gnu.org> <56929D6F.2050508@yandex.ru> Reply-To: Eli Zaretskii NNTP-Posting-Host: plane.gmane.org X-Trace: ger.gmane.org 1452452413 19872 80.91.229.3 (10 Jan 2016 19:00:13 GMT) X-Complaints-To: usenet@ger.gmane.org NNTP-Posting-Date: Sun, 10 Jan 2016 19:00:13 +0000 (UTC) Cc: emacs-devel@gnu.org To: Dmitry Gutov Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Sun Jan 10 20:00:09 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 1aILDg-0008Q1-HE for ged-emacs-devel@m.gmane.org; Sun, 10 Jan 2016 20:00:04 +0100 Original-Received: from localhost ([::1]:48676 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1aILDf-000592-MM for ged-emacs-devel@m.gmane.org; Sun, 10 Jan 2016 14:00:03 -0500 Original-Received: from eggs.gnu.org ([2001:4830:134:3::10]:50335) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1aILDS-00058r-3P for emacs-devel@gnu.org; Sun, 10 Jan 2016 13:59:51 -0500 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1aILDN-0003DC-9J for emacs-devel@gnu.org; Sun, 10 Jan 2016 13:59:50 -0500 Original-Received: from fencepost.gnu.org ([2001:4830:134:3::e]:48334) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1aILDN-0003D8-5J; Sun, 10 Jan 2016 13:59:45 -0500 Original-Received: from 84.94.185.246.cable.012.net.il ([84.94.185.246]:3231 helo=HOME-C4E4A596F7) by fencepost.gnu.org with esmtpsa (TLS1.2:RSA_AES_128_CBC_SHA1:128) (Exim 4.82) (envelope-from ) id 1aILDM-0008Bu-Eo; Sun, 10 Jan 2016 13:59:44 -0500 In-reply-to: <56929D6F.2050508@yandex.ru> (message from Dmitry Gutov on Sun, 10 Jan 2016 21:05:35 +0300) X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.2.x-3.x [generic] X-Received-From: 2001:4830:134:3::e 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:197994 Archived-At: > Cc: emacs-devel@gnu.org > From: Dmitry Gutov > 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.