Function: with-electric-help

with-electric-help is an autoloaded and byte-compiled function defined in ehelp.el.gz.

Signature

(with-electric-help THUNK &optional BUFFER NOERASE MINHEIGHT)

Documentation

Pop up an "electric" help buffer.

THUNK is a function of no arguments which is called to initialize the contents of BUFFER. BUFFER defaults to *Help*. BUFFER will be erased before THUNK is called unless NOERASE is non-nil. THUNK will be called while BUFFER is current and with standard-output bound to the buffer specified by BUFFER.

If THUNK returns nil, we display BUFFER starting at the top, and shrink the window to fit. If THUNK returns non-nil, we don't do those things.

After THUNK has been called, this function "electrically" pops up a window in which BUFFER is displayed and allows the user to scroll through that buffer in electric-help-mode. The window's height will be at least MINHEIGHT if this value is non-nil.

If THUNK returns nil, we display BUFFER starting at the top, and shrink the window to fit if electric-help-shrink-window is non-nil. If THUNK returns non-nil, we don't do those things.

When the user exits (with electric-help-exit, or otherwise), the help buffer's window disappears (i.e., we use save-window-excursion), and BUFFER is put back into its original major mode.

Source Code

;; Defined in /usr/src/emacs/lisp/ehelp.el.gz
;;;###autoload
(defun with-electric-help (thunk &optional buffer noerase minheight)
  "Pop up an \"electric\" help buffer.
THUNK is a function of no arguments which is called to initialize the
contents of BUFFER.  BUFFER defaults to `*Help*'.  BUFFER will be
erased before THUNK is called unless NOERASE is non-nil.  THUNK will
be called while BUFFER is current and with `standard-output' bound to
the buffer specified by BUFFER.

If THUNK returns nil, we display BUFFER starting at the top, and shrink
the window to fit.  If THUNK returns non-nil, we don't do those things.

After THUNK has been called, this function \"electrically\" pops up a
window in which BUFFER is displayed and allows the user to scroll
through that buffer in `electric-help-mode'.  The window's height will
be at least MINHEIGHT if this value is non-nil.

If THUNK returns nil, we display BUFFER starting at the top, and
shrink the window to fit if `electric-help-shrink-window' is non-nil.
If THUNK returns non-nil, we don't do those things.

When the user exits (with `electric-help-exit', or otherwise), the help
buffer's window disappears (i.e., we use `save-window-excursion'), and
BUFFER is put back into its original major mode."
  (setq buffer (get-buffer-create (or buffer "*Help*")))
  (let ((one (one-window-p t))
	(config (current-window-configuration))
        (bury nil)
        (electric-help-form-to-execute nil))
    (unwind-protect
         (save-excursion
           (when one
	     (goto-char (window-start)))
           (let ((pop-up-windows t))
             (pop-to-buffer buffer))
           (with-current-buffer buffer
             (when (and minheight (< (window-height) minheight))
	       (enlarge-window (- minheight (window-height))))
             (electric-help-mode)
	     (setq buffer-read-only nil)
	     (unless noerase
	       (erase-buffer)))
           (let ((standard-output buffer))
             (unless (funcall thunk)
	       (set-buffer buffer)
	       (set-buffer-modified-p nil)
	       (goto-char (point-min))
	       (when (and one electric-help-shrink-window)
		 (shrink-window-if-larger-than-buffer))))
           (set-buffer buffer)
           (run-hooks 'electric-help-mode-hook)
	   (setq buffer-read-only t)
           (if (eq (car-safe (electric-help-command-loop)) 'retain)
               (setq config (current-window-configuration))
	     (setq bury t))
	   ;; Remove the hook.
	   (when (memq 'electric-help-retain mouse-leave-buffer-hook)
	     (remove-hook 'mouse-leave-buffer-hook 'electric-help-retain)))
      (message "")
      (set-buffer buffer)
      (setq buffer-read-only nil)

      ;; Restore the original major mode saved by `electric-help-mode'.
      ;; We should really get a usable *Help* buffer when retaining
      ;; the electric one with `r'.  The problem is that a simple
      ;; call to `help-mode' won't cut it; e.g. RET is bound wrong
      ;; afterwards (`View-scroll-line-forward' instead of `help-follow').
      ;; That's because Help mode should be set with `with-help-window'
      ;; instead of the direct call to `help-mode'. But at least
      ;; RET works correctly on links after using `help-mode'.
      ;; This is satisfactory enough.
      (condition-case ()
          (funcall (or electric-help-orig-major-mode 'fundamental-mode))
        (error nil))

      (set-window-configuration config)
      (when bury
	;;>> Perhaps this shouldn't be done,
	;; so that when we say "Press space to bury" we mean it
	(replace-buffer-in-windows buffer)
	;; must do this outside of save-window-excursion
	(bury-buffer buffer))
      (if (functionp electric-help-form-to-execute)
          (funcall electric-help-form-to-execute)
        (eval electric-help-form-to-execute)))))