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: Thu, 21 Jan 2016 21:46:19 +0300 Message-ID: <56A1277B.9080001@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> <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> <83powu96yo.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 1453402005 781 80.91.229.3 (21 Jan 2016 18:46:45 GMT) X-Complaints-To: usenet@ger.gmane.org NNTP-Posting-Date: Thu, 21 Jan 2016 18:46:45 +0000 (UTC) Cc: emacs-devel@gnu.org To: Eli Zaretskii Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Thu Jan 21 19:46:40 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 1aMKFj-0007bL-SE for ged-emacs-devel@m.gmane.org; Thu, 21 Jan 2016 19:46:40 +0100 Original-Received: from localhost ([::1]:49299 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1aMKFj-0001MH-84 for ged-emacs-devel@m.gmane.org; Thu, 21 Jan 2016 13:46:39 -0500 Original-Received: from eggs.gnu.org ([2001:4830:134:3::10]:49432) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1aMKFV-0001M8-Bk for emacs-devel@gnu.org; Thu, 21 Jan 2016 13:46:26 -0500 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1aMKFS-0005J6-3t for emacs-devel@gnu.org; Thu, 21 Jan 2016 13:46:25 -0500 Original-Received: from mail-lf0-x236.google.com ([2a00:1450:4010:c07::236]:35299) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1aMKFR-0005Iu-NP; Thu, 21 Jan 2016 13:46:22 -0500 Original-Received: by mail-lf0-x236.google.com with SMTP id c192so32588748lfe.2; Thu, 21 Jan 2016 10:46:21 -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=wvlORafWQ4fv1GhQ7TqktEj3sIhKeoDAAzMqWxP/nb8=; b=kz14rw+HZA6YB+PP/GOQwuRE1Xi5KJZ0UsLgOBh26cxdUibSGVK3TQPFshtFMF9lfi 9JY8AfJVg1kT9PRW8ZuS4FviAaX0MZnOV3EYgDmnizI//OQ/vGsFCqDgqaNJSSJagA2n +Gh+sIOIbXpSrSe4R8iJj4KfVubqop3a7nJZazc0ic5yaTgziFsFTVTccyFrSPsFQUwz 2f+vZmQehnLnR1vqJuZ9QmbnTjgj16Im054ayi575yiNPoudQhqeP0xkZI2gRf5IeK17 KRcmG9Z2rGZfG2qbM/Fqbwl6PzUyb75Ie75KnsavzQnrtQ4p0VdcDhw0oqHPhODKvAF3 BNGA== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20130820; h=x-gm-message-state:sender:subject:to:references:cc:from:message-id :date:user-agent:mime-version:in-reply-to:content-type :content-transfer-encoding; bh=wvlORafWQ4fv1GhQ7TqktEj3sIhKeoDAAzMqWxP/nb8=; b=g1FWLwA2QMwAukBPWB4TK4lJL41n8krxez7C04fMCpIs1kea9PrfXIGe+ut8k75DZz KXfocY675fO8Wy/JRGEnpSoL4GFVytLcDLBP8r+Chh57WOrIAu4azKZwil4CCNyP2n2M ekIWkswk/XG1aG+mNnui2QASggHkkZ8GOTr+5v3LIjC0fL+m5vxQasIEk78QrAZA5fv6 yrx7m+Wid4g3Wdn7nM7PMpA70/0mVbv+Szr25dYMT8qIwuUQVKNShDBom0+3D/yQ0sjh p/f3hWThksPdVmmIXXDi9/So9x5UIqP2KCX0EgnWpi1JAQPjib6JOEmTp0T6z/byLrGA BMGg== X-Gm-Message-State: ALoCoQkn78qdPmpRh3eipCRwjMViVum8vYwAl8xBoVTQIwyv8LJUtDN7Br4fmIuEKsbiRHY3zmzkIxK3zMU2cpJD2LAupLeFVA== X-Received: by 10.25.41.203 with SMTP id p194mr16339759lfp.135.1453401980464; Thu, 21 Jan 2016 10:46:20 -0800 (PST) Original-Received: from [192.168.1.190] ([178.252.127.222]) by smtp.googlemail.com with ESMTPSA id h69sm367147lfi.35.2016.01.21.10.46.19 (version=TLSv1/SSLv3 cipher=OTHER); Thu, 21 Jan 2016 10:46:19 -0800 (PST) User-Agent: Mozilla/5.0 (X11; Linux x86_64; rv:44.0) Gecko/20100101 Thunderbird/44.0 In-Reply-To: <83powu96yo.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:c07::236 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:198516 Archived-At: On 01/21/2016 08:29 PM, Eli Zaretskii wrote: > 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"). I don't know if that's true. "Tags" is a more meaningful word. You even define it in the manual. We don't define the word "xref". > 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. Backends don't return files. They return lists of references. Which could be "definitions", "references", "apropos matches"... and, I suppose, "regexp matches", if we really want to. Initially, I created the xref-find-regexp command, but then moved it to the project package, because always including the current project root turned out to be more useful, to me. > So how do the "roots", whatever that is, come into play? IOW, why is > this command in project.el and not in xref.el? The what and why of "project roots" are described inside project.el. As a practical example, xref-find-regexp, with etags backend, in the Emacs project, would only search the files inside src, lisp and lwlib, whereas project-find-regexp searches inside the whole emacs/ directory. And project-or-external-find-regexp would search outside of it as well, if any of the currently used TAGS files resided outside of emacs/. Each such TAGS file would create an "external root" to be searched. And if you were to use xref-find-regexp to search for occurrences of `tags-loop-continue', it would only find them in the sources. Whereas both project- commands would also find its occurrences inside doc/**/*.texi, etc/NEWS*, top-level ChangeLog files and inside test/. That looks distinctly more useful to me. Especially note how tags-search skips the test/ directory. > I suppose the reason > is somehow related to the purpose of project.el, which is different > from xref.el. Yes. Projects are groups of different kind of files. Xref deals with information about source code: where a function was defined, where it was referenced, and which functions we have. > 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. The fact that we had tags-query-replace doing things a certain way, doesn't mean that the replacement should work exactly the same. We can give it a different name, to appraise the user of the difference. How about xref-query-replace-in-matches? > If project-or-external-find-regexp is exactly equivalent, then perhaps > a simple alias would be enough. That would've been too easy. > 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. Sure. But that a matter of proper naming and documentation. That doesn't necessarily imply making the new commands do exactly what the previous ones did. >> 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. For xref-find-references, we generally leave it up to the backend. But that query is easier to make sense of: we usually only look for references in source files, so it can disregard the rest. When doing a regexp search, we expect to see the matches in all kinds of related files, including README at the top-level of the project. At least I do. xref-find-regexp, as I imagine you want it to be defined, doesn't fit any of my usual workflows. Hence the questions. > 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. I never suggested making tags-query-replace an "obsolete alias" to xref-query-replace.