]> code.delx.au - gnu-emacs/blob - lisp/ehelp.el
Merge from emacs-23
[gnu-emacs] / lisp / ehelp.el
1 ;;; ehelp.el --- bindings for electric-help mode
2
3 ;; Copyright (C) 1986, 1995, 2000, 2001, 2002, 2003, 2004, 2005, 2006,
4 ;; 2007, 2008, 2009, 2010, 2011 Free Software Foundation, Inc.
5
6 ;; Author: Richard Mlynarik
7 ;; (according to ack.texi and authors.el)
8 ;; Maintainer: FSF
9 ;; Keywords: help, extensions
10
11 ;; This file is part of GNU Emacs.
12
13 ;; GNU Emacs is free software: you can redistribute it and/or modify
14 ;; it under the terms of the GNU General Public License as published by
15 ;; the Free Software Foundation, either version 3 of the License, or
16 ;; (at your option) any later version.
17
18 ;; GNU Emacs is distributed in the hope that it will be useful,
19 ;; but WITHOUT ANY WARRANTY; without even the implied warranty of
20 ;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
21 ;; GNU General Public License for more details.
22
23 ;; You should have received a copy of the GNU General Public License
24 ;; along with GNU Emacs. If not, see <http://www.gnu.org/licenses/>.
25
26 ;;; Commentary:
27
28 ;; This package provides a pre-packaged `Electric Help Mode' for
29 ;; browsing on-line help screens. There is one entry point,
30 ;; `with-electric-help'; all you have to give it is a no-argument
31 ;; function that generates the actual text of the help into the current
32 ;; buffer.
33
34 ;; To make this the default, you must do
35 ;; (require 'ehelp)
36 ;; (define-key global-map "\C-h" 'ehelp-command)
37 ;; (define-key global-map [help] 'ehelp-command)
38 ;; (define-key global-map [f1] 'ehelp-command)
39
40 ;;; Code:
41
42 (require 'electric)
43
44 (defvar electric-help-form-to-execute nil)
45
46 (defgroup electric-help ()
47 "Electric help facility."
48 :version "21.1"
49 :group 'help)
50
51 (defcustom electric-help-shrink-window t
52 "If set, adjust help window sizes to buffer sizes when displaying help."
53 :type 'boolean
54 :group 'electric-help)
55
56 (defcustom electric-help-mode-hook nil
57 "Hook run by `with-electric-help' after initializing the buffer."
58 :type 'hook
59 :group 'electric-help)
60
61 (put 'electric-help-undefined 'suppress-keymap t)
62
63 (defvar electric-help-map
64 (let ((map (make-keymap)))
65 ;; allow all non-self-inserting keys - search, scroll, etc, but
66 ;; let M-x and C-x exit ehelp mode and retain buffer:
67 (suppress-keymap map)
68 (define-key map "\C-u" 'electric-help-undefined)
69 (define-key map [?\C-0] 'electric-help-undefined)
70 (define-key map [?\C-1] 'electric-help-undefined)
71 (define-key map [?\C-2] 'electric-help-undefined)
72 (define-key map [?\C-3] 'electric-help-undefined)
73 (define-key map [?\C-4] 'electric-help-undefined)
74 (define-key map [?\C-5] 'electric-help-undefined)
75 (define-key map [?\C-6] 'electric-help-undefined)
76 (define-key map [?\C-7] 'electric-help-undefined)
77 (define-key map [?\C-8] 'electric-help-undefined)
78 (define-key map [?\C-9] 'electric-help-undefined)
79 (define-key map (char-to-string help-char) 'electric-help-help)
80 (define-key map "?" 'electric-help-help)
81 (define-key map " " 'scroll-up)
82 (define-key map "\^?" 'scroll-down)
83 (define-key map "." 'beginning-of-buffer)
84 (define-key map "<" 'beginning-of-buffer)
85 (define-key map ">" 'end-of-buffer)
86 ;(define-key map "\C-g" 'electric-help-exit)
87 (define-key map "Q" 'electric-help-exit)
88 (define-key map "q" 'electric-help-exit)
89 ;;a better key than this?
90 (define-key map "R" 'electric-help-retain)
91 (define-key map "r" 'electric-help-retain)
92 (define-key map "\ex" 'electric-help-execute-extended)
93 (define-key map "\C-x" 'electric-help-ctrl-x-prefix)
94 map)
95 "Keymap defining commands available in `electric-help-mode'.")
96
97 (defvar electric-help-orig-major-mode nil)
98 (make-variable-buffer-local 'electric-help-orig-major-mode)
99
100 (defun electric-help-mode ()
101 "`with-electric-help' temporarily places its buffer in this mode.
102 \(On exit from `with-electric-help', the original `major-mode' is restored.)"
103 (setq buffer-read-only t)
104 (setq electric-help-orig-major-mode major-mode)
105 (setq mode-name "Help")
106 (setq major-mode 'help)
107 (setq mode-line-buffer-identification '(" Help: %b"))
108 (use-local-map electric-help-map)
109 (add-hook 'mouse-leave-buffer-hook 'electric-help-retain)
110 (view-mode -1)
111 ;; this is done below in with-electric-help
112 ;(run-hooks 'electric-help-mode-hook)
113 )
114
115 ;;;###autoload
116 (defun with-electric-help (thunk &optional buffer noerase minheight)
117 "Pop up an \"electric\" help buffer.
118 THUNK is a function of no arguments which is called to initialize the
119 contents of BUFFER. BUFFER defaults to `*Help*'. BUFFER will be
120 erased before THUNK is called unless NOERASE is non-nil. THUNK will
121 be called while BUFFER is current and with `standard-output' bound to
122 the buffer specified by BUFFER.
123
124 If THUNK returns nil, we display BUFFER starting at the top, and shrink
125 the window to fit. If THUNK returns non-nil, we don't do those things.
126
127 After THUNK has been called, this function \"electrically\" pops up a
128 window in which BUFFER is displayed and allows the user to scroll
129 through that buffer in `electric-help-mode'. The window's height will
130 be at least MINHEIGHT if this value is non-nil.
131
132 If THUNK returns nil, we display BUFFER starting at the top, and
133 shrink the window to fit if `electric-help-shrink-window' is non-nil.
134 If THUNK returns non-nil, we don't do those things.
135
136 When the user exits (with `electric-help-exit', or otherwise), the help
137 buffer's window disappears (i.e., we use `save-window-excursion'), and
138 BUFFER is put back into its original major mode."
139 (setq buffer (get-buffer-create (or buffer "*Help*")))
140 (let ((one (one-window-p t))
141 (config (current-window-configuration))
142 (bury nil)
143 (electric-help-form-to-execute nil))
144 (unwind-protect
145 (save-excursion
146 (when one
147 (goto-char (window-start (selected-window))))
148 (let ((pop-up-windows t))
149 (pop-to-buffer buffer))
150 (with-current-buffer buffer
151 (when (and minheight (< (window-height) minheight))
152 (enlarge-window (- minheight (window-height))))
153 (electric-help-mode)
154 (setq buffer-read-only nil)
155 (unless noerase
156 (erase-buffer)))
157 (let ((standard-output buffer))
158 (unless (funcall thunk)
159 (set-buffer buffer)
160 (set-buffer-modified-p nil)
161 (goto-char (point-min))
162 (when (and one electric-help-shrink-window)
163 (shrink-window-if-larger-than-buffer))))
164 (set-buffer buffer)
165 (run-hooks 'electric-help-mode-hook)
166 (setq buffer-read-only t)
167 (if (eq (car-safe (electric-help-command-loop)) 'retain)
168 (setq config (current-window-configuration))
169 (setq bury t))
170 ;; Remove the hook.
171 (when (memq 'electric-help-retain mouse-leave-buffer-hook)
172 (remove-hook 'mouse-leave-buffer-hook 'electric-help-retain)))
173 (message "")
174 (set-buffer buffer)
175 (setq buffer-read-only nil)
176
177 ;; Restore the original major mode saved by `electric-help-mode'.
178 ;; We should really get a usable *Help* buffer when retaining
179 ;; the electric one with `r'. The problem is that a simple
180 ;; call to `help-mode' won't cut it; e.g. RET is bound wrong
181 ;; afterwards (`View-scroll-line-forward' instead of `help-follow').
182 ;; That's because Help mode should be set with `with-help-window'
183 ;; instead of the direct call to `help-mode'. But at least
184 ;; RET works correctly on links after using `help-mode'.
185 ;; This is satisfactory enough.
186 (condition-case ()
187 (funcall (or electric-help-orig-major-mode 'fundamental-mode))
188 (error nil))
189
190 (set-window-configuration config)
191 (when bury
192 ;;>> Perhaps this shouldn't be done,
193 ;; so that when we say "Press space to bury" we mean it
194 (replace-buffer-in-windows buffer)
195 ;; must do this outside of save-window-excursion
196 (bury-buffer buffer))
197 (eval electric-help-form-to-execute))))
198
199 (defun electric-help-command-loop ()
200 (catch 'exit
201 (if (pos-visible-in-window-p (point-max))
202 (progn (message "%s" (substitute-command-keys "<<< Press Space to bury the help buffer, Press \\[electric-help-retain] to retain it >>>"))
203 (if (equal (setq unread-command-events (list (read-event)))
204 '(?\s))
205 (progn (setq unread-command-events nil)
206 (throw 'exit t)))))
207 (let (up down both neither
208 (standard (and (eq (key-binding " " nil t)
209 'scroll-up)
210 (eq (key-binding "\^?" nil t)
211 'scroll-down)
212 (eq (key-binding "q" nil t)
213 'electric-help-exit)
214 (eq (key-binding "r" nil t)
215 'electric-help-retain))))
216 (Electric-command-loop
217 'exit
218 (function (lambda ()
219 (sit-for 0) ;necessary if last command was end-of-buffer or
220 ;beginning-of-buffer - otherwise pos-visible-in-window-p
221 ;will yield a wrong result.
222 (let ((min (pos-visible-in-window-p (point-min)))
223 (max (pos-visible-in-window-p (1- (point-max)))))
224 (cond (isearch-mode 'noprompt)
225 ((and min max)
226 (cond (standard "Press q to exit, r to retain ")
227 (neither)
228 (t (setq neither (substitute-command-keys "Press \\[electric-help-exit] to exit, \\[electric-help-retain] to retain ")))))
229 (min
230 (cond (standard "Press SPC to scroll, q to exit, r to retain ")
231 (up)
232 (t (setq up (substitute-command-keys "Press \\[scroll-up] to scroll, \\[electric-help-exit] to exit, \\[electric-help-retain] to retain ")))))
233 (max
234 (cond (standard "Press DEL to scroll back, q to exit, r to retain ")
235 (down)
236 (t (setq down (substitute-command-keys "Press \\[scroll-down] to scroll back, \\[electric-help-exit] to exit, \\[electric-help-retain] to retain ")))))
237 (t
238 (cond (standard "Press SPC to scroll, DEL to scroll back, q to exit, r to retain ")
239 (both)
240 (t (setq both (substitute-command-keys "Press \\[scroll-up] to scroll, \\[scroll-down] to scroll back, \\[electric-help-exit] to exit, \\[electric-help-retain] to retain ")))))))))
241 t))))
242
243
244 \f
245 ;(defun electric-help-scroll-up (arg)
246 ; ">>>Doc"
247 ; (interactive "P")
248 ; (if (and (null arg) (pos-visible-in-window-p (point-max)))
249 ; (electric-help-exit)
250 ; (scroll-up arg)))
251
252 (defun electric-help-exit ()
253 "Exit `with-electric-help', restoring the previous window/buffer configuration.
254 \(The *Help* buffer will be buried.)"
255 (interactive)
256 ;; Make sure that we don't throw twice, even if two events cause
257 ;; calling this function:
258 (if (memq 'electric-help-retain mouse-leave-buffer-hook)
259 (progn
260 (remove-hook 'mouse-leave-buffer-hook 'electric-help-retain)
261 (throw 'exit t))))
262
263 (defun electric-help-retain ()
264 "Exit `with-electric-help', retaining the current window/buffer configuration.
265 \(The *Help* buffer will not be selected, but \\[switch-to-buffer-other-window] RET
266 will select it.)"
267 (interactive)
268 ;; Make sure that we don't throw twice, even if two events cause
269 ;; calling this function:
270 (if (memq 'electric-help-retain mouse-leave-buffer-hook)
271 (progn
272 (remove-hook 'mouse-leave-buffer-hook 'electric-help-retain)
273 (throw 'exit '(retain)))))
274
275
276 (defun electric-help-undefined ()
277 (interactive)
278 (error "%s is undefined -- Press %s to exit"
279 (mapconcat 'single-key-description (this-command-keys) " ")
280 (if (eq (key-binding "q" nil t) 'electric-help-exit)
281 "q"
282 (substitute-command-keys "\\[electric-help-exit]"))))
283
284
285 ;>>> this needs to be hairified (recursive help, anybody?)
286 (defun electric-help-help ()
287 (interactive)
288 (if (and (eq (key-binding "q" nil t) 'electric-help-exit)
289 (eq (key-binding " " nil t) 'scroll-up)
290 (eq (key-binding "\^?" nil t) 'scroll-down)
291 (eq (key-binding "r" nil t) 'electric-help-retain))
292 (message "SPC scrolls up, DEL scrolls down, q exits burying help buffer, r exits")
293 (message "%s" (substitute-command-keys "\\[scroll-up] scrolls up, \\[scroll-down] scrolls down, \\[electric-help-exit] exits burying help buffer, \\[electric-help-retain] exits")))
294 (sit-for 2))
295
296 \f
297 ;;;###autoload
298 (defun electric-helpify (fun &optional name)
299 (let ((name (or name "*Help*")))
300 (if (save-window-excursion
301 ;; kludge-o-rama
302 (let* ((p (symbol-function 'help-print-return-message))
303 (b (get-buffer name))
304 (m (buffer-modified-p b)))
305 (and b (not (get-buffer-window b))
306 (setq b nil))
307 (unwind-protect
308 (progn
309 (message "%s..." (capitalize (symbol-name fun)))
310 ;; with-output-to-temp-buffer marks the buffer as unmodified.
311 ;; kludging excessively and relying on that as some sort
312 ;; of indication leads to the following abomination...
313 ;;>> This would be doable without such icky kludges if either
314 ;;>> (a) there were a function to read the interactive
315 ;;>> args for a command and return a list of those args.
316 ;;>> (To which one would then just apply the command)
317 ;;>> (The only problem with this is that interactive-p
318 ;;>> would break, but that is such a misfeature in
319 ;;>> any case that I don't care)
320 ;;>> It is easy to do this for emacs-lisp functions;
321 ;;>> the only problem is getting the interactive spec
322 ;;>> for subrs
323 ;;>> (b) there were a function which returned a
324 ;;>> modification-tick for a buffer. One could tell
325 ;;>> whether a buffer had changed by whether the
326 ;;>> modification-tick were different.
327 ;;>> (Presumably there would have to be a way to either
328 ;;>> restore the tick to some previous value, or to
329 ;;>> suspend updating of the tick in order to allow
330 ;;>> things like momentary-string-display)
331 (and b
332 (with-current-buffer b
333 (set-buffer-modified-p t)))
334 (fset 'help-print-return-message 'ignore)
335 (call-interactively fun)
336 (and (get-buffer name)
337 (get-buffer-window (get-buffer name))
338 (or (not b)
339 (not (eq b (get-buffer name)))
340 (not (buffer-modified-p b)))))
341 (fset 'help-print-return-message p)
342 (and b (buffer-name b)
343 (with-current-buffer b
344 (set-buffer-modified-p m))))))
345 (with-electric-help 'ignore name t))))
346
347 \f
348
349 ;; This is to be bound to M-x in ehelp mode. Retains ehelp buffer and then
350 ;; continues with execute-extended-command.
351 (defun electric-help-execute-extended (prefixarg)
352 (interactive "p")
353 (setq electric-help-form-to-execute '(execute-extended-command nil))
354 (electric-help-retain))
355
356 ;; This is to be buond to C-x in ehelp mode. Retains ehelp buffer and then
357 ;; continues with ctrl-x prefix.
358 (defun electric-help-ctrl-x-prefix (prefixarg)
359 (interactive "p")
360 (setq electric-help-form-to-execute '(progn (message nil) (setq unread-command-char ?\C-x)))
361 (electric-help-retain))
362
363 \f
364 (defun electric-describe-key ()
365 (interactive)
366 (electric-helpify 'describe-key))
367
368 (defun electric-describe-mode ()
369 (interactive)
370 (electric-helpify 'describe-mode))
371
372 (defun electric-view-lossage ()
373 (interactive)
374 (electric-helpify 'view-lossage))
375
376 ;(defun electric-help-for-help ()
377 ; "See help-for-help"
378 ; (interactive)
379 ; )
380
381 (defun electric-describe-function ()
382 (interactive)
383 (electric-helpify 'describe-function))
384
385 (defun electric-describe-variable ()
386 (interactive)
387 (electric-helpify 'describe-variable))
388
389 (defun electric-describe-bindings ()
390 (interactive)
391 (electric-helpify 'describe-bindings))
392
393 (defun electric-describe-syntax ()
394 (interactive)
395 (electric-helpify 'describe-syntax))
396
397 (defun electric-command-apropos ()
398 (interactive)
399 (electric-helpify 'command-apropos "*Apropos*"))
400
401 ;(define-key help-map "a" 'electric-command-apropos)
402
403 (defun electric-apropos ()
404 (interactive)
405 (electric-helpify 'apropos))
406
407 \f
408 ;;;; ehelp-map
409
410 (defvar ehelp-map
411 (let ((map (copy-keymap help-map)))
412 (substitute-key-definition 'apropos 'electric-apropos map)
413 (substitute-key-definition 'command-apropos 'electric-command-apropos map)
414 (substitute-key-definition 'describe-key 'electric-describe-key map)
415 (substitute-key-definition 'describe-mode 'electric-describe-mode map)
416 (substitute-key-definition 'view-lossage 'electric-view-lossage map)
417 (substitute-key-definition 'describe-function 'electric-describe-function map)
418 (substitute-key-definition 'describe-variable 'electric-describe-variable map)
419 (substitute-key-definition 'describe-bindings 'electric-describe-bindings map)
420 (substitute-key-definition 'describe-syntax 'electric-describe-syntax map)
421 map))
422
423 ;;;###(autoload 'ehelp-command "ehelp" "Prefix command for ehelp." t 'keymap)
424 (defalias 'ehelp-command ehelp-map)
425 (put 'ehelp-command 'documentation "Prefix command for ehelp.")
426
427 (provide 'ehelp)
428
429 ;; arch-tag: e0e3037f-42c0-433e-ba18-322c5d951f46
430 ;;; ehelp.el ends here