2008-12-05 22:34:25 -05:00
|
|
|
|
;;; fuel-help.el -- accessing Factor's help system
|
|
|
|
|
|
2009-01-03 10:37:28 -05:00
|
|
|
|
;; Copyright (C) 2008, 2009 Jose Antonio Ortega Ruiz
|
2008-12-05 22:34:25 -05:00
|
|
|
|
;; 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-eval)
|
2009-01-03 10:37:28 -05:00
|
|
|
|
(require 'fuel-markup)
|
2008-12-20 10:51:05 -05:00
|
|
|
|
(require 'fuel-autodoc)
|
2008-12-16 19:12:15 -05:00
|
|
|
|
(require 'fuel-completion)
|
|
|
|
|
(require 'fuel-font-lock)
|
2008-12-21 10:04:39 -05:00
|
|
|
|
(require 'fuel-popup)
|
2008-12-16 19:12:15 -05:00
|
|
|
|
(require 'fuel-base)
|
2008-12-05 22:34:25 -05:00
|
|
|
|
|
2009-01-03 10:37:28 -05:00
|
|
|
|
(require 'button)
|
|
|
|
|
|
2008-12-05 22:34:25 -05:00
|
|
|
|
|
|
|
|
|
;;; Customization:
|
|
|
|
|
|
|
|
|
|
(defgroup fuel-help nil
|
2008-12-21 19:51:41 -05:00
|
|
|
|
"Options controlling FUEL's help system."
|
2008-12-05 22:34:25 -05:00
|
|
|
|
:group 'fuel)
|
|
|
|
|
|
|
|
|
|
(defcustom fuel-help-always-ask t
|
|
|
|
|
"When enabled, always ask for confirmation in help prompts."
|
|
|
|
|
:type 'boolean
|
|
|
|
|
:group 'fuel-help)
|
|
|
|
|
|
2008-12-12 19:54:18 -05:00
|
|
|
|
(defcustom fuel-help-history-cache-size 50
|
|
|
|
|
"Maximum number of pages to keep in the help browser cache."
|
|
|
|
|
:type 'integer
|
|
|
|
|
:group 'fuel-help)
|
|
|
|
|
|
2008-12-05 22:34:25 -05:00
|
|
|
|
|
2008-12-12 19:54:18 -05:00
|
|
|
|
;;; Help browser history:
|
2008-12-05 22:34:25 -05:00
|
|
|
|
|
2009-01-03 10:37:28 -05:00
|
|
|
|
(defun fuel-help--make-history ()
|
2008-12-16 18:08:05 -05:00
|
|
|
|
(list nil ; current
|
|
|
|
|
(make-ring fuel-help-history-cache-size) ; previous
|
|
|
|
|
(make-ring fuel-help-history-cache-size))) ; next
|
2008-12-05 22:34:25 -05:00
|
|
|
|
|
2009-01-03 10:37:28 -05:00
|
|
|
|
(defvar fuel-help--history (fuel-help--make-history))
|
|
|
|
|
|
2008-12-12 19:54:18 -05:00
|
|
|
|
(defun fuel-help--history-push (term)
|
2008-12-16 18:08:05 -05:00
|
|
|
|
(when (and (car fuel-help--history)
|
|
|
|
|
(not (string= (caar fuel-help--history) (car term))))
|
2008-12-12 19:54:18 -05:00
|
|
|
|
(ring-insert (nth 1 fuel-help--history) (car fuel-help--history)))
|
|
|
|
|
(setcar fuel-help--history term))
|
2008-12-05 22:34:25 -05:00
|
|
|
|
|
2008-12-12 19:54:18 -05:00
|
|
|
|
(defun fuel-help--history-next ()
|
|
|
|
|
(when (not (ring-empty-p (nth 2 fuel-help--history)))
|
|
|
|
|
(when (car fuel-help--history)
|
|
|
|
|
(ring-insert (nth 1 fuel-help--history) (car fuel-help--history)))
|
|
|
|
|
(setcar fuel-help--history (ring-remove (nth 2 fuel-help--history) 0))))
|
2008-12-05 22:34:25 -05:00
|
|
|
|
|
2008-12-12 19:54:18 -05:00
|
|
|
|
(defun fuel-help--history-previous ()
|
|
|
|
|
(when (not (ring-empty-p (nth 1 fuel-help--history)))
|
|
|
|
|
(when (car fuel-help--history)
|
|
|
|
|
(ring-insert (nth 2 fuel-help--history) (car fuel-help--history)))
|
|
|
|
|
(setcar fuel-help--history (ring-remove (nth 1 fuel-help--history) 0))))
|
2008-12-05 22:34:25 -05:00
|
|
|
|
|
2008-12-12 19:54:18 -05:00
|
|
|
|
|
|
|
|
|
;;; Fuel help buffer and internals:
|
2008-12-05 22:34:25 -05:00
|
|
|
|
|
2008-12-21 10:04:39 -05:00
|
|
|
|
(fuel-popup--define fuel-help--buffer
|
|
|
|
|
"*fuel help*" 'fuel-help-mode)
|
|
|
|
|
|
2008-12-05 22:34:25 -05:00
|
|
|
|
|
2008-12-12 19:54:18 -05:00
|
|
|
|
(defvar fuel-help--prompt-history nil)
|
2008-12-05 22:34:25 -05:00
|
|
|
|
|
2009-01-03 10:37:28 -05:00
|
|
|
|
(defun fuel-help--read-word (see)
|
|
|
|
|
(let* ((def (fuel-syntax-symbol-at-point))
|
2008-12-05 22:34:25 -05:00
|
|
|
|
(prompt (format "See%s help on%s: " (if see " short" "")
|
|
|
|
|
(if def (format " (%s)" def) "")))
|
|
|
|
|
(ask (or (not (memq major-mode '(factor-mode fuel-help-mode)))
|
|
|
|
|
(not def)
|
2009-01-03 10:37:28 -05:00
|
|
|
|
fuel-help-always-ask)))
|
|
|
|
|
(if ask (fuel-completion--read-word prompt
|
|
|
|
|
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)
|
|
|
|
|
(let* ((ret (fuel-eval--send/wait cmd 2000))
|
|
|
|
|
(res (fuel-eval--retort-result ret)))
|
|
|
|
|
(if (not res)
|
|
|
|
|
(message "No help for '%s'" def)
|
|
|
|
|
(fuel-help--insert-contents def res)))))))
|
|
|
|
|
|
|
|
|
|
(defun fuel-help--get-article (name label)
|
2009-01-03 15:51:21 -05:00
|
|
|
|
(message "Retrieving article ...")
|
2009-01-03 10:37:28 -05:00
|
|
|
|
(let* ((cmd `(:fuel* ((,name fuel-get-article)) "fuel" t))
|
|
|
|
|
(ret (fuel-eval--send/wait cmd 2000))
|
|
|
|
|
(res (fuel-eval--retort-result ret)))
|
|
|
|
|
(fuel-help--insert-contents label res)
|
|
|
|
|
(message "")))
|
|
|
|
|
|
|
|
|
|
(defun fuel-help--follow-link (label link type)
|
|
|
|
|
(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))
|
|
|
|
|
(t (message (format "Links of type %s not yet implemented" type))))))
|
|
|
|
|
|
|
|
|
|
(defun fuel-help--insert-contents (def art &optional nopush)
|
2008-12-21 10:04:39 -05:00
|
|
|
|
(let ((hb (fuel-help--buffer))
|
2008-12-12 19:54:18 -05:00
|
|
|
|
(inhibit-read-only t)
|
|
|
|
|
(font-lock-verbose nil))
|
|
|
|
|
(set-buffer hb)
|
|
|
|
|
(erase-buffer)
|
2009-01-03 10:37:28 -05:00
|
|
|
|
(if (stringp art)
|
|
|
|
|
(insert art)
|
|
|
|
|
(fuel-markup--print art)
|
|
|
|
|
(fuel-markup--insert-newline))
|
2008-12-16 18:08:05 -05:00
|
|
|
|
(unless nopush
|
2009-01-03 10:37:28 -05:00
|
|
|
|
(fuel-help--history-push (cons def (buffer-string))))
|
2008-12-12 19:54:18 -05:00
|
|
|
|
(set-buffer-modified-p nil)
|
2008-12-21 10:04:39 -05:00
|
|
|
|
(fuel-popup--display)
|
2008-12-12 19:54:18 -05:00
|
|
|
|
(goto-char (point-min))
|
2009-01-03 10:37:28 -05:00
|
|
|
|
(message "")))
|
2008-12-18 11:07:36 -05:00
|
|
|
|
|
2008-12-05 22:34:25 -05:00
|
|
|
|
|
2008-12-12 19:54:18 -05:00
|
|
|
|
;;; Interactive help commands:
|
2008-12-05 22:34:25 -05:00
|
|
|
|
|
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))
|
2008-12-05 22:34:25 -05:00
|
|
|
|
|
|
|
|
|
(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))
|
2008-12-05 22:34:25 -05:00
|
|
|
|
|
2008-12-12 19:54:18 -05:00
|
|
|
|
(defun fuel-help-next ()
|
|
|
|
|
"Go to next page in help browser."
|
|
|
|
|
(interactive)
|
|
|
|
|
(let ((item (fuel-help--history-next))
|
|
|
|
|
(fuel-help-always-ask nil))
|
|
|
|
|
(unless item
|
|
|
|
|
(error "No next page"))
|
|
|
|
|
(fuel-help--insert-contents (car item) (cdr item) t)))
|
|
|
|
|
|
|
|
|
|
(defun fuel-help-previous ()
|
|
|
|
|
"Go to next page in help browser."
|
|
|
|
|
(interactive)
|
|
|
|
|
(let ((item (fuel-help--history-previous))
|
|
|
|
|
(fuel-help-always-ask nil))
|
|
|
|
|
(unless item
|
|
|
|
|
(error "No previous page"))
|
|
|
|
|
(fuel-help--insert-contents (car item) (cdr item) 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? ")
|
|
|
|
|
(setq fuel-help--history (fuel-help--make-history)))
|
|
|
|
|
(message ""))
|
2008-12-18 11:07:36 -05:00
|
|
|
|
|
2008-12-12 19:54:18 -05:00
|
|
|
|
|
2008-12-18 11:07:36 -05:00
|
|
|
|
;;;; Help mode map:
|
2008-12-12 19:54:18 -05:00
|
|
|
|
|
|
|
|
|
(defvar fuel-help-mode-map
|
|
|
|
|
(let ((map (make-sparse-keymap)))
|
2008-12-20 19:43:28 -05:00
|
|
|
|
(suppress-keymap map)
|
2009-01-03 10:37:28 -05:00
|
|
|
|
(set-keymap-parent map button-buffer-map)
|
2008-12-12 19:54:18 -05:00
|
|
|
|
(define-key map "b" 'fuel-help-previous)
|
2009-01-03 10:37:28 -05:00
|
|
|
|
(define-key map "c" 'fuel-help-clean-history)
|
2008-12-12 19:54:18 -05:00
|
|
|
|
(define-key map "f" 'fuel-help-next)
|
2009-01-03 10:37:28 -05:00
|
|
|
|
(define-key map "h" 'fuel-help)
|
2008-12-15 17:44:13 -05:00
|
|
|
|
(define-key map "l" 'fuel-help-previous)
|
2008-12-17 17:50:48 -05:00
|
|
|
|
(define-key map "p" 'fuel-help-previous)
|
2008-12-15 17:44:13 -05:00
|
|
|
|
(define-key map "n" 'fuel-help-next)
|
2008-12-12 19:54:18 -05:00
|
|
|
|
(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)
|
2008-12-18 09:38:40 -05:00
|
|
|
|
(define-key map "\C-cz" 'run-factor)
|
|
|
|
|
(define-key map "\C-c\C-z" 'run-factor)
|
2008-12-12 19:54:18 -05:00
|
|
|
|
map))
|
|
|
|
|
|
2008-12-18 11:07:36 -05:00
|
|
|
|
|
|
|
|
|
;;; Help mode definition:
|
2008-12-12 19:54:18 -05:00
|
|
|
|
|
|
|
|
|
(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)
|
2008-12-12 19:54:18 -05:00
|
|
|
|
(use-local-map fuel-help-mode-map)
|
2009-01-03 10:37:28 -05:00
|
|
|
|
(set-syntax-table fuel-syntax--syntax-table)
|
2008-12-20 19:43:28 -05:00
|
|
|
|
(setq mode-name "FUEL Help")
|
2008-12-12 19:54:18 -05:00
|
|
|
|
(setq major-mode 'fuel-help-mode)
|
|
|
|
|
|
2009-01-03 10:37:28 -05:00
|
|
|
|
(setq fuel-markup--follow-link-function 'fuel-help--follow-link)
|
2008-12-12 19:54:18 -05:00
|
|
|
|
|
|
|
|
|
(setq fuel-autodoc-mode-string "")
|
|
|
|
|
(fuel-autodoc-mode)
|
|
|
|
|
|
2008-12-12 21:40:36 -05:00
|
|
|
|
(setq buffer-read-only t))
|
2008-12-12 19:54:18 -05:00
|
|
|
|
|
2008-12-05 22:34:25 -05:00
|
|
|
|
|
|
|
|
|
(provide 'fuel-help)
|
|
|
|
|
;;; fuel-help.el ends here
|