lisp/emacs-lisp/helper.el

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