lisp/ehelp.el

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