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

[Dmitry Gutov <dgutov@yandex.ru>]

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.