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: Sun, 10 Jan 2016 22:32:48 +0300
> 
> Elisp backend is one of the two Xref backends we have. The rest of the 
> "backends" you've described, are "external tools", which are used in a 
> different way than "proper" Xref backends.
> 
> So I want the Elisp Xref backend to continue to be called an Xref 
> backend, but I don't want GNU Global called that, until we actually have 
> an Xref backend for it.

Can you propose an alternative conceptual framework for the user
manual, wrt to backends and the features described in this section?

Here are the problems I bumped into when I worked on this section:

 . It is impractical to try to ignore the existence of backends: many
   functions and commands mention them in their names and doc strings,
   so the fact of their existence is pretty much into the user's face.
   I couldn't ignore them.

 . There are only 2 proper backends, but then there are "fallbacks",
   like symref, Grep, etc. that are used in important commands.  What
   do we call those "non-backends", and how do we describe them
   without confusing the heck out of the readers?

 . How to describe a bunch of related features, of which only part is
   implemented by Xref, the rest are still (and probably always will
   be) in Etags, Semantic, etc.?  How to describe commands whose
   results could be very different depending on the backend and on the
   major mode?

 . How to make all of this reasonably future-proof, given that the
   functionality implemented today covers only a small portion of the
   turf it was supposed to?

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?

It is futile to argue about minor details if we disagree about the
basics.  If you can propose a coherent alternative for describing
these features, maybe we can make some progress.  Otherwise, I will
fix the few specific minor aspects that you've pointed out, and then I
will quickly try to forget about this ungrateful job I took upon
myself.

Thanks for the other comments, I will get to them in due time.