factor/misc/fuel/fuel-help.el

366 lines
12 KiB
EmacsLisp
Raw Normal View History

;;; fuel-help.el -- accessing Factor's help system
2009-01-03 10:37:28 -05:00
;; Copyright (C) 2008, 2009 Jose Antonio Ortega Ruiz
;; See http://factorcode.org/license.txt for BSD license.
;; Author: Jose Antonio Ortega Ruiz <jao@gnu.org>
;; Keywords: languages, fuel, factor
;; Start date: Wed Dec 03, 2008 21:41
;;; Comentary:
;; Modes and functions interfacing Factor's 'see' and 'help'
;; utilities, as well as an ElDoc-based autodoc mode.
;;; Code:
(require 'fuel-edit)
(require 'fuel-eval)
2009-01-03 10:37:28 -05:00
(require 'fuel-markup)
2008-12-20 10:51:05 -05:00
(require 'fuel-autodoc)
(require 'fuel-completion)
(require 'fuel-syntax)
(require 'fuel-font-lock)
(require 'fuel-popup)
(require 'fuel-base)
2009-01-03 10:37:28 -05:00
(require 'button)
;;; Customization:
(defgroup fuel-help nil
"Options controlling FUEL's help system."
:group 'fuel)
(defcustom fuel-help-always-ask t
"When enabled, always ask for confirmation in help prompts."
:type 'boolean
:group 'fuel-help)
(defcustom fuel-help-history-cache-size 50
"Maximum number of pages to keep in the help browser cache."
:type 'integer
:group 'fuel-help)
2009-01-03 22:04:08 -05:00
(defcustom fuel-help-bookmarks nil
"Bookmars. Maintain this list using the help browser."
:type 'list
:group 'fuel-help)
;;; Help browser history:
2009-01-03 10:37:28 -05:00
(defun fuel-help--make-history ()
(list nil ; current
(make-ring fuel-help-history-cache-size) ; previous
(make-ring fuel-help-history-cache-size))) ; next
2009-01-03 22:04:08 -05:00
(defsubst fuel-help--history-current ()
(car fuel-help--history))
(defun fuel-help--history-push (link)
(unless (equal link (car fuel-help--history))
(let ((next (fuel-help--history-next)))
(unless (equal link next)
(when next (fuel-help--history-previous))
(ring-insert (nth 1 fuel-help--history) (car fuel-help--history))
(setcar fuel-help--history link))))
link)
(defun fuel-help--history-next (&optional forget-current)
(when (not (ring-empty-p (nth 2 fuel-help--history)))
(when (and (car fuel-help--history) (not forget-current))
(ring-insert (nth 1 fuel-help--history) (car fuel-help--history)))
(setcar fuel-help--history (ring-remove (nth 2 fuel-help--history) 0))))
(defun fuel-help--history-previous (&optional forget-current)
(when (not (ring-empty-p (nth 1 fuel-help--history)))
(when (and (car fuel-help--history) (not forget-current))
(ring-insert (nth 2 fuel-help--history) (car fuel-help--history)))
(setcar fuel-help--history (ring-remove (nth 1 fuel-help--history) 0))))
(defvar fuel-help--history (fuel-help--make-history))
;;; Page cache:
(defun fuel-help--history-current-content ()
(fuel-help--cache-get (car fuel-help--history)))
2009-01-04 13:40:22 -05:00
(defvar fuel-help--cache (make-hash-table :weakness 'key :test 'equal))
(defsubst fuel-help--cache-get (name)
(gethash name fuel-help--cache))
(defsubst fuel-help--cache-insert (name str)
(puthash name str fuel-help--cache))
(defsubst fuel-help--cache-clear ()
(clrhash fuel-help--cache))
;;; Fuel help buffer and internals:
(fuel-popup--define fuel-help--buffer
"*fuel help*" 'fuel-help-mode)
(defvar fuel-help--prompt-history nil)
2009-01-03 22:04:08 -05:00
(make-local-variable
(defvar fuel-help--buffer-link nil))
2009-01-03 10:37:28 -05:00
(defun fuel-help--read-word (see)
(let* ((def (fuel-syntax-symbol-at-point))
(prompt (format "See%s help on%s: " (if see " short" "")
(if def (format " (%s)" def) "")))
(ask (or (not def) fuel-help-always-ask)))
(if ask
(fuel-completion--read-word prompt
2009-01-03 10:37:28 -05:00
def
'fuel-help--prompt-history
t)
def)))
(defun fuel-help--word-help (&optional see word)
(let ((def (or word (fuel-help--read-word see))))
(when def
(let ((cmd `(:fuel* (,def ,(if see 'fuel-word-see 'fuel-word-help))
"fuel" t)))
(message "Looking up '%s' ..." def)
2009-01-06 22:08:36 -05:00
(let* ((ret (fuel-eval--send/wait cmd))
(res (fuel-eval--retort-result ret)))
(if (not res)
(message "No help for '%s'" def)
(fuel-help--insert-contents (list def def 'word) res)))))))
2009-01-03 10:37:28 -05:00
(defun fuel-help--get-article (name label)
(message "Retrieving article ...")
(let* ((cmd `(:fuel* ((,name fuel-get-article)) "fuel" t))
2009-01-06 22:08:36 -05:00
(ret (fuel-eval--send/wait cmd))
(res (fuel-eval--retort-result ret)))
(if (not res)
(message "Article '%s' not found" label)
(fuel-help--insert-contents (list name label 'article) res)
(message ""))))
2009-01-03 10:37:28 -05:00
(defun fuel-help--get-vocab (name)
(message "Retrieving help vocabulary for vocabulary '%s' ..." name)
(let* ((cmd `(:fuel* ((,name fuel-vocab-help)) "fuel" (,name)))
2009-01-06 22:08:36 -05:00
(ret (fuel-eval--send/wait cmd))
(res (fuel-eval--retort-result ret)))
(if (not res)
(message "No help available for vocabulary '%s'" name)
(fuel-help--insert-contents (list name name 'vocab) res)
(message ""))))
(defun fuel-help--get-vocab/author (author)
(message "Retrieving vocabularies by %s ..." author)
(let* ((cmd `(:fuel* ((,author fuel-get-vocabs/author)) "fuel" t))
(ret (fuel-eval--send/wait cmd))
(res (fuel-eval--retort-result ret)))
(if (not res)
(message "No vocabularies by %s" author)
(fuel-help--insert-contents (list author author 'author) res)
(message ""))))
(defun fuel-help--get-vocab/tag (tag)
(message "Retrieving vocabularies tagged '%s' ..." tag)
(let* ((cmd `(:fuel* ((,tag fuel-get-vocabs/tag)) "fuel" t))
(ret (fuel-eval--send/wait cmd))
(res (fuel-eval--retort-result ret)))
(if (not res)
(message "No vocabularies tagged '%s'" tag)
(fuel-help--insert-contents (list tag tag 'tag) res)
(message ""))))
(defun fuel-help--follow-link (link label type &optional no-cache)
(let* ((llink (list link label type))
(cached (and (not no-cache) (fuel-help--cache-get llink))))
(if (not cached)
(let ((fuel-help-always-ask nil))
(cond ((eq type 'word) (fuel-help--word-help nil link))
((eq type 'article) (fuel-help--get-article link label))
((eq type 'vocab) (fuel-help--get-vocab link))
((eq type 'author) (fuel-help--get-vocab/author label))
((eq type 'tag) (fuel-help--get-vocab/tag label))
((eq type 'bookmarks) (fuel-help-display-bookmarks))
(t (error "Links of type %s not yet implemented" type))))
(fuel-help--insert-contents llink cached))))
(defun fuel-help--insert-contents (key content)
(let ((hb (fuel-help--buffer))
(inhibit-read-only t)
(font-lock-verbose nil))
(set-buffer hb)
(erase-buffer)
(if (stringp content)
(insert content)
(fuel-markup--print content)
(fuel-markup--insert-newline)
(delete-blank-lines)
(fuel-help--cache-insert key (buffer-string)))
(fuel-help--history-push key)
(setq fuel-help--buffer-link key)
(set-buffer-modified-p nil)
(fuel-popup--display)
(goto-char (point-min))
2009-01-03 10:37:28 -05:00
(message "")))
2009-01-03 22:04:08 -05:00
;;; Bookmarks:
(defun fuel-help-bookmark-page ()
"Add current help page to bookmarks."
(interactive)
(let ((link fuel-help--buffer-link))
(unless link (error "No link associated to this page"))
(add-to-list 'fuel-help-bookmarks link)
(customize-save-variable 'fuel-help-bookmarks fuel-help-bookmarks)
(message "Bookmark '%s' saved" (cadr link))))
(defun fuel-help-delete-bookmark ()
"Delete link at point from bookmarks."
(interactive)
(let ((link (fuel-markup--link-at-point)))
(unless link (error "No link at point"))
(unless (member link fuel-help-bookmarks)
(error "'%s' is not bookmarked" (cadr link)))
(customize-save-variable 'fuel-help-bookmarks
(remove link fuel-help-bookmarks))
(message "Bookmark '%s' delete" (cadr link))
(fuel-help-display-bookmarks)))
(defun fuel-help-display-bookmarks ()
"Display bookmarked pages."
(interactive)
(let ((links (mapcar (lambda (l) (cons '$subsection l)) fuel-help-bookmarks)))
(unless links (error "No links to display"))
(fuel-help--insert-contents '("bookmarks" "Bookmars" bookmarks)
`(article "Bookmarks" ,links))))
2009-01-03 22:04:08 -05:00
;;; Interactive help commands:
2009-01-03 10:37:28 -05:00
(defun fuel-help-short ()
"See help summary of symbol at point."
(interactive)
(fuel-help--word-help t))
(defun fuel-help ()
"Show extended help about the symbol at point, using a help
buffer."
(interactive)
2009-01-03 10:37:28 -05:00
(fuel-help--word-help))
(defun fuel-help-vocab (vocab)
"Ask for a vocabulary name and show its help page."
(interactive (list (fuel-edit--read-vocabulary-name nil)))
(fuel-help--get-vocab vocab))
(defun fuel-help-next (&optional forget-current)
"Go to next page in help browser.
With prefix, the current page is deleted from history."
(interactive "P")
(let ((item (fuel-help--history-next forget-current)))
(unless item (error "No next page"))
(apply 'fuel-help--follow-link item)))
(defun fuel-help-previous (&optional forget-current)
"Go to previous page in help browser.
With prefix, the current page is deleted from history."
(interactive "P")
(let ((item (fuel-help--history-previous forget-current)))
(unless item (error "No previous page"))
(apply 'fuel-help--follow-link item)))
(defun fuel-help-kill-page ()
"Kill current page if a previous or next one exists."
(interactive)
(condition-case nil
(fuel-help-previous t)
(error (fuel-help-next t))))
(defun fuel-help-refresh ()
"Refresh the contents of current page."
(interactive)
(when fuel-help--buffer-link
(apply 'fuel-help--follow-link (append fuel-help--buffer-link '(t)))))
2009-01-03 10:37:28 -05:00
(defun fuel-help-clean-history ()
"Clean up the help browser cache of visited pages."
(interactive)
(when (y-or-n-p "Clean browsing history? ")
(fuel-help--cache-clear)
(setq fuel-help--history (fuel-help--make-history))
(fuel-help-refresh))
2009-01-03 10:37:28 -05:00
(message ""))
(defun fuel-help-edit ()
"Edit the current article or word help."
(interactive)
(let ((link (car fuel-help--buffer-link))
(type (nth 2 fuel-help--buffer-link)))
(cond ((eq type 'word) (fuel-edit-word-doc-at-point nil link))
((member type '(article vocab)) (fuel-edit--edit-article link))
(t (error "No document associated with this page")))))
;;;; Help mode map:
(defvar fuel-help-mode-map
(let ((map (make-sparse-keymap)))
(suppress-keymap map)
2009-01-03 10:37:28 -05:00
(set-keymap-parent map button-buffer-map)
2009-01-03 20:36:58 -05:00
(define-key map "a" 'fuel-apropos)
2009-01-03 22:04:08 -05:00
(define-key map "ba" 'fuel-help-bookmark-page)
(define-key map "bb" 'fuel-help-display-bookmarks)
(define-key map "bd" 'fuel-help-delete-bookmark)
2009-01-03 10:37:28 -05:00
(define-key map "c" 'fuel-help-clean-history)
(define-key map "e" 'fuel-help-edit)
2009-01-03 10:37:28 -05:00
(define-key map "h" 'fuel-help)
(define-key map "k" 'fuel-help-kill-page)
(define-key map "n" 'fuel-help-next)
2009-01-05 09:30:07 -05:00
(define-key map "l" 'fuel-help-previous)
(define-key map "p" 'fuel-help-previous)
(define-key map "r" 'fuel-help-refresh)
(define-key map "v" 'fuel-help-vocab)
(define-key map (kbd "SPC") 'scroll-up)
(define-key map (kbd "S-SPC") 'scroll-down)
2008-12-21 19:34:47 -05:00
(define-key map "\M-." 'fuel-edit-word-at-point)
(define-key map "\C-cz" 'run-factor)
(define-key map "\C-c\C-z" 'run-factor)
map))
;;; IN: support
(defun fuel-help--find-in ()
(save-excursion
(or (fuel-syntax--find-in)
(and (goto-char (point-min))
(re-search-forward "Vocabulary: \\(.+\\)$" nil t)
(match-string-no-properties 1)))))
;;; Help mode definition:
(defun fuel-help-mode ()
"Major mode for browsing Factor documentation.
\\{fuel-help-mode-map}"
(interactive)
(kill-all-local-variables)
2008-12-12 21:40:36 -05:00
(buffer-disable-undo)
(use-local-map fuel-help-mode-map)
2009-01-03 10:37:28 -05:00
(set-syntax-table fuel-syntax--syntax-table)
(setq mode-name "FUEL Help")
(setq major-mode 'fuel-help-mode)
(setq fuel-syntax--current-vocab-function 'fuel-help--find-in)
2009-01-03 10:37:28 -05:00
(setq fuel-markup--follow-link-function 'fuel-help--follow-link)
2008-12-12 21:40:36 -05:00
(setq buffer-read-only t))
(provide 'fuel-help)
;;; fuel-help.el ends here