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

[Dmitry Gutov <dgutov@yandex.ru>]

On 01/10/2016 11:51 PM, Eli Zaretskii wrote:

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

These don't seem too complex to me. I think I've already raised many of 
the below points (though not the "let's not document" one).

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

When the xref functions and commands mention the word "backend", they 
refer to xref backends. And I don't suggest we 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?

Again, they're only used in one command. And the way they're used, is 
unlikely to be extended to other commands.

In the future, we may have either individual backends based on these 
tools, or maybe one aggregated "external tools" backend that will 
dispatch to the appropriate tool, if they provide more or less the same 
functionality.

Now, using the same word, backend, for both actual Xref backends and the 
"external tools" feature we've borrowed from CEDET is my main complaint. 
Even if we only deal with that, I'll be much happier.

First and foremost, do not list Etags, GNU GLOBAL, Cscope, IDUtils and 
Grep together. As much as we want it to be true, Emacs does not really 
provide a "unified user interface to these tools" (but hopefully, will 
sometime).

I see, basically, two options:

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

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

Maybe you can choose to simply refer to (info "(semantic) SymRef") 
there, which mentions them (and calls them "symbol reference tools"). I 
think that description is too short, however.

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

The features implemented by Semantic should be described separately--it 
has its own manual. I'm not sure which feature of Semantic in particular 
you feel should be documented with that of Etags.

If you mean completion-at-point, which is enhanced a bit when 
semantic-mode is on, then I don't see why you have to mention it. Yes, 
it might improve accuracy, but the user interface is the same. You can 
add a reference to a node in Semantic's manual that describes the 
benefits it adds to completion-at-point. Or could, if that node existed.

Regarding the features implemented by Etags, some of which are not 
covered by Xref: let's make a list of the essential omissions, and try 
to cover them.

For instance, tags-query-replace has an alternative in 
project[-or-external]-find-regexp, followed by xref-query-replace.

dired-do-search, likewise, could be substituted for a new 
dired-find-regexp command which uses xref's presentation.

dired-do-query-replace-regexp--with using the same command followed by 
xref-query-replace.

I'm not saying they will be perfect, but they *will* essentially cover 
the same functionality.

And maybe someone somewhere will be surprised to know that 
find-grep-dired + dired-do-query-replace-regexp is not the only way to 
perform replacements across all files in a directory.

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

I know it covers a small portion, but why is that a problem? We can 
document some existing xref commands (thus promising to maintain them), 
and we'll get to the rest of the functionality when it arrives.

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