Re: [Emacs-diffs] emacs-26 b1aaa72: Improve documentation of Xref

[Dmitry Gutov]

Hi Eli,

On 3/11/18 7:39 PM, Eli Zaretskii wrote:
> branch: emacs-26
> commit b1aaa72df8e0afd8a849aab7525640f1cec66af3
> Author: Eli Zaretskii <address@hidden>
> Commit: Eli Zaretskii <address@hidden>

> address@hidden xref-etags-mode
> +  Some major modes install @code{xref} support facilities that might
> +fail to find certain identifiers.  For example, in Emacs Lisp mode
> +(@pxref{Lisp Eval}) @kbd{M-.} will by default find only functions and
> +variables from Lisp packages that are loaded into the current Emacs
> +session.  To find more identifiers, turn on the Xref Etags minor mode
> +with @address@hidden xref-etags-mode}}.  This command forces @code{xref}
> +to use the @code{etags} backend (@pxref{Xref}).  (For this to work,
> +you should first run @command{etags} to create the tags table, see
> address@hidden Tags Table}.)

I think that's unfair to all the non-etags Xref backends, both built-in 
and third-party ones.

"Some ... might fail to find", "to find more indentifiers" imply that 
etags always has a bigger and more comprehensive index. Which is not 
entirely true even for the emacs-lisp-mode xref backend. For instance, 
it will navigate to the functions defined inside any of the ELPA 
packages the user has installed. For the etags backend to index them, 
the user has to know to create a tags table there and visit it, which is 
not something many of users tend to do.

More importantly, I think the Reddit user's problem (which has probably 
resulted in this manual update) was that they thought, for some reason, 
that xref-find-definitions will always use the tags table. And that them 
visiting it should affect what xref-find-definitions finds.

So if there's some place in the manual that leaves them with that 
impression, I think it should be updated.

Note that even if the current xref backend were using a system that has 
an all-around more comprehensive index (like GNU Global, or one of the 
LSP servers, etc), the user would still have a problem if they expected 
M-x visit-tags-table to update that index.

So how about something like this:

  Some major modes install @code{xref} support facilities that use a
different index than the current tags table.  For example, in Emacs
Lisp mode (@pxref{Lisp Eval}) @kbd{M-.} will by default search among the
functions and variables from Lisp packages that are loaded into the
current Emacs session.  To consult the tags table instead, turn on the Xref
Etags minor mode with @address@hidden xref-etags-mode}}.  This command
forces @code{xref} to use the @code{etags} backend (@pxref{Xref}).
(For this to work, you should first run @command{etags} to create the
tags table, see @ref{Create Tags Table}.)

?