1;;; helper.el --- utility help package supporting help in electric modes
2
3;; Copyright (C) 1985, 2001, 2002, 2003, 2004, 2005,
4;;   2006, 2007 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 2, 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 mode-name)
124	(documentation (documentation major-mode)))
125    (save-excursion
126      (set-buffer (get-buffer-create "*Help*"))
127      (setq buffer-read-only nil)
128      (erase-buffer)
129      (insert name " Mode\n" documentation)
130      (help-mode)))
131  (Helper-help-scroller))
132
133;;;###autoload
134(defun Helper-describe-bindings ()
135  "Describe local key bindings of current mode."
136  (interactive)
137  (message "Making binding list...")
138  (save-window-excursion (describe-bindings))
139  (Helper-help-scroller))
140
141;;;###autoload
142(defun Helper-help ()
143  "Provide help for current mode."
144  (interactive)
145  (let ((continue t) c)
146    (while continue
147      (message "Help (Type ? for further options)")
148      (setq c (read-key-sequence nil))
149      (setq c (lookup-key Helper-help-map c))
150      (cond ((eq c 'Helper-help-options)
151	     (Helper-help-options))
152	    ((commandp c)
153	     (call-interactively c)
154	     (setq continue nil))
155	    (t
156	     (ding)
157	     (setq continue nil))))))
158
159(provide 'helper)
160
161;;; arch-tag: a0984577-d3e9-4124-ae0d-c46fe740f6a9
162;;; helper.el ends here
163