From: Dmitry Gutov <dgutov@yandex.ru>
To: emacs-devel@gnu.org, Eli Zaretskii <eliz@gnu.org>
Subject: Re: [Emacs-diffs] emacs-25 f8208b6: Document the user-level features of the Xref package
Date: Sun, 10 Jan 2016 06:02:42 +0300 [thread overview]
Message-ID: <5691C9D2.7080905@yandex.ru> (raw)
In-Reply-To: <E1aHyy4-0006rU-Td@vcs.savannah.gnu.org>
Hi Eli,
Thanks for doing this.
I've noticed some problems, though, described below:
On 01/09/2016 10:14 PM, Eli Zaretskii wrote:
> +Emacs provides a unified user interface to these tools, called
> +@samp{xref}. The tools supported by @samp{xref} include:
> +...
> +@acronym{GNU} GLOBAL, the source code tagging system, which provides
> ...
> +Cscope (@uref{http://cscope.sourceforge.net/}, a tool for browsing
> ...
> +@acronym{GNU} IDUtils, a package for generating databases of
> ...
> +Grep, the venerable program that searches files for lines matching
> ...
> +Additional tools could be supported as they become available, or as
> +user extensions. Each such tool is used as a @dfn{backend} by
> +commands described in this section. Each command detects which
> +backends are available for the current major mode, and uses the most
> +capable of the available backends, with Grep generally serving as the
> +fall-back backend.
Sorry, this is not true, unfortunately, as things currently stand.
We don't use GNU Global, Cscope, ID Utils, or Grep as xref backends. We
can't "find definitions" using any of them, for example, even though the
user might expect to be able to do so.
The only place where the aforementioned tools are used, is in the
_default_ implementation of the generic function
xref-backend-references. IOW, the implementation that gets used when the
current backend doesn't provide its own.
> +@cindex tag
> +The commands described here are useful for finding references in major
> +modes other than those defined to support programming languages. For
> +example, chapters, sections, appendices, etc. of a text or a @TeX{}
> +document can be treated as identifiers as well. In this chapter, we
> +collectively refer to a reference that specifies the name of the file
> +where the corresponding subunit is defined, and the position of the
> +subunit's definition in that file, as a @dfn{tag}. We refer to the
> +backends used by @code{xref} as @dfn{tagging backends}.
"tagging backends"? Why not call them "Xref backends", like referred to
in the Xref commentary and the docstrings?
I wouldn't say that the current terminology in Xref is perfect (the name
itself encroaches on info-xref.el, for instance), but introducing terms
that are only used in the manual, won't help clarity.
Why not submit a patch for xref.el first?
> +@node Identifier Search
> +@subsubsection Searching and Replacing with Identifiers
> +@cindex search and replace in multiple files
> +@cindex multiple-file search and replace
> +
> + The commands in this section visit and search all the files listed
> +in the @code{xref} backend's database, one by one. For these
> +commands, the database serves only to specify a sequence of files to
> +search.
That may be true for tags-search, but that's never true for
xref-find-references.
If the current backend defines xref-backend-references, then we just ask
it, and show the results.
If it doesn't, we delegate to the first available "CEDET tool", but they
do perform the regexp search, not just list the files. Then,
xref-collect-references takes the list of matches and verified, for each
one, whether the match begins and ends on a symbol boundary (Grep can't
check that).
> These commands scan all the databases starting with the first
> +one (if any) that describes the current file, proceed from there to
> +the end of the list, and then scan from the beginning of the list
> +until they have covered all the databases in the list.
What list? xref definitely uses one database at a time (per project
root, if we're talking about the default implementation).
> +@findex tags-search
> + @kbd{M-x tags-search} reads a regexp using the minibuffer, then
> +searches for matches in all the files in the selected tags table, one
> +file at a time. It displays the name of the file being searched so
> +you can follow its progress. As soon as it finds an occurrence,
> +@code{tags-search} returns. This command works only with the etags
> +backend, and requires tags tables to be available (@pxref{Tags
> +Tables}).
The last sentence makes it seem like it goes through the xref machinery,
whereas it doesn't.
> +@findex tags-loop-continue
> + Having found one match, you probably want to find all the rest.
> +Type @kbd{M-x tags-loop-continue}) to resume the @code{tags-search},
> +finding one more match. This searches the rest of the current buffer,
> +followed by the remaining files of the tags table.
This makes it seem like tags-loop-continue is applicable for use after
xref-find-* commands as well. But it isn't.
Maybe this command, as well as tags-query-replace, the other etags-only
commands, and the related etags variables, should still remain in a
separate section?
> +@node List Identifiers
> +@subsubsection Identifier Inquiries
> +
> +@table @kbd
> +@item C-M-i
> +@itemx M-@key{TAB}
> +Perform completion on the text around point, using the @code{xref}
> +backend if one is available (@code{completion-at-point}).
If I understand this sentence right, it's inaccurate: xref backends
don't define completion tables for buffer text. It is still governed by
completion-at-point-functions.
xref-backend-identifier-completion-table is only used for completion in
the prompt when reading an identifier, by xref commands.
> +@c Sadly, the new-and-improved Xref feature doesn't provide anything
> +@c close to the described below features of the now-obsoleted
> +@c tags-apropos. I'm leaving this here to encourage enhancements to
> +@c xref.el.
Writing this complaint in the manual, expecting it to be read by someone
likely to produce enhancements to xref.el, seems rather optimistic.
Please submit a feature request (or several, if they're distinct).
Displaying the tags files names should be possible after the xref
rendering logic becomes more flexible (and e.g. could be supplied by the
backend).
> mode is enabled, it tries to use the Semantic parser data for
> completion (@pxref{Semantic}). If Semantic mode is not enabled or
> fails at performing completion, it tries to complete using the
> -selected tags table (@pxref{Tags}). If in Emacs Lisp mode, it
> +available @code{xref} backend (@pxref{Xref}).
Also not true. Like mentioned, we don't use xref backends for
completion. Unifying in-buffer completion and xref identifier completion
might be beneficial, but it's not easy to do.
next parent reply other threads:[~2016-01-10 3:02 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 ` Dmitry Gutov [this message]
2016-01-10 15:50 ` [Emacs-diffs] emacs-25 f8208b6: Document the user-level features of the Xref package 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
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=5691C9D2.7080905@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.