Subject: bug#36767: 26.1; request: add more quick keys to the *Help* buffer

From: Lars Ingebrigtsen <[email-masked]>
Date: Thu, 23 Sep 2021 22:52:59 +0200

Arthur Miller <[email-masked]> writes:

> You can see how it looks like. I have attached a small screenshot too,
> so you don't need to apply it just to see how it looks like. The file
> name at the end of the header is probably clear on it's own; the
> symbol link is as clear/unclear as rest of the links in the buffer.

(You're doing all these mails in a bug report that has been archived, so
the only other people who's reading them are the ones in the CCs.  If
you wish to discuss things publicly, either do so in emacs-devel or open
a new bug report.)

I fixed up your patch so that it works more reliably, but then I
remembered why I didn't add the link: We don't know at this point
whether the symbol in question is documented in the manual.  Adding a
link to something that fails is bad UI.  And we can't check whether the
symbol exists in the manual when generating the *Help* buffer, because
it's slow, and the trade-off (making the command slow versus an extra
link) is not a good one.

-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no

diff --git a/lisp/help-mode.el b/lisp/help-mode.el
index 551cf7e1a3..4d6d13ea42 100644
--- a/lisp/help-mode.el
+++ b/lisp/help-mode.el
@@ -367,6 +367,11 @@ 'help-news
     (view-buffer-other-window (find-file-noselect file))
     (goto-char pos))
   'help-echo (purecopy "mouse-2, RET: show corresponding NEWS announcement"))
+
+(define-button-type 'help-symbol-info
+  :supertype 'help-xref
+  'help-function #'help-goto-info
+  'help-echo (purecopy "mouse-2, RET: read this info node"))
 
 (defvar bookmark-make-record-function)
 (defvar help-mode--current-data nil)
@@ -538,6 +543,15 @@ help-make-xrefs
           ;; The following should probably be abstracted out.
           (unwind-protect
               (progn
+                ;; Make a button of the first time the symbol appears
+                ;; in the buffer.
+                (save-excursion
+                  (when-let ((symbol (plist-get help-mode--current-data
+                                                :symbol)))
+                    (when (or (symbolp symbol) (fboundp symbol))
+                      (goto-char (point-min))
+                      (when (search-forward (symbol-name symbol) nil t)
+                        (help-xref-button 0 'help-symbol-info)))))
                 ;; Info references
                 (save-excursion
                   (while (re-search-forward help-xref-info-regexp nil t)