lisp/emacs-lisp/helper.el

   1 ;;; helper.el --- utility help package supporting help in electric modes
   2
   3 ;; Copyright (C) 1985, 2001, 2002, 2003, 2004, 2005,
   4 ;;   2006, 2007, 2008 Free Software Foundation, Inc.
   5
   6 ;; Author: K. Shane Hartman
   7 ;; Maintainer: FSF
   8 ;; Keywords: help
   9
  10 ;; This file is part of GNU Emacs.
  11
  12 ;; GNU Emacs is free software; you can redistribute it and/or modify
  13 ;; it under the terms of the GNU General Public License as published by
  14 ;; the Free Software Foundation; either version 3, or (at your option)
  15 ;; any later version.
  16
  17 ;; GNU Emacs is distributed in the hope that it will be useful,
  18 ;; but WITHOUT ANY WARRANTY; without even the implied warranty of
  19 ;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  20 ;; GNU General Public License for more details.
  21
  22 ;; You should have received a copy of the GNU General Public License
  23 ;; along with GNU Emacs; see the file COPYING.  If not, write to the
  24 ;; Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
  25 ;; Boston, MA 02110-1301, USA.
  26
  27 ;;; Commentary:
  28
  29 ;;; Code:
  30
  31 ;; hey, here's a helping hand.
  32
  33 ;; Bind this to a string for <blank> in "... Other keys <blank>".
  34 ;; Helper-help uses this to construct help string when scrolling.
  35 ;; Defaults to "return"
  36 (defvar Helper-return-blurb nil)
  37
  38 ;; Keymap implementation doesn't work too well for non-standard loops.
  39 ;; But define it anyway for those who can use it.  Non-standard loops
  40 ;; will probably have to use Helper-help.  You can't autoload the
  41 ;; keymap either.
  42
  43
  44 (defvar Helper-help-map nil)
  45 (if Helper-help-map
  46     nil
  47   (setq Helper-help-map (make-keymap))
  48   ;(fillarray Helper-help-map 'undefined)
  49   (define-key Helper-help-map "m" 'Helper-describe-mode)
  50   (define-key Helper-help-map "b" 'Helper-describe-bindings)
  51   (define-key Helper-help-map "c" 'Helper-describe-key-briefly)
  52   (define-key Helper-help-map "k" 'Helper-describe-key)
  53   ;(define-key Helper-help-map "f" 'Helper-describe-function)
  54   ;(define-key Helper-help-map "v" 'Helper-describe-variable)
  55   (define-key Helper-help-map "?" 'Helper-help-options)
  56   (define-key Helper-help-map (char-to-string help-char) 'Helper-help-options)
  57   (fset 'Helper-help-map Helper-help-map))
  58
  59 (defun Helper-help-scroller ()
  60   (let ((blurb (or (and (boundp 'Helper-return-blurb)
  61                         Helper-return-blurb)
  62                    "return")))
  63     (save-window-excursion
  64       (goto-char (window-start (selected-window)))
  65       (if (get-buffer-window "*Help*")
  66           (pop-to-buffer "*Help*")
  67         (switch-to-buffer "*Help*"))
  68       (goto-char (point-min))
  69       (let ((continue t) state)
  70         (while continue
  71           (setq state (+ (* 2 (if (pos-visible-in-window-p (point-max)) 1 0))
  72                          (if (pos-visible-in-window-p (point-min)) 1 0)))
  73           (message
  74             (nth state
  75                  '("Space forward, Delete back. Other keys %s"
  76                    "Space scrolls forward. Other keys %s"
  77                    "Delete scrolls back. Other keys %s"
  78                    "Type anything to %s"))
  79             blurb)
  80           (setq continue (read-event))
  81           (cond ((and (memq continue '(?\s ?\C-v)) (< state 2))
  82                  (scroll-up))
  83                 ((= continue ?\C-l)
  84                  (recenter))
  85                 ((and (= continue ?\177) (zerop (% state 2)))
  86                  (scroll-down))
  87                 (t (setq continue nil))))))))
  88
  89 (defun Helper-help-options ()
  90   "Describe help options."
  91   (interactive)
  92   (message "c (key briefly), m (mode), k (key), b (bindings)")
  93   ;(message "c (key briefly), m (mode), k (key), v (variable), f (function)")
  94   (sit-for 4))
  95
  96 (defun Helper-describe-key-briefly (key)
  97   "Briefly describe binding of KEY."
  98   (interactive "kDescribe key briefly: ")
  99   (describe-key-briefly key)
 100   (sit-for 4))
 101
 102 (defun Helper-describe-key (key)
 103   "Describe binding of KEY."
 104   (interactive "kDescribe key: ")
 105   (save-window-excursion (describe-key key))
 106   (Helper-help-scroller))
 107
 108 (defun Helper-describe-function ()
 109   "Describe a function.  Name read interactively."
 110   (interactive)
 111   (save-window-excursion (call-interactively 'describe-function))
 112   (Helper-help-scroller))
 113
 114 (defun Helper-describe-variable ()
 115   "Describe a variable.  Name read interactively."
 116   (interactive)
 117   (save-window-excursion (call-interactively 'describe-variable))
 118   (Helper-help-scroller))
 119
 120 (defun Helper-describe-mode ()
 121   "Describe the current mode."
 122   (interactive)
 123   (let ((name (format-mode-line mode-name))
 124         (documentation (documentation major-mode)))
 125     (with-current-buffer (get-buffer-create "*Help*")
 126       (setq buffer-read-only nil)
 127       (erase-buffer)
 128       (insert name " Mode\n" documentation)
 129       (help-mode)))
 130   (Helper-help-scroller))
 131
 132 ;;;###autoload
 133 (defun Helper-describe-bindings ()
 134   "Describe local key bindings of current mode."
 135   (interactive)
 136   (message "Making binding list...")
 137   (save-window-excursion (describe-bindings))
 138   (Helper-help-scroller))
 139
 140 ;;;###autoload
 141 (defun Helper-help ()
 142   "Provide help for current mode."
 143   (interactive)
 144   (let ((continue t) c)
 145     (while continue
 146       (message "Help (Type ? for further options)")
 147       (setq c (read-key-sequence nil))
 148       (setq c (lookup-key Helper-help-map c))
 149       (cond ((eq c 'Helper-help-options)
 150              (Helper-help-options))
 151             ((commandp c)
 152              (call-interactively c)
 153              (setq continue nil))
 154             (t
 155              (ding)
 156              (setq continue nil))))))
 157
 158 (provide 'helper)
 159
 160 ;; arch-tag: a0984577-d3e9-4124-ae0d-c46fe740f6a9
 161 ;;; helper.el ends here