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

[Eli Zaretskii <eliz@gnu.org>]

> Cc: emacs-devel@gnu.org
> From: Dmitry Gutov <dgutov@yandex.ru>
> Date: Wed, 20 Jan 2016 00:53:19 +0300
> 
> On 01/19/2016 08:41 PM, Eli Zaretskii wrote:
> 
> > Some of the discussion we had before was about the structure of this
> > section.  You cannot see the structure from the diffs, which is why I
> > suggested to read the formatted manual.
> 
> Yes, but I didn't offer any particular opinion on that. It seems good 
> enough, although I'd remove, or move out, the references to etags 
> commands: the section is named Xref, tags-* commands are not part of it.

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

> With the two new additions, we could feel more confident doing that.

AFAICT, your additions are not directly related to this section; they
are not mentioned in it.

> There's no direct counterpart to tags-search, but I think it can be 
> adequately replaced with dired-do-find-regexp or 
> project-or-external-find-regexp.

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.  We should have an xref-based replacement
for tags-search and tags-query-replace, which would similarly search
through the "relevant" files.  These are currently the only 2
etags-based commands in that section that directly invoke etags.el.
Once we solve that problem (and I think we should do this before v25.1
is out), there will be no reason for splitting the description more
than it already is (the tags tables and how to build them are already
described in a separate subsection).

(Btw, I think replacing tags-search and tags-query-replace with
commands that start with "project-" is not a good idea, for the same
reason that having "tags-*" commands there is.  They should be
"xref-*" commands.)