bug#69462: 29.2.50; describe-function should support finding references

bug#69462: 29.2.50; describe-function should support finding references

[Spencer Baugh]

In emacs-lisp-mode in an Emacs git checkout, M-? (xref-find-references)
nicely searches the load path for references to a symbol.

It would be neat if this feature could be accessed from
describe-function and describe-variable as well, perhaps by just hitting
M-? in the help buffer.

The feature may need to be redesigned somewhat, since it's currently
dependent on being run from a project; to use it from a
describe-function help buffer, we'd want to only search the load-path.


In GNU Emacs 29.2.50 (build 4, x86_64-pc-linux-gnu, X toolkit, cairo
 version 1.15.12, Xaw scroll bars) of 2024-02-28 built on
 igm-qws-u22796a
Repository revision: 46e23709d37943a20faa735c97af520196a443e9
Repository branch: emacs-29
Windowing system distributor 'The X.Org Foundation', version 11.0.12011000
System Description: Rocky Linux 8.9 (Green Obsidian)

Configured using:
 'configure 'CFLAGS=-O0 -g3' --with-gif=ifavailable
 --with-x-toolkit=lucid'

Configured features:
CAIRO DBUS FREETYPE GLIB GMP GNUTLS GSETTINGS HARFBUZZ JPEG JSON
LIBSELINUX LIBSYSTEMD LIBXML2 MODULES NOTIFY INOTIFY PDUMPER PNG RSVG
SECCOMP SOUND SQLITE3 THREADS TIFF TOOLKIT_SCROLL_BARS X11 XDBE XIM
XINPUT2 XPM LUCID ZLIB

Important settings:
  value of $LANG: en_US.UTF-8
  locale-coding-system: utf-8-unix

Major mode: Lisp Interaction

Minor modes in effect:
  tooltip-mode: t
  global-eldoc-mode: t
  eldoc-mode: t
  show-paren-mode: t
  electric-indent-mode: t
  mouse-wheel-mode: t
  tool-bar-mode: t
  menu-bar-mode: t
  file-name-shadow-mode: t
  global-font-lock-mode: t
  font-lock-mode: t
  blink-cursor-mode: t
  line-number-mode: t
  indent-tabs-mode: t
  transient-mark-mode: t
  auto-composition-mode: t
  auto-encryption-mode: t
  auto-compression-mode: t

Load-path shadows:
None found.

Features:
(help-mode pp shadow sort mail-extr emacsbug message mailcap yank-media
puny dired dired-loaddefs rfc822 mml mml-sec password-cache epa derived
epg rfc6068 epg-config gnus-util text-property-search time-date subr-x
mm-decode mm-bodies mm-encode mail-parse rfc2231 mailabbrev gmm-utils
mailheader cl-loaddefs cl-lib sendmail rfc2047 rfc2045 ietf-drums
mm-util mail-prsvr mail-utils rmc iso-transl tooltip cconv eldoc paren
electric uniquify ediff-hook vc-hooks lisp-float-type elisp-mode mwheel
term/x-win x-win term/common-win x-dnd tool-bar dnd fontset image
regexp-opt fringe tabulated-list replace newcomment text-mode lisp-mode
prog-mode register page tab-bar menu-bar rfn-eshadow isearch easymenu
timer select scroll-bar mouse jit-lock font-lock syntax font-core
term/tty-colors frame minibuffer nadvice seq simple cl-generic
indonesian philippine cham georgian utf-8-lang misc-lang vietnamese
tibetan thai tai-viet lao korean japanese eucjp-ms cp51932 hebrew greek
romanian slovak czech european ethiopic indian cyrillic chinese
composite emoji-zwj charscript charprop case-table epa-hook
jka-cmpr-hook help abbrev obarray oclosure cl-preloaded button loaddefs
theme-loaddefs faces cus-face macroexp files window text-properties
overlay sha1 md5 base64 format env code-pages mule custom widget keymap
hashtable-print-readable backquote threads dbusbind inotify
dynamic-setting system-font-setting font-render-setting cairo x-toolkit
xinput2 x multi-tty make-network-process emacs)

Memory information:
((conses 16 66391 8487)
 (symbols 48 9599 1)
 (strings 32 23263 2684)
 (string-bytes 1 688577)
 (vectors 16 10405)
 (vector-slots 8 158153 18632)
 (floats 8 44 18)
 (intervals 56 259 0)
 (buffers 976 11))

bug#69462: 29.2.50; describe-function should support finding references

[Dmitry Gutov]

[-- Attachment #1: Type: text/plain, Size: 974 bytes --]

Hi!

On 28/02/2024 19:31, Spencer Baugh wrote:
> 
> In emacs-lisp-mode in an Emacs git checkout, M-? (xref-find-references)
> nicely searches the load path for references to a symbol.
> 
> It would be neat if this feature could be accessed from
> describe-function and describe-variable as well, perhaps by just hitting
> M-? in the help buffer.
> 
> The feature may need to be redesigned somewhat, since it's currently
> dependent on being run from a project; to use it from a
> describe-function help buffer, we'd want to only search the load-path.

Reusing the Elisp backend seems the easiest approach.

Caveats:

* You need to press RET after M-? like anywhere else (unless 
xref-prompt-for-identifier is customized).
* A bit hackish change in 'xref-backend-definitions'.

Pros:

* Both M-? and M-. work on anything that looks like symbol in the help 
buffer, quoted or not - though there will be false positives like usual.
* Can be similarly added to cl-describe-type.

[-- Attachment #2: help-fns--setup-xref-backend.diff --]
[-- Type: text/x-patch, Size: 1825 bytes --]

diff --git a/lisp/help-fns.el b/lisp/help-fns.el
index e1daa8977f0..ac424a9d028 100644
--- a/lisp/help-fns.el
+++ b/lisp/help-fns.el
@@ -262,6 +262,11 @@ help-fns--describe-function-or-command-prompt
                   fn))
     (list fn)))
 
+(defun help-fns--setup-xref-backend ()
+  (add-hook 'xref-backend-functions #'elisp--xref-backend nil t)
+  (setq-local project-vc-external-roots-function #'elisp-load-path-roots)
+  (setq-local semantic-symref-filepattern-alist '((help-mode "*.el"))))
+
 ;;;###autoload
 (defun describe-function (function)
   "Display the full documentation of FUNCTION (a symbol).
@@ -287,6 +292,7 @@ describe-function
 
     (save-excursion
       (with-help-window (help-buffer)
+        (help-fns--setup-xref-backend)
         (if (get function 'reader-construct)
             (princ function)
           (prin1 function))
@@ -1348,6 +1354,8 @@ describe-variable
 	      (prin1 variable)
 	      (setq file-name (find-lisp-object-file-name variable 'defvar))
 
+              (help-fns--setup-xref-backend)
+
 	      (princ (if file-name
 		         (progn
 		           (princ (format-message
diff --git a/lisp/progmodes/elisp-mode.el b/lisp/progmodes/elisp-mode.el
index 63bd685af91..2f931daedc7 100644
--- a/lisp/progmodes/elisp-mode.el
+++ b/lisp/progmodes/elisp-mode.el
@@ -1049,7 +1049,9 @@ xref-backend-definitions
   (let ((sym (intern-soft identifier)))
     (when sym
       (let* ((pos (get-text-property 0 'pos identifier))
-             (namespace (if pos
+             (namespace (if (and pos
+                                 ;; Reusing it in Help Mode.
+                                 (derived-mode-p 'emacs-lisp-mode))
                             (elisp--xref-infer-namespace pos)
                           'any))
              (defs (elisp--xref-find-definitions sym)))

bug#69462: 29.2.50; describe-function should support finding references

[Dmitry Gutov]

Pushed to master in revision c8ecd7fa0da. Closing, but feedback welcome.

On 28/09/2024 02:01, Dmitry Gutov wrote:
> Hi!
> 
> On 28/02/2024 19:31, Spencer Baugh wrote:
>>
>> In emacs-lisp-mode in an Emacs git checkout, M-? (xref-find-references)
>> nicely searches the load path for references to a symbol.
>>
>> It would be neat if this feature could be accessed from
>> describe-function and describe-variable as well, perhaps by just hitting
>> M-? in the help buffer.
>>
>> The feature may need to be redesigned somewhat, since it's currently
>> dependent on being run from a project; to use it from a
>> describe-function help buffer, we'd want to only search the load-path.
> 
> Reusing the Elisp backend seems the easiest approach.
> 
> Caveats:
> 
> * You need to press RET after M-? like anywhere else (unless xref- 
> prompt-for-identifier is customized).
> * A bit hackish change in 'xref-backend-definitions'.
> 
> Pros:
> 
> * Both M-? and M-. work on anything that looks like symbol in the help 
> buffer, quoted or not - though there will be false positives like usual.
> * Can be similarly added to cl-describe-type.

bug#69462: 29.2.50; describe-function should support finding references

[Eshel Yaron via Bug reports for GNU Emacs, the Swiss army knife of text editors]

Hi,

Dmitry Gutov <dmitry@gutov.dev> writes:

> Pushed to master in revision c8ecd7fa0da. Closing, but feedback welcome.

Looks nice!  What's somewhat nonideal is that the ELisp-specific Xref
setup lingers in the Help buffer even if it is reused for other purposes
(like dictionary words when dictionary-display-definition-function is
set to dictionary-display-definition-in-help-buffer).

Perhaps help-setup-xref should kill the local variables that
help-fns--setup-xref-backend now sets?


Cheers,

Eshel

bug#69462: 29.2.50; describe-function should support finding references

[Dmitry Gutov]

On 03/10/2024 03:07, Dmitry Gutov wrote:
> Pushed to master in revision c8ecd7fa0da. Closing, but feedback welcome.

And a follow-u commit ad529831018, to really make it never ask for project.

bug#69462: 29.2.50; describe-function should support finding references

[Dmitry Gutov]

On 03/10/2024 10:14, Eshel Yaron wrote:
> Looks nice!  What's somewhat nonideal is that the ELisp-specific Xref
> setup lingers in the Help buffer even if it is reused for other purposes
> (like dictionary words when dictionary-display-definition-function is
> set to dictionary-display-definition-in-help-buffer).
> 
> Perhaps help-setup-xref should kill the local variables that
> help-fns--setup-xref-backend now sets?

Thanks, good idea, pushed as bde00266db4.

bug#69462: 29.2.50; describe-function should support finding references

[Eshel Yaron via Bug reports for GNU Emacs, the Swiss army knife of text editors]

Dmitry Gutov <dmitry@gutov.dev> writes:

> On 03/10/2024 10:14, Eshel Yaron wrote:
>> Looks nice!  What's somewhat nonideal is that the ELisp-specific Xref
>> setup lingers in the Help buffer even if it is reused for other purposes
>> (like dictionary words when dictionary-display-definition-function is
>> set to dictionary-display-definition-in-help-buffer).
>> Perhaps help-setup-xref should kill the local variables that
>> help-fns--setup-xref-backend now sets?
>
> Thanks, good idea, pushed as bde00266db4.

Great, I pushed a small fix for this change in 9f54f24e94d, and I
submitted a patch in bug#73637 that generalizes this kind of clean up.


Best,

Eshel

bug#69462: 29.2.50; describe-function should support finding references

[Dmitry Gutov]

On 05/10/2024 10:20, Eshel Yaron wrote:
> Great, I pushed a small fix for this change in 9f54f24e94d, and I
> submitted a patch in bug#73637 that generalizes this kind of clean up.

Thanks!