From: Dmitry Gutov <dgutov@yandex.ru>
To: Eli Zaretskii <eliz@gnu.org>
Cc: emacs-devel@gnu.org
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 [thread overview]
Message-ID: <5693FDFA.2070607@yandex.ru> (raw)
In-Reply-To: <831t9pma4e.fsf@gnu.org>
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.
next prev parent reply other threads:[~2016-01-11 19:09 UTC|newest]
Thread overview: 54+ messages / expand[flat|nested] mbox.gz Atom feed top
[not found] <20160109191428.26341.44105@vcs.savannah.gnu.org>
[not found] ` <E1aHyy4-0006rU-Td@vcs.savannah.gnu.org>
2016-01-10 3:02 ` [Emacs-diffs] emacs-25 f8208b6: Document the user-level features of the Xref package Dmitry Gutov
2016-01-10 15:50 ` Eli Zaretskii
2016-01-10 18:05 ` Dmitry Gutov
2016-01-10 18:59 ` Eli Zaretskii
2016-01-10 19:32 ` Dmitry Gutov
2016-01-10 20:51 ` Eli Zaretskii
2016-01-10 21:11 ` Dmitry Gutov
2016-01-11 3:33 ` Eli Zaretskii
2016-01-11 16:55 ` Dmitry Gutov
2016-01-11 17:52 ` Eli Zaretskii
2016-01-11 19:09 ` Dmitry Gutov [this message]
2016-01-11 19:31 ` Eli Zaretskii
2016-01-11 19:41 ` Dmitry Gutov
2016-01-11 20:14 ` Eli Zaretskii
2016-01-11 20:21 ` Dmitry Gutov
2016-01-18 17:31 ` Eli Zaretskii
2016-01-18 22:18 ` Dmitry Gutov
2016-01-19 17:41 ` Eli Zaretskii
2016-01-19 21:53 ` Dmitry Gutov
2016-01-20 4:43 ` Eli Zaretskii
2016-01-20 7:28 ` John Wiegley
2016-01-20 20:53 ` Dmitry Gutov
2016-01-20 21:03 ` John Wiegley
2016-01-20 21:09 ` Dmitry Gutov
2016-01-21 19:01 ` Stephen Leake
2016-01-21 20:32 ` Dmitry Gutov
2016-01-21 3:46 ` Eli Zaretskii
2016-01-21 3:28 ` Dmitry Gutov
2016-01-21 17:29 ` Eli Zaretskii
2016-01-21 18:46 ` Dmitry Gutov
2016-01-21 19:00 ` Eli Zaretskii
2016-01-21 19:46 ` Dmitry Gutov
2016-01-21 20:02 ` Eli Zaretskii
2016-01-21 20:10 ` Dmitry Gutov
2016-01-21 20:32 ` Eli Zaretskii
2016-01-21 21:40 ` Dmitry Gutov
2016-01-24 2:20 ` Dmitry Gutov
2016-01-24 15:29 ` Eli Zaretskii
2016-01-25 20:38 ` Ken Brown
2016-01-25 20:52 ` Eli Zaretskii
2016-01-25 21:29 ` Dmitry Gutov
2016-01-26 2:44 ` Ken Brown
2016-01-26 6:22 ` Dmitry Gutov
2016-01-21 19:19 ` Stephen Leake
2016-01-21 19:26 ` Dmitry Gutov
2016-01-22 7:40 ` Stephen Leake
2016-01-22 8:21 ` Eli Zaretskii
2016-01-22 10:46 ` Dmitry Gutov
2016-01-22 13:37 ` Eli Zaretskii
2016-01-22 10:07 ` Dmitry Gutov
2016-01-21 20:09 ` Eli Zaretskii
2016-01-22 18:16 ` John Yates
2016-01-19 5:36 ` John Wiegley
2016-01-19 5:47 ` Dmitry Gutov
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=5693FDFA.2070607@yandex.ru \
--to=dgutov@yandex.ru \
--cc=eliz@gnu.org \
--cc=emacs-devel@gnu.org \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
Code repositories for project(s) associated with this external index
https://git.savannah.gnu.org/cgit/emacs.git
https://git.savannah.gnu.org/cgit/emacs/org-mode.git
This is an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.