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