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

classic Classic list List threaded Threaded
6 messages Options
Reply | Threaded
Open this post in threaded view
|

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 <[hidden email]>
> Commit: Eli Zaretskii <[hidden email]>

> +@findex 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 @w{@kbd{M-x 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}.)

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 @w{@kbd{M-x 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}.)

?

Reply | Threaded
Open this post in threaded view
|

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

Eli Zaretskii
> From: Dmitry Gutov <[hidden email]>
> Date: Mon, 12 Mar 2018 01:15:47 +0200
>
> 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.

This is not about fairness at all, and I'm surprised, to say the
least, that you judge the text in these terms.

This is about describing a command whose only raison d'ĂȘtre is to
provide a "fire escape" when the default method invoked by M-. fails
to find identifiers, because for some reason they are "out of scope"
for that default method.

> 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.

No, I wrote that because it took me some time to find this command,
although I vaguely remembered something like that should be possible.

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

Feel free to point out such place(s) if you find them.

> 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.

Irrelevant.  Once again, this command is only for when M-. fails to
find identifiers, something that shouldn't happen with those more
powerful facilities.

> 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}.)

Thanks, but I see no reason to cloud the issue by refraining from
clearly identifying the situation where this command could be useful.
So I changed the text to make it more accurate, in the hope that it
will no longer lend itself to interpretation that prompted your
reaction.

Reply | Threaded
Open this post in threaded view
|

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

Dmitry Gutov
On 3/12/18 6:04 PM, Eli Zaretskii wrote:

> This is not about fairness at all, and I'm surprised, to say the
> least, that you judge the text in these terms.

Just talking about what impression the wording might leave. Your new
update is better, thank you.

> This is about describing a command whose only raison d'ĂȘtre is to
> provide a "fire escape" when the default method invoked by M-. fails
> to find identifiers, because for some reason they are "out of scope"
> for that default method.

I didn't mean to ascribe any ill intent to the author.

>> 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.
>
> No, I wrote that because it took me some time to find this command,
> although I vaguely remembered something like that should be possible.

Still, there is that scenario from Reddit:

"M-. (bound to xref-find-definitions) can't find any definitions. I
visit-tags-file, set tags-file-name and tags-table-list manaully,
generated the file with etags and ctags, everything. No luck"

Basically, there was no reason to expect navigation to those symbols to
work, except that the user had created and visited a tags table
containing them. So I think the surprise really was that M-. didn't use
the current tags table.

>> So if there's some place in the manual that leaves them with that impression, I think it should be updated.
>
> Feel free to point out such place(s) if you find them.

Upon re-reading, I think the manual is indeed pretty clear. And we can
ascribe the problem mostly to old habits.

> Irrelevant.  Once again, this command is only for when M-. fails to
> find identifiers, something that shouldn't happen with those more
> powerful facilities.

Nothing is perfect, and I'm sure there will be cases when a user sees a
search fail using one of these more advanced systems. The right course
of action there would be to refine their configuration and/or report
bugs to appropriate places, and only then maybe try etags (which could
still produce worse results).

Anyway, I don't have any significant improvements to suggest over the
current wording, in this regard.

> Thanks, but I see no reason to cloud the issue by refraining from
> clearly identifying the situation where this command could be useful.
> So I changed the text to make it more accurate, in the hope that it
> will no longer lend itself to interpretation that prompted your
> reaction.

It's better, thank you.

Also after re-reading, I see some duplication with what's been said
before about how a backend can implement its capabilities in different
ways ("built-in means for looking up"), that first item already lists
the disadvantages. BTW, you mentioned the auto-loaded functions in the
new description of xref-etags-mode, but not in the aforementioned
section above, which is arguably more important.

Anyway, these are minor things, and I don't have any concrete proposals
here.

Reply | Threaded
Open this post in threaded view
|

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

Stefan Monnier
> "M-. (bound to xref-find-definitions) can't find any
> definitions. I visit-tags-file, set tags-file-name and tags-table-list
> manaully, generated the file with etags and ctags, everything. No luck"
>
> Basically, there was no reason to expect navigation to those symbols to
> work, except that the user had created and visited a tags table containing
> them. So I think the surprise really was that M-. didn't use the current
> tags table.

I guess this is due to the fact that M-. used to rely on etags so the
user who hasn't paid attention gets surprised, indeed.

Maybe xref could have an ad-hoc hack which does:
- if there's no match
- and there's a tags table installed.
- and there's a match in the tags table.
- then kindly suggest to the user to activate xref-etags-mode


        Stefan


Reply | Threaded
Open this post in threaded view
|

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

Dmitry Gutov
On 3/13/18 12:43 AM, Stefan Monnier wrote:

> Maybe xref could have an ad-hoc hack which does:
> - if there's no match
> - and there's a tags table installed.
> - and there's a match in the tags table.
> - then kindly suggest to the user to activate xref-etags-mode

Is that going to be a temporary measure? If so, when do we phase it out?

Anyway, here's a patch that somebody could test out:

diff --git a/lisp/progmodes/xref.el b/lisp/progmodes/xref.el
index 5a9a7a925a..bdb1503c2e 100644
--- a/lisp/progmodes/xref.el
+++ b/lisp/progmodes/xref.el
@@ -828,10 +828,19 @@ xref--read-identifier
 
  ;;; Commands

+(defvar xref--warned-about-xref-etags-mode nil)
+
  (defun xref--find-xrefs (input kind arg display-action)
-  (let ((xrefs (funcall (intern (format "xref-backend-%s" kind))
-                        (xref-find-backend)
-                        arg)))
+  (let* ((fun (intern (format "xref-backend-%s" kind)))
+         (xrefs (funcall fun (xref-find-backend) arg)))
+    (unless (or xrefs
+                xref--warned-about-xref-etags-mode)
+      (when (and tags-file-name
+                 (funcall fun 'etags arg))
+        (setq xref--warned-about-xref-etags-mode t)
+        (user-error (concat "No %s found for: %s; did you mean to use
etags?"
+                            " If so, turn on xref-etags-mode")
+                    (symbol-name kind) input)))
      (unless xrefs
        (user-error "No %s found for: %s" (symbol-name kind) input))
      (xref--show-xrefs xrefs display-action)))

Reply | Threaded
Open this post in threaded view
|

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

Stefan Monnier
>> Maybe xref could have an ad-hoc hack which does:
>> - if there's no match
>> - and there's a tags table installed.
>> - and there's a match in the tags table.
>> - then kindly suggest to the user to activate xref-etags-mode
> Is that going to be a temporary measure?

I was thinking about it as something temporary, yes.

> If so, when do we phase it out?

Good question.  Given that the original change was introduced in
Emacs-25.1, it doesn't make sense to keep such a hack very long, so if
it's too late to put it in Emacs-26.1 (which seems likely), then it's
probably too late full stop.


        Stefan