lisp/ehelp.el

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