Commit | Line | Data |
---|---|---|
c0274f38 ER |
1 | ;;; ehelp.el --- bindings for electric-help mode |
2 | ||
e5167999 ER |
3 | ;; Maintainer: FSF |
4 | ;; Last-Modified: 16 Mar 1992 | |
fd7fa35a | 5 | ;; Keywords: help, extensions |
e5167999 | 6 | |
a2535589 JA |
7 | ;; Copyright (C) 1986 Free Software Foundation, Inc. |
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 | |
e5167999 | 13 | ;; the Free Software Foundation; either version 2, or (at your option) |
a2535589 JA |
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 | |
23 | ;; the Free Software Foundation, 675 Mass Ave, Cambridge, MA 02139, USA. | |
24 | ||
e5167999 ER |
25 | ;;; Code: |
26 | ||
a2535589 | 27 | (require 'electric) |
a2535589 | 28 | (defvar electric-help-map () |
d5b9d1d8 | 29 | "Keymap defining commands available in `electric-help-mode'.") |
a2535589 JA |
30 | |
31 | (put 'electric-help-undefined 'suppress-keymap t) | |
32 | (if electric-help-map | |
33 | () | |
34 | (let ((map (make-keymap))) | |
35 | (fillarray map 'electric-help-undefined) | |
36 | (define-key map (char-to-string meta-prefix-char) (copy-keymap map)) | |
37 | (define-key map (char-to-string help-char) 'electric-help-help) | |
38 | (define-key map "?" 'electric-help-help) | |
39 | (define-key map " " 'scroll-up) | |
40 | (define-key map "\^?" 'scroll-down) | |
41 | (define-key map "." 'beginning-of-buffer) | |
42 | (define-key map "<" 'beginning-of-buffer) | |
43 | (define-key map ">" 'end-of-buffer) | |
44 | ;(define-key map "\C-g" 'electric-help-exit) | |
45 | (define-key map "q" 'electric-help-exit) | |
46 | (define-key map "Q" 'electric-help-exit) | |
47 | ;;a better key than this? | |
48 | (define-key map "r" 'electric-help-retain) | |
49 | ||
50 | (setq electric-help-map map))) | |
51 | ||
52 | (defun electric-help-mode () | |
d5b9d1d8 JB |
53 | "`with-electric-help' temporarily places its buffer in this mode. |
54 | \(On exit from `with-electric-help', the buffer is put in `default-major-mode'.)" | |
a2535589 JA |
55 | (setq buffer-read-only t) |
56 | (setq mode-name "Help") | |
57 | (setq major-mode 'help) | |
58 | (setq mode-line-buffer-identification '(" Help: %b")) | |
59 | (use-local-map electric-help-map) | |
60 | ;; this is done below in with-electric-help | |
61 | ;(run-hooks 'electric-help-mode-hook) | |
62 | ) | |
63 | ||
64 | (defun with-electric-help (thunk &optional buffer noerase) | |
d5b9d1d8 JB |
65 | "Arguments are THUNK &optional BUFFER NOERASE. BUFFER defaults to \"*Help*\" |
66 | THUNK is a function of no arguments which is called to initialize | |
67 | the contents of BUFFER. BUFFER will be erased before THUNK is called unless | |
68 | NOERASE is non-nil. THUNK will be called with `standard-output' bound to | |
69 | the buffer specified by BUFFER | |
a2535589 JA |
70 | |
71 | After THUNK has been called, this function \"electrically\" pops up a window | |
72 | in which BUFFER is displayed and allows the user to scroll through that buffer | |
73 | in electric-help-mode. | |
d5b9d1d8 JB |
74 | When the user exits (with `electric-help-exit', or otherwise) the help |
75 | buffer's window disappears (i.e., we use `save-window-excursion') | |
76 | BUFFER is put into `default-major-mode' (or `fundamental-mode') when we exit" | |
a2535589 JA |
77 | (setq buffer (get-buffer-create (or buffer "*Help*"))) |
78 | (let ((one (one-window-p t)) | |
88c269cb | 79 | (config (current-window-configuration)) |
80 | (bury nil)) | |
81 | (unwind-protect | |
82 | (save-excursion | |
83 | (if one (goto-char (window-start (selected-window)))) | |
84 | (let ((pop-up-windows t)) | |
85 | (pop-to-buffer buffer)) | |
86 | (save-excursion | |
87 | (set-buffer buffer) | |
88 | (electric-help-mode) | |
89 | (setq buffer-read-only nil) | |
90 | (or noerase (erase-buffer))) | |
91 | (let ((standard-output buffer)) | |
92 | (if (not (funcall thunk)) | |
93 | (progn | |
94 | (set-buffer buffer) | |
95 | (set-buffer-modified-p nil) | |
96 | (goto-char (point-min)) | |
97 | (if one (shrink-window-if-larger-than-buffer (selected-window)))))) | |
98 | (set-buffer buffer) | |
99 | (run-hooks 'electric-help-mode-hook) | |
100 | (if (eq (car-safe (electric-help-command-loop)) | |
101 | 'retain) | |
102 | (setq config (current-window-configuration)) | |
103 | (setq bury t))) | |
104 | (message "") | |
105 | (set-buffer buffer) | |
106 | (setq buffer-read-only nil) | |
107 | (condition-case () | |
108 | (funcall (or default-major-mode 'fundamental-mode)) | |
109 | (error nil)) | |
110 | (set-window-configuration config) | |
111 | (if bury | |
112 | (progn | |
113 | ;;>> Perhaps this shouldn't be done. | |
114 | ;; so that when we say "Press space to bury" we mean it | |
115 | (replace-buffer-in-windows buffer) | |
116 | ;; must do this outside of save-window-excursion | |
117 | (bury-buffer buffer)))))) | |
a2535589 JA |
118 | |
119 | (defun electric-help-command-loop () | |
120 | (catch 'exit | |
121 | (if (pos-visible-in-window-p (point-max)) | |
122 | (progn (message "<<< Press Space to bury the help buffer >>>") | |
123 | (if (= (setq unread-command-char (read-char)) ?\ ) | |
124 | (progn (setq unread-command-char -1) | |
125 | (throw 'exit t))))) | |
126 | (let (up down both neither | |
127 | (standard (and (eq (key-binding " ") | |
128 | 'scroll-up) | |
129 | (eq (key-binding "\^?") | |
130 | 'scroll-down) | |
131 | (eq (key-binding "Q") | |
132 | 'electric-help-exit) | |
133 | (eq (key-binding "q") | |
134 | 'electric-help-exit)))) | |
135 | (Electric-command-loop | |
136 | 'exit | |
137 | (function (lambda () | |
138 | (let ((min (pos-visible-in-window-p (point-min))) | |
139 | (max (pos-visible-in-window-p (point-max)))) | |
140 | (cond ((and min max) | |
141 | (cond (standard "Press Q to exit ") | |
142 | (neither) | |
143 | (t (setq neither (substitute-command-keys "Press \\[scroll-up] to exit "))))) | |
144 | (min | |
145 | (cond (standard "Press SPC to scroll, Q to exit ") | |
146 | (up) | |
147 | (t (setq up (substitute-command-keys "Press \\[scroll-up] to scroll; \\[electric-help-exit] to exit "))))) | |
148 | (max | |
149 | (cond (standard "Press DEL to scroll back, Q to exit ") | |
150 | (down) | |
151 | (t (setq down (substitute-command-keys "Press \\[scroll-down] to scroll back, \\[scroll-up] to exit "))))) | |
152 | (t | |
153 | (cond (standard "Press SPC to scroll, DEL to scroll back, Q to exit ") | |
154 | (both) | |
155 | (t (setq both (substitute-command-keys "Press \\[scroll-up] to scroll, \\[scroll-down] to scroll back, \\[electric-help-exit] to exit "))))))))) | |
156 | t)))) | |
157 | ||
158 | ||
159 | \f | |
160 | ;(defun electric-help-scroll-up (arg) | |
161 | ; ">>>Doc" | |
162 | ; (interactive "P") | |
163 | ; (if (and (null arg) (pos-visible-in-window-p (point-max))) | |
164 | ; (electric-help-exit) | |
165 | ; (scroll-up arg))) | |
166 | ||
167 | (defun electric-help-exit () | |
168 | ">>>Doc" | |
169 | (interactive) | |
170 | (throw 'exit t)) | |
171 | ||
172 | (defun electric-help-retain () | |
d5b9d1d8 | 173 | "Exit `electric-help', retaining the current window/buffer configuration. |
a2535589 JA |
174 | \(The *Help* buffer will not be selected, but \\[switch-to-buffer-other-window] RET |
175 | will select it.)" | |
176 | (interactive) | |
177 | (throw 'exit '(retain))) | |
178 | ||
179 | ||
a2535589 JA |
180 | (defun electric-help-undefined () |
181 | (interactive) | |
182 | (error "%s is undefined -- Press %s to exit" | |
183 | (mapconcat 'single-key-description (this-command-keys) " ") | |
184 | (if (eq (key-binding "Q") 'electric-help-exit) | |
185 | "Q" | |
186 | (substitute-command-keys "\\[electric-help-exit]")))) | |
187 | ||
188 | ||
189 | ;>>> this needs to be hairified (recursive help, anybody?) | |
190 | (defun electric-help-help () | |
191 | (interactive) | |
192 | (if (and (eq (key-binding "Q") 'electric-help-exit) | |
193 | (eq (key-binding " ") 'scroll-up) | |
194 | (eq (key-binding "\^?") 'scroll-down)) | |
195 | (message "SPC scrolls forward, DEL scrolls back, Q exits and burys help buffer") | |
196 | ;; to give something for user to look at while slow substitute-cmd-keys | |
197 | ;; grinds away | |
198 | (message "Help...") | |
199 | (message "%s" (substitute-command-keys "\\[scroll-up] scrolls forward, \\[scroll-down] scrolls back, \\[electric-help-exit] exits."))) | |
200 | (sit-for 2)) | |
201 | ||
202 | \f | |
203 | (defun electric-helpify (fun) | |
204 | (let ((name "*Help*")) | |
205 | (if (save-window-excursion | |
206 | ;; kludge-o-rama | |
207 | (let* ((p (symbol-function 'print-help-return-message)) | |
208 | (b (get-buffer name)) | |
209 | (m (buffer-modified-p b))) | |
210 | (and b (not (get-buffer-window b)) | |
211 | (setq b nil)) | |
212 | (unwind-protect | |
213 | (progn | |
214 | (message "%s..." (capitalize (symbol-name fun))) | |
215 | ;; with-output-to-temp-buffer marks the buffer as unmodified. | |
216 | ;; kludging excessively and relying on that as some sort | |
217 | ;; of indication leads to the following abomination... | |
218 | ;;>> This would be doable without such icky kludges if either | |
219 | ;;>> (a) there were a function to read the interactive | |
220 | ;;>> args for a command and return a list of those args. | |
221 | ;;>> (To which one would then just apply the command) | |
222 | ;;>> (The only problem with this is that interactive-p | |
223 | ;;>> would break, but that is such a misfeature in | |
224 | ;;>> any case that I don't care) | |
225 | ;;>> It is easy to do this for emacs-lisp functions; | |
226 | ;;>> the only problem is getting the interactive spec | |
227 | ;;>> for subrs | |
228 | ;;>> (b) there were a function which returned a | |
229 | ;;>> modification-tick for a buffer. One could tell | |
230 | ;;>> whether a buffer had changed by whether the | |
231 | ;;>> modification-tick were different. | |
232 | ;;>> (Presumably there would have to be a way to either | |
233 | ;;>> restore the tick to some previous value, or to | |
234 | ;;>> suspend updating of the tick in order to allow | |
235 | ;;>> things like momentary-string-display) | |
236 | (and b | |
237 | (save-excursion | |
238 | (set-buffer b) | |
239 | (set-buffer-modified-p t))) | |
240 | (fset 'print-help-return-message 'ignore) | |
241 | (call-interactively fun) | |
242 | (and (get-buffer name) | |
243 | (get-buffer-window (get-buffer name)) | |
244 | (or (not b) | |
245 | (not (eq b (get-buffer name))) | |
246 | (not (buffer-modified-p b))))) | |
247 | (fset 'print-help-return-message p) | |
248 | (and b (buffer-name b) | |
249 | (save-excursion | |
250 | (set-buffer b) | |
251 | (set-buffer-modified-p m)))))) | |
252 | (with-electric-help 'ignore name t)))) | |
253 | ||
254 | \f | |
255 | (defun electric-describe-key () | |
256 | (interactive) | |
257 | (electric-helpify 'describe-key)) | |
258 | ||
259 | (defun electric-describe-mode () | |
260 | (interactive) | |
261 | (electric-helpify 'describe-mode)) | |
262 | ||
263 | (defun electric-view-lossage () | |
264 | (interactive) | |
265 | (electric-helpify 'view-lossage)) | |
266 | ||
267 | ;(defun electric-help-for-help () | |
268 | ; "See help-for-help" | |
269 | ; (interactive) | |
270 | ; ) | |
271 | ||
272 | (defun electric-describe-function () | |
273 | (interactive) | |
274 | (electric-helpify 'describe-function)) | |
275 | ||
276 | (defun electric-describe-variable () | |
277 | (interactive) | |
278 | (electric-helpify 'describe-variable)) | |
279 | ||
280 | (defun electric-describe-bindings () | |
281 | (interactive) | |
282 | (electric-helpify 'describe-bindings)) | |
283 | ||
284 | (defun electric-describe-syntax () | |
285 | (interactive) | |
286 | (electric-helpify 'describe-syntax)) | |
287 | ||
288 | (defun electric-command-apropos () | |
289 | (interactive) | |
290 | (electric-helpify 'command-apropos)) | |
291 | ||
292 | ;(define-key help-map "a" 'electric-command-apropos) | |
293 | ||
294 | ||
a2535589 JA |
295 | \f |
296 | ;;;; ehelp-map | |
297 | ||
298 | (defvar ehelp-map ()) | |
299 | (if ehelp-map | |
300 | nil | |
301 | (let ((map (copy-keymap help-map))) | |
302 | (substitute-key-definition 'describe-key 'electric-describe-key map) | |
303 | (substitute-key-definition 'describe-mode 'electric-describe-mode map) | |
304 | (substitute-key-definition 'view-lossage 'electric-view-lossage map) | |
305 | (substitute-key-definition 'describe-function 'electric-describe-function map) | |
306 | (substitute-key-definition 'describe-variable 'electric-describe-variable map) | |
307 | (substitute-key-definition 'describe-bindings 'electric-describe-bindings map) | |
308 | (substitute-key-definition 'describe-syntax 'electric-describe-syntax map) | |
309 | ||
310 | (setq ehelp-map map) | |
311 | (fset 'ehelp-command map))) | |
312 | ||
313 | ;; Do (define-key global-map "\C-h" 'ehelp-command) if you want to win | |
49116ac0 JB |
314 | |
315 | (provide 'ehelp) | |
316 | ||
c0274f38 | 317 | ;;; ehelp.el ends here |