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