[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.
- Re: [Emacs-diffs] emacs-25 f8208b6: Document the user-level features of the Xref package, Dmitry Gutov, 2016/01/09
- Re: [Emacs-diffs] emacs-25 f8208b6: Document the user-level features of the Xref package, Eli Zaretskii, 2016/01/10
- Re: [Emacs-diffs] emacs-25 f8208b6: Document the user-level features of the Xref package, Dmitry Gutov, 2016/01/10
- Re: [Emacs-diffs] emacs-25 f8208b6: Document the user-level features of the Xref package, Eli Zaretskii, 2016/01/10
- Re: [Emacs-diffs] emacs-25 f8208b6: Document the user-level features of the Xref package, Dmitry Gutov, 2016/01/10
- Re: [Emacs-diffs] emacs-25 f8208b6: Document the user-level features of the Xref package, Eli Zaretskii, 2016/01/10
- Re: [Emacs-diffs] emacs-25 f8208b6: Document the user-level features of the Xref package, Dmitry Gutov, 2016/01/10
- Re: [Emacs-diffs] emacs-25 f8208b6: Document the user-level features of the Xref package, Eli Zaretskii, 2016/01/10
- Re: [Emacs-diffs] emacs-25 f8208b6: Document the user-level features of the Xref package, Dmitry Gutov, 2016/01/11
- Re: [Emacs-diffs] emacs-25 f8208b6: Document the user-level features of the Xref package, Eli Zaretskii, 2016/01/11
- Re: [Emacs-diffs] emacs-25 f8208b6: Document the user-level features of the Xref package,
Dmitry Gutov <=
- Re: [Emacs-diffs] emacs-25 f8208b6: Document the user-level features of the Xref package, Eli Zaretskii, 2016/01/11
- Re: [Emacs-diffs] emacs-25 f8208b6: Document the user-level features of the Xref package, Dmitry Gutov, 2016/01/11
- Re: [Emacs-diffs] emacs-25 f8208b6: Document the user-level features of the Xref package, Eli Zaretskii, 2016/01/11
- Re: [Emacs-diffs] emacs-25 f8208b6: Document the user-level features of the Xref package, Dmitry Gutov, 2016/01/11
- Re: [Emacs-diffs] emacs-25 f8208b6: Document the user-level features of the Xref package, Eli Zaretskii, 2016/01/18
- Re: [Emacs-diffs] emacs-25 f8208b6: Document the user-level features of the Xref package, Dmitry Gutov, 2016/01/18
- Re: [Emacs-diffs] emacs-25 f8208b6: Document the user-level features of the Xref package, Eli Zaretskii, 2016/01/19
- Re: [Emacs-diffs] emacs-25 f8208b6: Document the user-level features of the Xref package, Dmitry Gutov, 2016/01/19
- Re: [Emacs-diffs] emacs-25 f8208b6: Document the user-level features of the Xref package, Eli Zaretskii, 2016/01/19
- Re: [Emacs-diffs] emacs-25 f8208b6: Document the user-level features of the Xref package, John Wiegley, 2016/01/20