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: Thu, 21 Jan 2016 19:29:35 +0200 Message-ID: <83powu96yo.fsf@gnu.org> References: <20160109191428.26341.44105@vcs.savannah.gnu.org> <5691C9D2.7080905@yandex.ru> <83egdpmo1j.fsf@gnu.org> <56929D6F.2050508@yandex.ru> <834melmfa4.fsf@gnu.org> <5692B1E0.8010100@yandex.ru> <831t9pma4e.fsf@gnu.org> <5693FDFA.2070607@yandex.ru> <83ziwbkj5l.fsf@gnu.org> <5694055E.6050201@yandex.ru> <83si1udcaz.fsf@gnu.org> <569D64AC.1060606@yandex.ru> <83powxbh6c.fsf@gnu.org> <569EB04F.800@yandex.ru> <8337tsc133.fsf@gnu.org> <56A05073.5090100@yandex.ru> Reply-To: Eli Zaretskii NNTP-Posting-Host: plane.gmane.org X-Trace: ger.gmane.org 1453397417 20762 80.91.229.3 (21 Jan 2016 17:30:17 GMT) X-Complaints-To: usenet@ger.gmane.org NNTP-Posting-Date: Thu, 21 Jan 2016 17:30:17 +0000 (UTC) Cc: emacs-devel@gnu.org To: Dmitry Gutov Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Thu Jan 21 18:30:12 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 1aMJ3f-0000Fg-B7 for ged-emacs-devel@m.gmane.org; Thu, 21 Jan 2016 18:30:07 +0100 Original-Received: from localhost ([::1]:49087 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1aMJ3e-000266-6A for ged-emacs-devel@m.gmane.org; Thu, 21 Jan 2016 12:30:06 -0500 Original-Received: from eggs.gnu.org ([2001:4830:134:3::10]:53690) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1aMJ2y-0001J8-23 for emacs-devel@gnu.org; Thu, 21 Jan 2016 12:29:25 -0500 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1aMJ2u-0000PE-RW for emacs-devel@gnu.org; Thu, 21 Jan 2016 12:29:23 -0500 Original-Received: from fencepost.gnu.org ([2001:4830:134:3::e]:48994) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1aMJ2u-0000PA-Ns; Thu, 21 Jan 2016 12:29:20 -0500 Original-Received: from 84.94.185.246.cable.012.net.il ([84.94.185.246]:4421 helo=HOME-C4E4A596F7) by fencepost.gnu.org with esmtpsa (TLS1.2:RSA_AES_128_CBC_SHA1:128) (Exim 4.82) (envelope-from ) id 1aMJ2u-0001zF-4o; Thu, 21 Jan 2016 12:29:20 -0500 In-reply-to: <56A05073.5090100@yandex.ru> (message from Dmitry Gutov on Thu, 21 Jan 2016 06:28:51 +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:198507 Archived-At: > Cc: emacs-devel@gnu.org > From: Dmitry Gutov > Date: Thu, 21 Jan 2016 06:28:51 +0300 > > On 01/20/2016 07:43 AM, Eli Zaretskii wrote: > > > "Xref" is the name of the node, not of the section. And the node's > > name does not mean it describes xref the package; this is user-level > > documentation. If you have a better suggestion for a short name of a > > node which aims at describing features most of which have "xref-" in > > their names, please tell. > > Cross-Referencing? A native speaker might have a better suggestion. Cross-Referencing doesn't fit, IMO, not if you consider the user-level functionality. I've tried to find a name that somehow expressed the functionality, but came up empty-handed. "Xref" is a compromise: it's not a word that means something, it's just the name of the package (but then so was "Tags"). > > AFAICT, your additions are not directly related to this section; they > > are not mentioned in it. > > Hmm. When I asked what we needed to obsolete tags-loop-continue, you > only mentioned Dired commands. > > http://lists.gnu.org/archive/html/emacs-devel/2016-01/msg00842.html Yes. But I think it would be good to replace these last two as well. > > No, dired-do-find-regexp cannot replace it, because it looks through > > all the files in the directory, whereas tags-search looks in the files > > recorded in the tags tables. > > Ok, dired-do-find-regexp cannot. What about project-or-external-find-regexp? It's close. But AFAIU it requires something called "roots", which is an additional input. What I had in mind was just what tags-search does, but with the xref-style UI, i.e. via the *xref* buffer showing the matches. Same as you did in Dired, but looking in files returned by the backend -- etags will return the files in TAGS, elisp will return the files in load-path (or wherever else it gets the files), etc. > By default, when the VC project backend is used, and > project-vc-external-roots-function is at its default value, > project-or-external-find-regexp will search the current project, as well > as the directories of the tags tables, if they are outside of it. > > Or, in emacs-lisp-mode, it will search the load-path directories. So how do the "roots", whatever that is, come into play? IOW, why is this command in project.el and not in xref.el? I suppose the reason is somehow related to the purpose of project.el, which is different from xref.el. > > We should have an xref-based replacement > > for tags-search and tags-query-replace, which would similarly search > > through the "relevant" files. > > tags-query-replace? We have xref-query-replace already xref-query-replace is (confusingly) different: it makes replacements in the names of the matching identifiers, not in matches found in the files returned by the backend. > Back to tags-search. > > Like described above, we have a command that goes further that it > already. So what would be the goal of having xref-find-regexp? Just to > tick off a box and simplify updating the manual? If project-or-external-find-regexp is exactly equivalent, then perhaps a simple alias would be enough. And don't underestimate the power of consistent names and of array of commands whose names and descriptions in the manual make sense. Confusing documentation makes it much harder to grasp the features and their internal logic. > Suppose we're in emacs-lisp-mode. What will xref-find-regexp do? Will it > search the load-path elements, but skip the current project, however > it's defined, if it's not in load-path? Will it only search *.el files > inside load-path directories, and ignore files with all other extensions? Why don't those questions arise when we invoke xref-find-references? How do you know in what files to search then? I think the same answer will do for the replacements of tags-search and tags-query-replace. > > (Btw, I think replacing tags-search and tags-query-replace with > > commands that start with "project-" is not a good idea, for the same > > I definitely never suggested replacing tags-query-replace with project- > anything. The new "replace" workflow is two-step: two the search (using > some command that creates an xref buffer), then call xref-query-replace. xref-query-replace does this: This command interactively replaces FROM with TO in the names of the references displayed in the current *xref* buffer. That's not what tags-query-replace does.