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

[Dmitry Gutov]

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.