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 06:28:51 +0300
> 
> On 01/20/2016 07:43 AM, Eli Zaretskii wrote:
> 
> > "Xref" is the name of the node, not of the section.  And the node's
> > name does not mean it describes xref the package; this is user-level
> > documentation.  If you have a better suggestion for a short name of a
> > node which aims at describing features most of which have "xref-" in
> > their names, please tell.
> 
> Cross-Referencing? A native speaker might have a better suggestion.

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

> > AFAICT, your additions are not directly related to this section; they
> > are not mentioned in it.
> 
> Hmm. When I asked what we needed to obsolete tags-loop-continue, you 
> only mentioned Dired commands.
> 
> http://lists.gnu.org/archive/html/emacs-devel/2016-01/msg00842.html

Yes.  But I think it would be good to replace these last two as well.

> > No, dired-do-find-regexp cannot replace it, because it looks through
> > all the files in the directory, whereas tags-search looks in the files
> > recorded in the tags tables.
> 
> Ok, dired-do-find-regexp cannot. What about project-or-external-find-regexp?

It's close.  But AFAIU it requires something called "roots", which is
an additional input.  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.

> By default, when the VC project backend is used, and 
> project-vc-external-roots-function is at its default value, 
> project-or-external-find-regexp will search the current project, as well 
> as the directories of the tags tables, if they are outside of it.
> 
> Or, in emacs-lisp-mode, it will search the load-path directories.

So how do the "roots", whatever that is, come into play?  IOW, why is
this command in project.el and not in xref.el?  I suppose the reason
is somehow related to the purpose of project.el, which is different
from xref.el.

> > We should have an xref-based replacement
> > for tags-search and tags-query-replace, which would similarly search
> > through the "relevant" files.
> 
> tags-query-replace? We have xref-query-replace already

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.

> Back to tags-search.
> 
> Like described above, we have a command that goes further that it 
> already. So what would be the goal of having xref-find-regexp? Just to 
> tick off a box and simplify updating the manual?

If project-or-external-find-regexp is exactly equivalent, then perhaps
a simple alias would be enough.

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.

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

> > (Btw, I think replacing tags-search and tags-query-replace with
> > commands that start with "project-" is not a good idea, for the same
> 
> I definitely never suggested replacing tags-query-replace with project- 
> anything. The new "replace" workflow is two-step: two the search (using 
> some command that creates an xref buffer), then call xref-query-replace.

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.