;;; help-mode.el --- `help-mode' used by *Help* buffers
-;; Copyright (C) 1985-1986, 1993-1994, 1998-2015 Free Software
+;; Copyright (C) 1985-1986, 1993-1994, 1998-2016 Free Software
;; Foundation, Inc.
;; Maintainer: emacs-devel@gnu.org
;;; Code:
(require 'button)
+(require 'cl-lib)
(eval-when-compile (require 'easymenu))
(defvar help-mode-map
(defun help-button-action (button)
"Call BUTTON's help function."
- (help-do-xref (button-start button)
+ (help-do-xref nil
(button-get button 'help-function)
(button-get button 'help-args)))
(define-button-type 'help-symbol
:supertype 'help-xref
- 'help-function #'help-xref-interned
+ 'help-function #'describe-symbol
'help-echo (purecopy "mouse-2, RET: describe this symbol"))
(define-button-type 'help-back
(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"))))
(goto-char (point-min))
(if (re-search-forward
(format "^[ \t]*(\\(cl-\\)?define-compiler-macro[ \t]+%s"
- (regexp-quote (symbol-name fun))) nil t)
+ (regexp-quote (symbol-name fun)))
+ nil t)
(forward-line 0)
(message "Unable to find location in file")))
(message "Unable to find file")))
(setq file (help-C-file-name var 'var)))
(let ((location (find-variable-noselect var 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"))))
;;;###autoload
(defun help-mode-setup ()
+ "Enter Help Mode in the current buffer."
(help-mode)
(setq buffer-read-only nil))
;;;###autoload
(defun help-mode-finish ()
+ "Finalize Help Mode setup in current buffer."
(when (derived-mode-p 'help-mode)
(setq buffer-read-only t)
(help-make-xrefs (current-buffer))))
"\\(source \\(?:code \\)?\\(?:of\\|for\\)\\)\\)"
"[ \t\n]+\\)?"
;; Note starting with word-syntax character:
- "`\\(\\sw\\(\\sw\\|\\s_\\)+\\)'"))
+ "['`‘]\\(\\sw\\(\\sw\\|\\s_\\)+\\)['’]"))
"Regexp matching doc string references to symbols.
The words preceding the quoted symbol can be used in doc strings to
(defconst help-xref-info-regexp
- (purecopy "\\<[Ii]nfo[ \t\n]+\\(node\\|anchor\\)[ \t\n]+`\\([^']+\\)'")
+ (purecopy
+ "\\<[Ii]nfo[ \t\n]+\\(node\\|anchor\\)[ \t\n]+['`‘]\\([^'’]+\\)['’]")
"Regexp matching doc string references to an Info node.")
(defconst help-xref-url-regexp
- (purecopy "\\<[Uu][Rr][Ll][ \t\n]+`\\([^']+\\)'")
+ (purecopy "\\<[Uu][Rr][Ll][ \t\n]+['`‘]\\([^'’]+\\)['’]")
"Regexp matching doc string references to a URL.")
;;;###autoload
(error "Current buffer is not in Help mode"))
(current-buffer))))
+(defvar describe-symbol-backends
+ `((nil ,#'fboundp ,(lambda (s _b _f) (describe-function s)))
+ ("face" ,#'facep ,(lambda (s _b _f) (describe-face s)))
+ (nil
+ ,(lambda (symbol)
+ (or (and (boundp symbol) (not (keywordp symbol)))
+ (get symbol 'variable-documentation)))
+ ,#'describe-variable)))
+
;;;###autoload
(defun help-make-xrefs (&optional buffer)
"Parse and hyperlink documentation cross-references in the given BUFFER.
;; (pop-to-buffer (car location))
;; (goto-char (cdr location))))
(help-xref-button 8 'help-function-def sym))
- ((and
- (facep sym)
- (save-match-data (looking-at "[ \t\n]+face\\W")))
- (help-xref-button 8 'help-face sym))
- ((and (or (boundp sym)
- (get sym 'variable-documentation))
- (fboundp sym))
- ;; We can't intuit whether to use the
- ;; variable or function doc -- supply both.
- (help-xref-button 8 'help-symbol sym))
- ((and
- (or (boundp sym)
- (get sym 'variable-documentation))
- (or
- (documentation-property
- sym 'variable-documentation)
- (documentation-property
- (indirect-variable sym)
- 'variable-documentation)))
- (help-xref-button 8 'help-variable sym))
- ((fboundp sym)
- (help-xref-button 8 'help-function sym)))))))
+ ((cl-some (lambda (x) (funcall (nth 1 x) sym))
+ describe-symbol-backends)
+ (help-xref-button 8 'help-symbol sym)))))))
;; An obvious case of a key substitution:
(save-excursion
(while (re-search-forward
;; Additional functions for (re-)creating types of help buffers.
;;;###autoload
-(defun help-xref-interned (symbol &optional buffer frame)
- "Follow a hyperlink which appeared to be an arbitrary interned SYMBOL.
-Both variable, function and face documentation are extracted into a single
-help buffer. If SYMBOL is a variable, include buffer-local value for optional
-BUFFER or FRAME."
- (with-current-buffer (help-buffer)
- ;; Push the previous item on the stack before clobbering the output buffer.
- (help-setup-xref nil nil)
- (let ((facedoc (when (facep symbol)
- ;; Don't record the current entry in the stack.
- (setq help-xref-stack-item nil)
- (describe-face symbol)))
- (fdoc (when (fboundp symbol)
- ;; Don't record the current entry in the stack.
- (setq help-xref-stack-item nil)
- (describe-function symbol)))
- (sdoc (when (or (boundp symbol)
- (get symbol 'variable-documentation))
- ;; Don't record the current entry in the stack.
- (setq help-xref-stack-item nil)
- (describe-variable symbol buffer frame))))
- (cond
- (sdoc
- ;; We now have a help buffer on the variable.
- ;; Insert the function and face text before it.
- (when (or fdoc facedoc)
- (goto-char (point-min))
- (let ((inhibit-read-only t))
- (when fdoc
- (insert fdoc "\n\n")
- (when facedoc
- (insert (make-string 30 ?-) "\n\n" (symbol-name symbol)
- " is also a " "face." "\n\n")))
- (when facedoc
- (insert facedoc "\n\n"))
- (insert (make-string 30 ?-) "\n\n" (symbol-name symbol)
- " is also a " "variable." "\n\n"))
- ;; Don't record the `describe-variable' item in the stack.
- (setq help-xref-stack-item nil)
- (help-setup-xref (list #'help-xref-interned symbol) nil)))
- (fdoc
- ;; We now have a help buffer on the function.
- ;; Insert face text before it.
- (when facedoc
- (goto-char (point-max))
- (let ((inhibit-read-only t))
- (insert "\n\n" (make-string 30 ?-) "\n\n" (symbol-name symbol)
- " is also a " "face." "\n\n" facedoc))
- ;; Don't record the `describe-function' item in the stack.
- (setq help-xref-stack-item nil)
- (help-setup-xref (list #'help-xref-interned symbol) nil))))
- (goto-char (point-min)))))
+(define-obsolete-function-alias 'help-xref-interned 'describe-symbol "25.1")
\f
;; Navigation/hyperlinking with xrefs
(when (or (boundp sym)
(get sym 'variable-documentation)
(fboundp sym) (facep sym))
- (help-do-xref pos #'help-xref-interned (list sym)))))
+ (help-do-xref pos #'describe-symbol (list sym)))))
(defun help-mode-revert-buffer (_ignore-auto noconfirm)
(when (or noconfirm (yes-or-no-p "Revert help buffer? "))