[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
bug#60587: Patch for adding links to symbols' help documentation
From: |
H. Dieter Wilhelm |
Subject: |
bug#60587: Patch for adding links to symbols' help documentation |
Date: |
Wed, 01 Feb 2023 22:26:52 +0100 |
User-agent: |
Gnus/5.13 (Gnus v5.13) |
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
- bug#60587: Patch for adding links to symbols' help documentation,
H. Dieter Wilhelm <=
- bug#60587: Patch for adding links to symbols' help documentation, H. Dieter Wilhelm, 2023/02/01
- bug#60587: Patch for adding links to symbols' help documentation, H. Dieter Wilhelm, 2023/02/04
- bug#60587: Patch for adding links to symbols' help documentation, Stefan Monnier, 2023/02/04
- bug#60587: Patch for adding links to symbols' help documentation, H. Dieter Wilhelm, 2023/02/12
- bug#60587: Patch for adding links to symbols' help documentation, Stefan Monnier, 2023/02/14
- bug#60587: Patch for adding links to symbols' help documentation, H. Dieter Wilhelm, 2023/02/15
- bug#60587: Patch for adding links to symbols' help documentation, Stefan Monnier, 2023/02/15