[Top][All Lists]

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

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

From: Dmitry Gutov
Subject: Re: [Emacs-diffs] emacs-25 f8208b6: Document the user-level features of the Xref package
Date: Mon, 11 Jan 2016 22:09:46 +0300
User-agent: Mozilla/5.0 (X11; Linux x86_64; rv:43.0) Gecko/20100101 Thunderbird/43.0

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.

reply via email to

[Prev in Thread] Current Thread [Next in Thread]