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: Thu, 21 Jan 2016 21:46:19 +0300 [thread overview]
Message-ID: <56A1277B.9080001@yandex.ru> (raw)
In-Reply-To: <83powu96yo.fsf@gnu.org>
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.
next prev parent reply other threads:[~2016-01-21 18:46 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
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 [this message]
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=56A1277B.9080001@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.