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

[Eli Zaretskii]

> Cc: address@hidden
> From: Dmitry Gutov <address@hidden>
> Date: Thu, 21 Jan 2016 21:46:19 +0300
> 
> 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.

That's just history: someone invented a definition that would make
sense.

> We don't define the word "xref".

We could, if we wanted to.  I think for now just pretending the name
has no semantic meaning is good enough.

> > 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.

But a reference includes a file name, doesn't it?  If so, why not
search through those files?

> 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.

It probably is for some use cases.  But in others, users might want
the other kind.

> 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.

That's what I thought.  So a command that would only search what's in
TAGS does have a place, IMO.  It would also be a good replacement for
tags-search.

> 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 think both use cases are legitimate.

> How about xref-query-replace-in-matches?

Fine with me.

> >> 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.

It would be OK for xref-find-regexp to do the same.  Users who want
the project.el way of doing that can invoke the commands there.  (They
should probably be documented in the manual.)