[Top][All Lists]

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

Re: [Emacs-diffs] emacs-25 f8208b6: Document the user-level features of

From: Dmitry Gutov
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
User-agent: Mozilla/5.0 (X11; Linux x86_64; rv:44.0) Gecko/20100101 Thunderbird/44.0

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),

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.

reply via email to

[Prev in Thread] Current Thread [Next in Thread]