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: Mon, 11 Jan 2016 22:09:46 +0300
> 
> - Do not mention the external tools at all here. Only list Etags and 
> Emacs Lisp as Xref backends. As a consequence, do not document 
> xref-find-references in the manual. Since it doesn't replace any 
> particular pre-existing feature, I think we're allowed to do that.

Doesn't sound right to me.  This is an important command, and a good
addition to the Emacs features.  Leaving it out of the manual just
because we cannot find a good place for it, or a good way to squeeze
it into the chapter, sounds... unwise.  However, ...

> - Only mention the "external tools" in the documentation of 
> xref-find-refrerences. Maybe add a reference there to some other node. 
> That node might have to be created, and it would list them, and contain 
> some other guidance, like "if you're using any of those except Grep, 
> refreshing the database is up to you".

... xref-find-refrerences was the least of my problems when I worked
on this.  It's just one command.

What I needed is a coherent framework that would bring some order to
this group of commands and features.

> > Faced with these challenges, I came up with the solution that is now
> > before your eyes.  What alternative do you suggest?  Can you present a
> > coherent conceptual framework for describing these features, and a
> > structure of the section to go with that framework?
> 
> I can try.

Thanks, that's what I need.  If the concepts and the overall idea are
good, the details will fall in place by themselves.