397 lines
18 KiB
EmacsLisp
397 lines
18 KiB
EmacsLisp
|
;;; help-mode+.el --- Extensions to `help-mode.el'
|
||
|
|
;;
|
||
|
|
;; Filename: help-mode+.el
|
||
|
|
;; Description: Extensions to `help-mode.el'
|
||
|
|
;; Author: Drew Adams
|
||
|
|
;; Maintainer: Drew Adams (concat "drew.adams" "@" "oracle" ".com")
|
||
|
|
;; Copyright (C) 2004-2018, Drew Adams, all rights reserved.
|
||
|
|
;; Created: Sat Nov 06 15:14:12 2004
|
||
|
|
;; Version: 0
|
||
|
|
;; Package-Requires: ()
|
||
|
|
;; Last-Updated: Mon Jan 1 13:28:45 2018 (-0800)
|
||
|
|
;; By: dradams
|
||
|
|
;; Update #: 215
|
||
|
|
;; URL: https://www.emacswiki.org/emacs/download/help-mode%2b.el
|
||
|
|
;; Doc URL: https://emacswiki.org/emacs/HelpPlus
|
||
|
|
;; Keywords: help
|
||
|
|
;; Compatibility: GNU Emacs: 22.x, 23.x, 24.x, 25.x, 26.x
|
||
|
|
;;
|
||
|
|
;; Features that might be required by this library:
|
||
|
|
;;
|
||
|
|
;; `button', `help-mode', `view'.
|
||
|
|
;;
|
||
|
|
;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
|
||
|
|
;;
|
||
|
|
;;; Commentary:
|
||
|
|
;;
|
||
|
|
;; Extensions to `help-mode.el'
|
||
|
|
;;
|
||
|
|
;;
|
||
|
|
;; ***** NOTE: The following functions defined in `help-mode.el'
|
||
|
|
;; have been REDEFINED HERE:
|
||
|
|
;;
|
||
|
|
;; `help-make-xrefs' - Put symbol clause first, so cross-xref links
|
||
|
|
;; show doc for both fun and var, if available.
|
||
|
|
;; `help-mode' - If `one-window-p', then delete Help frame.
|
||
|
|
;; `help-xref-on-pp' - Library names are buttonized.
|
||
|
|
;;
|
||
|
|
;;
|
||
|
|
;; Put this in your initialization file (`~/.emacs'):
|
||
|
|
;;
|
||
|
|
;; (require 'help-mode+)
|
||
|
|
;;
|
||
|
|
;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
|
||
|
|
;;
|
||
|
|
;;; Change Log:
|
||
|
|
;;
|
||
|
|
;; 2018/01/1 dadams
|
||
|
|
;; help-make-xrefs:
|
||
|
|
;; Bug #12686: Promote type tests after cond tests to be inside them with the match tests.
|
||
|
|
;; 2014/01/17 dadams
|
||
|
|
;; Do not redefine help-mode for Emacs 24+.
|
||
|
|
;; 2012/10/25 dadams
|
||
|
|
;; Added redefinition of help-make-xrefs.
|
||
|
|
;; 2011/01/04 dadams
|
||
|
|
;; Removed autoload cookie from non-interactive function.
|
||
|
|
;; 2007/12/14 dadams
|
||
|
|
;; Added redefinition of help-mode.
|
||
|
|
;; Removed pop-to-help-buffer and help-origin-buffer to (new) help+.el.
|
||
|
|
;; 2006/07/11 dadams
|
||
|
|
;; Added: help-origin-buffer, pop-to-help-toggle. Bound latter to C-h C-o.
|
||
|
|
;;
|
||
|
|
;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
|
||
|
|
;;
|
||
|
|
;; This program is free software; you can redistribute it and/or modify
|
||
|
|
;; it under the terms of the GNU General Public License as published by
|
||
|
|
;; the Free Software Foundation; either version 2, or (at your option)
|
||
|
|
;; any later version.
|
||
|
|
|
||
|
|
;; This program is distributed in the hope that it will be useful,
|
||
|
|
;; but WITHOUT ANY WARRANTY; without even the implied warranty of
|
||
|
|
;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
|
||
|
|
;; GNU General Public License for more details.
|
||
|
|
|
||
|
|
;; You should have received a copy of the GNU General Public License
|
||
|
|
;; along with this program; see the file COPYING. If not, write to
|
||
|
|
;; the Free Software Foundation, Inc., 51 Franklin Street, Fifth
|
||
|
|
;; Floor, Boston, MA 02110-1301, USA.
|
||
|
|
;;
|
||
|
|
;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
|
||
|
|
;;
|
||
|
|
;;; Code:
|
||
|
|
|
||
|
|
(require 'help-mode)
|
||
|
|
|
||
|
|
;; Quiet the byte-compiler.
|
||
|
|
(defvar help-forward-label)
|
||
|
|
(defvar help-xref-override-view-map)
|
||
|
|
|
||
|
|
;;;;;;;;;;;;;;;;;;;;;;;;
|
||
|
|
|
||
|
|
|
||
|
|
;; REPLACES ORIGINAL IN `help-mode.el'.
|
||
|
|
;;
|
||
|
|
;; Deletes frame if `one-window-p'.
|
||
|
|
;;
|
||
|
|
;;;###autoload
|
||
|
|
(when (< emacs-major-version 24) ; Emacs 24+ does not use `view-mode', so no need.
|
||
|
|
(defun help-mode ()
|
||
|
|
"Major mode for viewing help text and navigating references in it.
|
||
|
|
Entry to this mode runs the normal hook `help-mode-hook'.
|
||
|
|
Commands:
|
||
|
|
\\{help-mode-map}"
|
||
|
|
(interactive)
|
||
|
|
(kill-all-local-variables)
|
||
|
|
(use-local-map help-mode-map)
|
||
|
|
(setq mode-name "Help"
|
||
|
|
major-mode 'help-mode)
|
||
|
|
(view-mode)
|
||
|
|
(make-local-variable 'view-no-disable-on-exit)
|
||
|
|
(setq view-no-disable-on-exit t
|
||
|
|
view-exit-action (lambda (buffer)
|
||
|
|
(or (window-minibuffer-p (selected-window))
|
||
|
|
(when (eq (window-buffer) (get-buffer "*Help*"))
|
||
|
|
(if (one-window-p t)
|
||
|
|
(delete-frame)
|
||
|
|
(delete-window))))))
|
||
|
|
(run-mode-hooks 'help-mode-hook)))
|
||
|
|
|
||
|
|
|
||
|
|
;; REPLACES ORIGINAL IN `help-mode.el'.
|
||
|
|
;;
|
||
|
|
;; Show all doc possible for a symbol that is any 2 or 3 of fn, var, and face.
|
||
|
|
;; See Emacs bug #12686.
|
||
|
|
;;
|
||
|
|
;; Also a partial fix for Emacs bug #24842.
|
||
|
|
;;
|
||
|
|
;;;###autoload
|
||
|
|
(defun help-make-xrefs (&optional buffer)
|
||
|
|
"Parse and hyperlink documentation cross-references in the given BUFFER.
|
||
|
|
|
||
|
|
Find cross-reference information in a buffer and activate such cross
|
||
|
|
references for selection with `help-follow'. Cross-references have
|
||
|
|
the canonical form `...' and the type of reference may be
|
||
|
|
disambiguated by the preceding word(s) used in
|
||
|
|
`help-xref-symbol-regexp'. Faces only get cross-referenced if
|
||
|
|
preceded or followed by the word `face'. Variables without
|
||
|
|
variable documentation do not get cross-referenced, unless
|
||
|
|
preceded by the word `variable' or `option'.
|
||
|
|
|
||
|
|
If the variable `help-xref-mule-regexp' is non-nil, find also
|
||
|
|
cross-reference information related to multilingual environment
|
||
|
|
\(e.g., coding-systems). This variable is also used to disambiguate
|
||
|
|
the type of reference as the same way as `help-xref-symbol-regexp'.
|
||
|
|
|
||
|
|
A special reference `back' is made to return back through a stack of
|
||
|
|
help buffers. Variable `help-back-label' specifies the text for
|
||
|
|
that."
|
||
|
|
(interactive "b")
|
||
|
|
(with-current-buffer (or buffer (current-buffer))
|
||
|
|
(save-excursion
|
||
|
|
(goto-char (point-min))
|
||
|
|
;; Skip the header-type info, though it might be useful to parse
|
||
|
|
;; it at some stage (e.g. "function in `library'").
|
||
|
|
(forward-paragraph)
|
||
|
|
(let ((old-modified (buffer-modified-p)))
|
||
|
|
(let ((stab (syntax-table))
|
||
|
|
(case-fold-search t)
|
||
|
|
(inhibit-read-only t))
|
||
|
|
(set-syntax-table emacs-lisp-mode-syntax-table)
|
||
|
|
;; The following should probably be abstracted out.
|
||
|
|
(unwind-protect
|
||
|
|
(progn
|
||
|
|
;; Info references
|
||
|
|
(save-excursion
|
||
|
|
(while (re-search-forward help-xref-info-regexp nil t)
|
||
|
|
(let ((data (match-string 2)))
|
||
|
|
(save-match-data
|
||
|
|
(unless (string-match "^([^)]+)" data)
|
||
|
|
(setq data (concat "(emacs)" data)))
|
||
|
|
(setq data ;; possible newlines if para filled
|
||
|
|
(replace-regexp-in-string "[ \t\n]+" " " data t t)))
|
||
|
|
(help-xref-button 2 'help-info data))))
|
||
|
|
;; URLs
|
||
|
|
(save-excursion
|
||
|
|
(while (re-search-forward help-xref-url-regexp nil t)
|
||
|
|
(let ((data (match-string 1)))
|
||
|
|
(help-xref-button 1 'help-url data))))
|
||
|
|
;; Mule related keywords. Do this before trying
|
||
|
|
;; `help-xref-symbol-regexp' because some of Mule
|
||
|
|
;; keywords have variable or function definitions.
|
||
|
|
|
||
|
|
;; $$$$$ Should I do it here too? (Have not done so yet.)
|
||
|
|
(when help-xref-mule-regexp
|
||
|
|
(save-excursion
|
||
|
|
(while (re-search-forward help-xref-mule-regexp nil t)
|
||
|
|
(let* ((data (match-string 7))
|
||
|
|
(sym (intern-soft data)))
|
||
|
|
(cond ((match-string 3) ; coding system
|
||
|
|
(and sym
|
||
|
|
(coding-system-p sym)
|
||
|
|
(help-xref-button 6 'help-coding-system sym)))
|
||
|
|
((match-string 4) ; input method
|
||
|
|
(and (assoc data input-method-alist)
|
||
|
|
(help-xref-button 7 'help-input-method data)))
|
||
|
|
((or (match-string 5) (match-string 6)) ; charset
|
||
|
|
(and sym
|
||
|
|
(charsetp sym)
|
||
|
|
(help-xref-button 7 'help-character-set sym)))
|
||
|
|
((assoc data input-method-alist)
|
||
|
|
(help-xref-button 7 'help-character-set data))
|
||
|
|
((and sym (coding-system-p sym))
|
||
|
|
(help-xref-button 7 'help-coding-system sym))
|
||
|
|
((and sym (charsetp sym))
|
||
|
|
(help-xref-button 7 'help-character-set sym)))))))
|
||
|
|
;; Quoted symbols
|
||
|
|
(save-excursion
|
||
|
|
(while (re-search-forward help-xref-symbol-regexp nil t)
|
||
|
|
(let* ((data (match-string 8))
|
||
|
|
(sym (intern-soft data)))
|
||
|
|
(when sym
|
||
|
|
(cond ((or (and (or (boundp sym) ; var & fn
|
||
|
|
(get sym 'variable-documentation))
|
||
|
|
(fboundp sym))
|
||
|
|
(and (fboundp sym) ; fn & face
|
||
|
|
(facep sym))
|
||
|
|
(and (or (boundp sym) ; var & face
|
||
|
|
(get sym 'variable-documentation))
|
||
|
|
(facep sym)))
|
||
|
|
;; Var, function, or face -- doc all, if possible.
|
||
|
|
(help-xref-button 8 'help-symbol sym))
|
||
|
|
((and (match-string 3) ; `variable' &c
|
||
|
|
(or (boundp sym) ; `variable' doesn't ensure
|
||
|
|
; it's actually bound
|
||
|
|
(get sym 'variable-documentation)))
|
||
|
|
(help-xref-button 8 'help-variable sym))
|
||
|
|
((and (match-string 4) ; `function' &c
|
||
|
|
(fboundp sym)) ; similarly
|
||
|
|
(help-xref-button 8 'help-function sym))
|
||
|
|
((and (match-string 5) ; `face'
|
||
|
|
(facep sym))
|
||
|
|
(help-xref-button 8 'help-face sym))
|
||
|
|
((match-string 6)) ; nothing for `symbol'
|
||
|
|
((match-string 7)
|
||
|
|
;; this used:
|
||
|
|
;; #'(lambda (arg)
|
||
|
|
;; (let ((location (find-function-noselect arg)))
|
||
|
|
;; (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))
|
||
|
|
(or (documentation-property sym 'variable-documentation)
|
||
|
|
(if (or (> emacs-major-version 24)
|
||
|
|
(and (= emacs-major-version 24)
|
||
|
|
(> emacs-minor-version 2)))
|
||
|
|
(documentation-property (indirect-variable sym)
|
||
|
|
'variable-documentation)
|
||
|
|
(condition-case nil
|
||
|
|
(documentation-property (indirect-variable sym)
|
||
|
|
'variable-documentation)
|
||
|
|
(cyclic-variable-indirection nil)))))
|
||
|
|
(help-xref-button 8 'help-variable sym))
|
||
|
|
((fboundp sym)
|
||
|
|
(help-xref-button 8 'help-function sym)))))))
|
||
|
|
;; An obvious case of a key substitution:
|
||
|
|
(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)
|
||
|
|
(let ((sym (intern-soft (match-string 1))))
|
||
|
|
(when (fboundp sym) (help-xref-button 1 'help-function sym)))))
|
||
|
|
;; Look for commands in whole keymap substitutions:
|
||
|
|
(save-excursion
|
||
|
|
;; Make sure to find the first keymap.
|
||
|
|
(goto-char (point-min))
|
||
|
|
;; Find a header and the column at which the command
|
||
|
|
;; name will be found.
|
||
|
|
|
||
|
|
;; If the keymap substitution isn't the last thing in
|
||
|
|
;; the doc string, and if there is anything on the same
|
||
|
|
;; line after it, this code won't recognize the end of it.
|
||
|
|
(while (re-search-forward "^key +binding\n\\(-+ +\\)-+\n\n"
|
||
|
|
nil t)
|
||
|
|
(let ((col (- (match-end 1) (match-beginning 1))))
|
||
|
|
(while (and (not (eobp))
|
||
|
|
;; Stop at a pair of blank lines.
|
||
|
|
(not (looking-at "\n\\s-*\n")))
|
||
|
|
;; Skip a single blank line.
|
||
|
|
(and (eolp) (forward-line))
|
||
|
|
(end-of-line)
|
||
|
|
(skip-chars-backward "^ \t\n")
|
||
|
|
(when (and (>= (current-column) col)
|
||
|
|
(looking-at "\\(\\sw\\|\\s_\\)+$"))
|
||
|
|
(let ((sym (intern-soft (match-string 0))))
|
||
|
|
(when (fboundp sym) (help-xref-button 0 'help-function sym))))
|
||
|
|
(forward-line))))))
|
||
|
|
(set-syntax-table stab))
|
||
|
|
;; Delete extraneous newlines at the end of the docstring
|
||
|
|
(goto-char (point-max))
|
||
|
|
(while (and (not (bobp)) (bolp)) (delete-char -1))
|
||
|
|
(insert "\n")
|
||
|
|
(when (or help-xref-stack (and (boundp 'help-xref-forward-stack)
|
||
|
|
help-xref-forward-stack))
|
||
|
|
(insert "\n"))
|
||
|
|
;; Make a back-reference in this buffer if appropriate.
|
||
|
|
(when help-xref-stack
|
||
|
|
(help-insert-xref-button help-back-label 'help-back
|
||
|
|
(current-buffer)))
|
||
|
|
;; Make a forward-reference in this buffer if appropriate.
|
||
|
|
(when (and (boundp 'help-xref-forward-stack) help-xref-forward-stack)
|
||
|
|
(when help-xref-stack
|
||
|
|
(insert "\t"))
|
||
|
|
(help-insert-xref-button help-forward-label 'help-forward
|
||
|
|
(current-buffer)))
|
||
|
|
(when (or help-xref-stack (and (boundp 'help-xref-forward-stack)
|
||
|
|
help-xref-forward-stack))
|
||
|
|
(insert "\n")))
|
||
|
|
(when (< emacs-major-version 24)
|
||
|
|
;; View mode steals RET from us.
|
||
|
|
(set (make-local-variable 'minor-mode-overriding-map-alist)
|
||
|
|
(list (cons 'view-mode help-xref-override-view-map))))
|
||
|
|
(when (or (> emacs-major-version 24)
|
||
|
|
(and (= emacs-major-version 24) (> emacs-minor-version 2)))
|
||
|
|
(set-buffer-modified-p old-modified))))))
|
||
|
|
|
||
|
|
|
||
|
|
;; REPLACES ORIGINAL IN `help-mode.el'.
|
||
|
|
|
||
|
|
;; Buttonizes names of libraries also.
|
||
|
|
;; To see the effect, try `C-h v features', and click on a library name.
|
||
|
|
;;
|
||
|
|
;; 2006-01-20: This no longer works, because the call to this function
|
||
|
|
;; from `describe-variable' was commented out in `help-fns.el'.
|
||
|
|
;;
|
||
|
|
(defun help-xref-on-pp (from to)
|
||
|
|
"Add xrefs for symbols in `pp's output between FROM and TO."
|
||
|
|
(if (> (- to from) 5000)
|
||
|
|
nil
|
||
|
|
(with-syntax-table emacs-lisp-mode-syntax-table
|
||
|
|
(save-excursion
|
||
|
|
(save-restriction
|
||
|
|
(narrow-to-region from to)
|
||
|
|
(goto-char (point-min))
|
||
|
|
(condition-case nil
|
||
|
|
(while (not (eobp))
|
||
|
|
(cond
|
||
|
|
((looking-at "\"") (forward-sexp 1))
|
||
|
|
((looking-at "#<") (search-forward ">" nil 'move))
|
||
|
|
((looking-at "\\(\\(\\sw\\|\\s_\\)+\\)")
|
||
|
|
(let* ((sym (intern-soft (match-string 1)))
|
||
|
|
(type (cond ((fboundp sym) 'help-function)
|
||
|
|
((or (memq sym '(t nil)) (keywordp sym))
|
||
|
|
nil)
|
||
|
|
((and sym (boundp sym))
|
||
|
|
'help-variable)
|
||
|
|
((and sym (locate-library (symbol-name sym)))
|
||
|
|
'help-library))))
|
||
|
|
(when type (help-xref-button 1 type sym)))
|
||
|
|
(goto-char (match-end 1)))
|
||
|
|
(t (forward-char 1))))
|
||
|
|
(error nil)))))))
|
||
|
|
|
||
|
|
(define-button-type 'help-library
|
||
|
|
:supertype 'help-xref
|
||
|
|
'help-function #'(lambda (x) (find-library (symbol-name x)))
|
||
|
|
'help-echo (purecopy "mouse-2, RET: find this library"))
|
||
|
|
|
||
|
|
;; $$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$
|
||
|
|
;; REPLACES ORIGINAL IN `help-mode.el'.
|
||
|
|
;; Provide a tooltip for whatever is under the mouse.
|
||
|
|
;; This can't be done here - the message needs to be done via an idle timer,
|
||
|
|
;; whenever mouse is over any name. Perhaps combine with eldoc.
|
||
|
|
;;
|
||
|
|
;; ;;;###autoload
|
||
|
|
;; (defun help-follow-mouse (click)
|
||
|
|
;; "Follow the cross-reference that you CLICK on."
|
||
|
|
;; (interactive "e")
|
||
|
|
;; (let* ((start (event-start click))
|
||
|
|
;; (window (car start))
|
||
|
|
;; (pos (car (cdr start))))
|
||
|
|
;; (with-current-buffer (window-buffer window)
|
||
|
|
;; (message "Display help on `%s'"
|
||
|
|
;; (save-excursion
|
||
|
|
;; (goto-char pos) (skip-syntax-backward "w_")
|
||
|
|
;; (buffer-substring (point)
|
||
|
|
;; (progn (skip-syntax-forward "w_")
|
||
|
|
;; (point)))))
|
||
|
|
;; (help-follow pos))))
|
||
|
|
|
||
|
|
;; After a certain idle time, use function `mouse-position', and pick
|
||
|
|
;; up the symbol under the pointer. Then display a message that
|
||
|
|
;; clicking mouse-2 will display help on the symbol.
|
||
|
|
|
||
|
|
|
||
|
|
;;;;;;;;;;;;;;;;;;;;;;;;;;;
|
||
|
|
|
||
|
|
(provide 'help-mode+)
|
||
|
|
|
||
|
|
;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
|
||
|
|
;;; help-mode+.el ends here
|