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