bug#60587: Patch for adding links to symbols' help documentation

[H. Dieter Wilhelm]

Eli Zaretskii <eliz@gnu.org> writes:

>> +         (is-info (and ifile
>> +                       (or (assoc-string (concat ifi ".info") ifiles)
>> +                           ;; the top info "dir" file
>> +                           (assoc-string (concat ifi ".info.gz") ifiles)
>> +                           ;; info files might be archived!
>> +                           (when pdir (string-match pdir ifile)))
>> +                       (not (assoc-string ifi ndocu)))))
>
> This should probably be extended to allow more extensions; see
> Info-suffix-list.

Please see the latest iteration of patches.

I'm now working on converting the toggle function to a minor-mode, as
Drew and Stefan suggested..

>From b927d91a1bac4330f8a3b0eeab1a9adf30c3786e Mon Sep 17 00:00:00 2001
From: Dieter Wilhelm <dieter@duenenhof-wilhelm.de>
Date: Wed, 25 Jan 2023 22:00:57 +0100
Subject: [PATCH] Info providing buttons on quoted symbols (bug#60587)

*lisp/info.el
---
 lisp/info.el | 401 +++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 401 insertions(+)

diff --git a/lisp/info.el b/lisp/info.el
index 035dff66e75..f5994bf6ce2 100644
--- a/lisp/info.el
+++ b/lisp/info.el
@@ -5510,6 +5510,407 @@ info--manual-names
                                             Info-directory-list
                                             (mapcar #'car 
Info-suffix-list))))))))
 
+
+;;; Commentary:
+
+;; The code below provides links of symbols (functions, variables, and
+;; faces) within Emacs' Info viewer to their builtin help
+;; documentation.  This linking is done when symbol names in texinfo
+;; documentation (like the Emacs- and Elisp manual) are:
+
+;; 1. Quoted symbol names like `symbol-name'.
+
+;; 2. Function names which are prefixed by M-x, for example M-x
+;; function-name or are quoted and prefixed, like `M-x function-name'.
+
+;; 3. Function names appearing behind the following forms, which
+;; occur, for example, in the Elisp manual:
+
+;;   -- Special Form: function-name
+;;   -- Command: ...
+;;   -- Function: ...
+;;   -- Macro: ...
+
+;; 4. And variables names behind the following text:
+
+;;   -- User Option: variable-name
+;;   -- Variable: ...
+
+;; In any case all symbol names must be known to Emacs, which means it
+;; is either a built-in, or its Lisp package is loaded for the current
+;; Emacs session, or the symbol is auto-loaded.
+
+;; You can follow the additional links with the usual Info
+;; keybindings.  The customisation variable
+;; `mouse-1-click-follows-link' is influencing the clicking behavior
+;; (and tooltips) of the links, the variable's default is 450 (milli
+;; seconds) setting it to nil means only clicking with mouse-2 is
+;; following the link (hint: Drew Adams).
+
+;; The link color of symbols - referencing their builtin documentation
+;; - is distinct from links which are referencing further Info
+;; documentation.
+
+;; Below code is checking if Info documents are relevant Elisp and
+;; Emacs related files to avoid false positives.  Please see the
+;; customization variable `info-none-emacs-or-elisp-documents'.
+
+;; The code uses mostly mechanisms from Emacs' lisp/help-mode.el file.
+
+
+;;; Code:
+
+(require 'button)
+(require 'cl-lib)
+(require 'help-mode)
+(require 'cl-seq)
+(require 'subr-x)
+
+(defcustom info-make-xref-flag t
+  "True (`t') means Emacs creates symbol link buttons in Info.
+Setting this variable to `nil' inhibits the creation of buttons
+on quoted symbols to their help strings.  Please see the function
+`info-make-xrefs' for further details."
+  :type '(choice (const :tag "Create link buttons" t)
+                 (const :tag "Do not create link buttons" nil))
+  :set (lambda (sym defs)
+         (custom-set-default sym defs)
+         (let ((fun  (if info-make-xref-flag
+                         #'add-hook
+                       #'remove-hook)))
+           (funcall fun 'Info-selection-hook
+                    'info-make-xrefs)))
+  :version "30.1"
+  :group 'info)
+
+;; Toggle on or off the linking to help documents
+(when info-make-xref-flag
+  ;; Info-selection-hook runs when a node is selected
+  (add-hook 'Info-selection-hook 'info-make-xrefs))
+
+;; TODO: add this toggle in info documentation and NEWS
+;; TODO: remove and create buttons in current info buffer
+(defun info-toggle-make-xrefs ()
+  "Toggle creating Info buttons."
+  (interactive)
+  (if (memq 'info-make-xrefs Info-selection-hook)
+      (remove-hook 'Info-selection-hook 'info-make-xrefs)
+    (add-hook 'Info-selection-hook 'info-make-xrefs)
+    (message "Create Info link buttons to symbol names.")))
+
+(defvar info-emacs-info-dir-content nil
+  "List of file names in Emacs' info directories.
+It is used to check if the current info file `Info-current-file'
+belongs to the Emacs and Elisp context.  This variable will be
+initialised when opening the first info file.")
+
+(defcustom info-none-emacs-or-elisp-documents
+  '("aarm2012"   ; Ada manual from package "ada-ref-man", 2023 on Elpa
+    "aarm2020"   ; Ada manual from package "ada-ref-man", 2023 on Elpa
+    "arm2012"    ; Ada manual from package "ada-ref-man", 2023 on Elpa
+    "arm2020"    ; Ada manual from package "ada-ref-man", 2023 on Elpa
+    "sicp"       ; Structure and Interpretation of Computer Programs,
+                                        ; package "sicp" 2023 on Melpa archive
+    )
+  "List of documentation which is not related to GNU Emacs or Elisp.
+As well as documents which should not be searched for linking to
+help documentation, for more details please see
+`info-check-docu-p'.  The list must contain only the base name of
+info files, e.g. without the file extension \".info\"."
+  :type '(repeat string)
+  :version "30.1"
+  :group 'info)
+
+(defun info-check-docu-p ()
+  "Check if the current info file is relevant to Emacs or Elisp.
+That means `Info-current-file' is either found in Emacs' info/
+directory or in `package-user-dir' and is not included in the
+`info-none-emacs-or-elisp-documents' list."
+  (unless info-emacs-info-dir-content
+    (info-compile-emacs-info-dir-content))
+  (let* ((ifile Info-current-file) ;I-c-f doesn't yield file suffices!
+         (ifi (file-name-nondirectory ifile))
+         ;; Verify that checking pdir is redundant because Package
+         ;; adds info package folders to Info-directory-list
+         (pdir (when (boundp 'package-user-dir)
+                 (expand-file-name
+                  package-user-dir)))
+         (ifiles info-emacs-info-dir-content)
+         (ndocu info-none-emacs-or-elisp-documents)
+         (sufs (mapcar 'car Info-suffix-list))
+         (vars (mapcar #'(lambda (x)(concat ifi x)) sufs))
+         (emacsy (and ifile
+                      (or (cl-intersection vars ifiles :test #'string=)
+                          (when pdir (string-match pdir ifile)))
+                      (not (assoc-string ifi ndocu)))))
+    (if emacsy
+        t)))
+
+(defvar describe-symbol-backends)      ;from help-mode.el
+(defvar help-xref-following)           ;dito
+
+(defvar-keymap info-button-map
+  :doc "Keymap used by buttons in Info buffers."
+  "RET" #'push-button
+  "<mouse-2>" #'push-button
+  "<follow-link>" 'mouse-face
+  "<mode-line> <mouse-2>" #'push-button
+  "<header-line> <mouse-2>" #'push-button)
+
+;; Button types
+
+;; Below parent button inherits Info's quoted symbol face
+;; `Info-quoted'.  Otherwise the buttons would inherit from
+;; button.el's `link' face which looks identical to Info's links.  I
+;; think it is helpful to distinguish both link types because they
+;; also act differently.
+(define-button-type 'info
+  'link t
+  'follow-link t
+  'face 'Info-quoted
+  'keymap info-button-map
+  'action #'info-button-action)
+
+(define-button-type 'info-function
+  :supertype 'info
+  'info-function 'describe-function
+  'help-echo (purecopy "mouse-2, RET: describe this function"))
+
+(define-button-type 'info-variable
+  :supertype 'info
+  'info-function 'describe-variable
+  'help-echo (purecopy "mouse-2, RET: describe this variable"))
+
+(define-button-type 'info-face
+  :supertype 'info
+  'info-function 'describe-face
+  'help-echo (purecopy "mouse-2, RET: describe this face"))
+
+(define-button-type 'info-symbol
+  :supertype 'info
+  'info-function #'describe-symbol
+  'help-echo (purecopy "mouse-2, RET: describe this symbol"))
+
+(define-button-type 'info-function-def
+  :supertype 'info
+  'info-function (lambda (fun &optional file type)
+                   (or file
+                       (setq file (find-lisp-object-file-name fun type)))
+                   (if (not file)
+                       (message "Unable to find defining file")
+                     (require 'find-func)
+                     (when (eq file 'C-source)
+                       (setq file
+                             (help-C-file-name (indirect-function fun) 'fun)))
+                     ;; Don't use find-function-noselect because it follows
+                     ;; aliases (which fails for built-in functions).
+                     (let ((location
+                            (find-function-search-for-symbol fun type file)))
+                       (pop-to-buffer (car location))
+                       (run-hooks 'find-function-after-hook)
+                       (if (cdr location)
+                           (goto-char (cdr location))
+                         (message "Unable to find location in file")))))
+  'help-echo (purecopy "mouse-2, RET: find function's definition"))
+
+(defun info-compile-emacs-info-dir-content ()
+  "Build a list of file names from Emacs' info directories.
+This function fills `info-emacs-info-dir-content' with files from
+`Info-directory-list'."
+  (setq info-emacs-info-dir-content
+        (mapcar 'file-name-nondirectory
+                (directory-files
+                 (car
+                  ;; search for the main Emacs' info/ directory, when this
+                  ;; function is called Info-directory-list is already
+                  ;; initialised
+                  (cl-member "[^.]emacs" Info-directory-list :test
+                             'string-match-p))
+                 ;; don't list "." and ".."
+                 t  "[^.]$"))))
+
+(defun info-button-action (button)
+  "Call BUTTON's help function."
+  (info-do-xref nil
+                (button-get button 'info-function)
+                (button-get button 'info-args)))
+
+(defun info-do-xref (_pos function args)
+  "Call the help cross-reference function FUNCTION with args ARGS.
+Things are set up properly so that the resulting `help-buffer' has
+a proper [back] button."
+  ;; There is a reference at point.  Follow it.
+  (let ((help-xref-following nil))
+    (apply
+     function (if (eq function 'info)
+                  (append args (list (generate-new-buffer-name 
"*info*")))args))))
+
+(defun info-button (match-number type &rest args)
+  "Make a hyperlink for cross-reference text previously matched.
+MATCH-NUMBER is the subexpression of interest in the last matched
+regexp.  TYPE is the type of button to use.  Any remaining
+arguments are passed to the button's info-function when it is
+invoked.  See `info-make-xrefs'.  Don't forget ARGS."
+  ;; Don't munge properties we've added, especially in some instances.
+  (unless (button-at (match-beginning match-number))
+    (make-text-button (match-beginning match-number)
+                      (match-end match-number)
+                      'type type 'info-args args)))
+
+(defvar info-symbol-context
+  '((variable . "variable\\|option")
+    (function . "function\\|command\\|call")
+    (face . "face")
+    ;; ignore symbols following this context type
+    (ignore . "symbol\\|program\\|property")
+    ;; function definitions in files
+    (definition . "source \\(?:code \\)?\\(?:of\\|for\\)"))
+  "This list helps to distinguish symbol types.
+Words in info documentation preceding a (quoted) symbol are used
+to distinguish variables, functions, faces and symbols.  The
+context information can also be used to ignore symbols because
+there is no help documentation for them.  The strings of the the
+list are becoming part of `info-symbol-regexp'.")
+
+(defvar info-symbol-regexp
+  ;; use purecopy?
+  (concat
+   "\\("                                ; Context start
+   "\\<\\("                             ; Contex type definition
+   (string-remove-suffix
+    "\\|"
+    (mapconcat
+     (lambda (x) (concat "\\(" (cdr x) "\\)\\|"))
+     info-symbol-context ""))
+   "\\)"          ; Context type definition end
+   "[ \t\n]+"     ; Separators to quoted symbols
+   "\\)?"         ; End of context
+   ;; quoted symbol
+   "['`‘]"       ; opening quotes
+   ;; Note: Symbol starting with word-syntax character:
+   "\\(\\sw\\(\\sw\\|\\s_\\)+\\|`\\)" ; The symbol itself
+   "['’]"                             ; End quotes
+   )
+  "The regular expression for matching symbols to their help documentation.
+It is comprised of the symbol's context and the (quoted) symbol
+name.  The various groups of context regular expressions are
+matched in `info-make-xrefs' to distinct info buttons.")
+
+(defun info-check-type( type)
+  "Check if TYPE corresponds to the current search result.
+The function is used in `info-make-xrefs'."
+  (let* ((isc info-symbol-context)
+        (n 3)                           ;embedded within 2 groups
+         (l (+ 3 (length isc))))
+    (while (and (not (eq type (caar isc) ) ) (< n l) )
+      (setq n (1+ n))
+      (setq isc (cdr isc)))
+    (match-string n)))
+
+
+;;;###autoload
+(defun info-make-xrefs (&optional buffer)
+  "Parse and hyperlink documentation cross-references in the given BUFFER.
+BUFFER defaults to the current buffer if omitted or nil.  Find
+cross-reference information in a buffer and activate such cross
+references for selection with `help-follow'.
+
+ Cross-references have the canonical (quoted) form `symbol-name'
+and the type of reference may be disambiguated by the preceding
+word(s) as compiled in `info-symbol-regexp'.  For example: Symbol
+names are receiving distinct variable buttons when preceeded by
+the words \"variable\" or \"option\".
+
+Variables are also detected when their names follow below form:
+
+ -- User Option: variable-name
+ -- Variable: ...
+
+Function names are also detected when prefixed by `M-x', for
+example `M-x function-name' or are quoted and prefixed like `M-x
+function-name'.
+
+Function names are detected, as well, when appearing behind the
+following forms, which occur - for example - in the Elisp manual:
+
+ -- Special Form: function-name
+ -- Command: ...
+ -- Function: ...
+ -- Macro: ...
+
+The linking is similar to mechanisms from lisp/help.el."
+  (interactive "b")
+  (when (info-check-docu-p)
+    (with-current-buffer (or buffer (current-buffer))
+      (save-excursion
+        (goto-char (point-min))
+        (with-silent-modifications      ;hint from Stefan
+          (let ((case-fold-search t)
+                (inhibit-read-only t))
+            (with-syntax-table emacs-lisp-mode-syntax-table
+              ;; Quoted symbols
+              (save-excursion
+                (while (re-search-forward info-symbol-regexp nil t)
+                  (let* ((sym-group (+ 3 (length info-symbol-context)))
+                         (data (match-string sym-group))
+                         (sym (intern-soft data)))
+                    (if sym
+                        (cond
+                         ((info-check-type 'variable)
+                          (and (or (boundp sym)
+                                   (get sym 'variable-documentation))
+                               (info-button sym-group 'info-variable sym)))
+                         ((info-check-type 'function)
+                          (and (fboundp sym)
+                               (info-button sym-group 'info-function sym)))
+                         ((info-check-type 'face)
+                          (and (facep sym)
+                               (info-button sym-group 'info-face sym)))
+                         ((info-check-type 'ignore))
+                         ((info-check-type 'definition)
+                          (info-button sym-group 'info-function-def sym))
+                         ;; symbols
+                         ((cl-some (lambda (x) (funcall (nth 1 x) sym))
+                                   describe-symbol-backends)
+                          (info-button sym-group 'info-symbol sym)))))))
+              ;; ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
+              ;; (info "(elisp) Eval")
+              ;; Elisp manual      -- Special Form:
+              ;;                   -- Command:
+              ;;                   -- Function: function-name function
+              ;;                   -- Macro:
+              (save-excursion
+                (while (re-search-forward
+                        "-- \\(Special 
Form:\\|Command:\\|Function:\\|Macro:\\) "
+                        nil t)
+                  (looking-at "\\(\\sw\\|\\s_\\)+")
+                  (let ((sym (intern-soft (match-string 0))))
+                    (if (fboundp sym)
+                        (info-button 0 'info-function sym)))))
+              ;;              -- User Option:
+              ;;              -- Variable: variable-name
+              (save-excursion
+                (while (re-search-forward
+                        "-- \\(User Option:\\|Variable:\\) "
+                        nil t)
+                  (looking-at "\\(\\sw\\|\\s_\\)+")
+                  (let ((sym (intern-soft (match-string 0))))
+                    (if (boundp sym)
+                        (info-button 0 'info-variable sym)))))
+              ;; M-x prefixed functions
+              (save-excursion
+                (while (re-search-forward
+                        ;; Assume command name is only word and symbol
+                        ;; characters to get things like `use M-x foo->bar'.
+                        ;; Command required to end with word constituent
+                        ;; to avoid `.' at end of a sentence.
+                        ;; "\\<M-x\\s-+\\(\\sw\\(\\sw\\|\\s_\\)*\\sw\\)" nil t)
+                        ;; include M-x and quotes
+                        
"['`‘]?M-x\\s-*\n?\\(\\sw\\(\\sw\\|\\s_\\)*\\sw\\)['’]?" nil t)
+                  (let ((sym (intern-soft (match-string 1))))
+                    (if (fboundp sym)
+                        (info-button 1 'info-function sym))))))))))))
+
 (provide 'info)
 
 ;;; info.el ends here
-- 
2.34.1

>From eaf3ad409e1ec29bb1207db44e17fa27cda0f5d2 Mon Sep 17 00:00:00 2001
From: Dieter Wilhelm <dieter@duenenhof-wilhelm.de>
Date: Wed, 1 Feb 2023 22:01:19 +0100
Subject: [PATCH] Documentation of Info providing buttons on quoted symbols
 (bug#60587)

* doc/emacs/help.texi
* etc/NEWS
---
 doc/emacs/help.texi | 13 +++++++++++++
 etc/NEWS            | 11 +++++++++++
 2 files changed, 24 insertions(+)

diff --git a/doc/emacs/help.texi b/doc/emacs/help.texi
index 2513e6be271..18a223b228f 100644
--- a/doc/emacs/help.texi
+++ b/doc/emacs/help.texi
@@ -653,6 +653,19 @@ Misc Help
 K @var{key}}, described above, enter Info and go straight to the
 documentation of @var{function} or @var{key}.
 
+  Info makes quoted symbol names into buttons which show the symbols'
+help documentation when typing @key{RET} or clicking the mouse
+(@pxref{Mouse References}).  For example, the quoted name
+@code{info-other-window} is made into a button which shows the
+function's documentation string in another window, in the
+@file{*Help*} buffer.  Info highlights such quoted symbols (variables,
+functions and face names) by a distinct face and these can be reached,
+as regular Info manual references, with @key{TAB} and @kbd{S-Tab}.
+
+@vindex info-make-xref-flag
+  If you want to prohibit the button creation for Info buffers, you
+can set @code{info-make-xref-flag} to @code{nil}.
+
 @kindex C-h S
 @findex info-lookup-symbol
   When editing a program, if you have an Info version of the manual
diff --git a/etc/NEWS b/etc/NEWS
index 5b8ab06086c..c55d39baf0c 100644
--- a/etc/NEWS
+++ b/etc/NEWS
@@ -195,6 +195,17 @@ This command adds a docstring comment to the current 
defun.  If a
 comment already exists, point is only moved to the comment.  It is
 bound to 'C-c C-d' in 'go-ts-mode'.
 
+** Info
+
++++
+*** Info-mode provides buttons on symbols showing their documentation string.
+Quoted `symbols', like names of variables, functions or face names,
+are made into buttons which can display the respective documentation
+strings.  These strings are presented in *Help* buffers in another
+window.  Such buttons are working independently of the regular Info
+cross references and can be disabled with setting
+`info-make-xref-flag' to nil.
+
 
 * New Modes and Packages in Emacs 30.1
 
-- 
2.34.1


-- 
Best wishes
H. Dieter Wilhelm
Zwingenberg, Germany