;;; help.el --- help commands for Emacs
-;; Copyright (C) 1985-1986, 1993-1994, 1998-2011
-;; Free Software Foundation, Inc.
+;; Copyright (C) 1985-1986, 1993-1994, 1998-2013 Free Software
+;; Foundation, Inc.
;; Maintainer: FSF
;; Keywords: help, internal
;;; Commentary:
-;; This code implements GNU Emacs' on-line help system, the one invoked by
+;; This code implements GNU Emacs's on-line help system, the one invoked by
;; `M-x help-for-help'.
;;; Code:
(add-hook 'temp-buffer-setup-hook 'help-mode-setup)
(add-hook 'temp-buffer-show-hook 'help-mode-finish)
-;; The variable `help-window' below is used by `help-mode-finish' to
-;; communicate the window displaying help (the "help window") to the
-;; macro `with-help-window'. The latter sets `help-window' to t before
-;; invoking `with-output-to-temp-buffer'. If and only if `help-window'
-;; is eq to t, `help-mode-finish' (called by `temp-buffer-setup-hook')
-;; sets `help-window' to the window selected by `display-buffer'.
-;; Exiting `with-help-window' and calling `help-print-return-message'
-;; reset `help-window' to nil.
-(defvar help-window nil
- "Window chosen for displaying help.")
-
;; `help-window-point-marker' is a marker you can move to a valid
;; position of the buffer shown in the help window in order to override
;; the standard positioning mechanism (`point-min') chosen by
-;; `with-output-to-temp-buffer'. `with-help-window' has this point
-;; nowhere before exiting. Currently used by `view-lossage' to assert
-;; that the last keystrokes are always visible.
+;; `with-output-to-temp-buffer' and `with-temp-buffer-window'.
+;; `with-help-window' has this point nowhere before exiting. Currently
+;; used by `view-lossage' to assert that the last keystrokes are always
+;; visible.
(defvar help-window-point-marker (make-marker)
"Marker to override default `window-point' in help windows.")
;; Secondly, the buffer has not been displayed yet,
;; so we don't know whether its frame will be selected.
nil)
- (display-buffer-reuse-frames
- (setq help-return-method (cons (selected-window)
- 'quit-window))
- nil)
((not (one-window-p t))
(setq help-return-method
(cons (selected-window) 'quit-window))
The number of messages retained in that buffer
is specified by the variable `message-log-max'."
(interactive)
- (switch-to-buffer (get-buffer-create "*Messages*")))
+ (with-current-buffer (get-buffer-create "*Messages*")
+ (goto-char (point-max))
+ (display-buffer (current-buffer))))
(defun view-order-manuals ()
"Display the Emacs ORDERS file."
(unless definition (error "No command"))
(let ((func (indirect-function definition))
(defs nil)
- (standard-output (if insert (current-buffer) t)))
+ (standard-output (if insert (current-buffer) standard-output)))
;; In DEFS, find all symbols that are aliases for DEFINITION.
(mapatoms (lambda (symbol)
(and (fboundp symbol)
(setq saved-yank-menu (copy-sequence yank-menu))
(menu-bar-update-yank-menu "(any string)" nil))
(setq key (read-key-sequence "Describe key (or click or menu item): "))
+ ;; Clear the echo area message (Bug#7014).
+ (message nil)
;; If KEY is a down-event, read and discard the
;; corresponding up-event. Note that there are also
;; down-events on scroll bars and mode lines: the actual
(aref key 1)
(aref key 0)))
(modifiers (event-modifiers event))
- (standard-output (if insert (current-buffer) t))
+ (standard-output (if insert (current-buffer) standard-output))
(mouse-msg (if (or (memq 'click modifiers) (memq 'down modifiers)
(memq 'drag modifiers)) " at that spot" ""))
(defn (key-binding key t))
For this to work correctly for a minor mode, the mode's indicator
variable \(listed in `minor-mode-alist') must also be a function
-whose documentation describes the minor mode."
+whose documentation describes the minor mode.
+
+If called from Lisp with a non-nil BUFFER argument, display
+documentation for the major and minor modes of that buffer."
(interactive "@")
(unless buffer (setq buffer (current-buffer)))
(help-setup-xref (list #'describe-mode buffer)
(error "Cannot find minor mode for `%s'" indicator))))
(defun lookup-minor-mode-from-indicator (indicator)
- "Return a minor mode symbol from its indicator on the modeline."
+ "Return a minor mode symbol from its indicator on the mode line."
;; remove first space if existed
(if (and (< 0 (length indicator))
(eq (aref indicator 0) ?\s))
result))
\f
;;; Automatic resizing of temporary buffers.
-(defcustom temp-buffer-max-height (lambda (buffer) (/ (- (frame-height) 2) 2))
+(defcustom temp-buffer-max-height
+ (lambda (buffer)
+ (if (eq (selected-window) (frame-root-window))
+ (/ (x-display-pixel-height) (frame-char-height) 2)
+ (/ (- (frame-height) 2) 2)))
"Maximum height of a window displaying a temporary buffer.
This is effective only when Temp Buffer Resize mode is enabled.
The value is the maximum height (in lines) which
`resize-temp-buffer-window' will give to a window displaying a
temporary buffer. It can also be a function to be called to
-choose the height for such a buffer. It gets one argumemt, the
+choose the height for such a buffer. It gets one argument, the
buffer, and should return a positive integer. At the time the
function is called, the window to be resized is selected."
:type '(choice integer function)
:group 'help
- :version "20.4")
+ :version "24.3")
(define-minor-mode temp-buffer-resize-mode
- "Toggle mode which makes windows smaller for temporary buffers.
-With prefix argument ARG, turn the resizing of windows displaying
-temporary buffers on if ARG is positive or off otherwise.
+ "Toggle auto-resizing temporary buffer windows (Temp Buffer Resize Mode).
+With a prefix argument ARG, enable Temp Buffer Resize mode if ARG
+is positive, and disable it otherwise. If called from Lisp,
+enable the mode if ARG is omitted or nil.
-This mode makes a window the right height for its contents, but
-never more than `temp-buffer-max-height' nor less than
-`window-min-height'.
+When Temp Buffer Resize mode is enabled, the windows in which we
+show a temporary buffer are automatically resized in height to
+fit the buffer's contents, but never more than
+`temp-buffer-max-height' nor less than `window-min-height'.
+
+A window is resized only if it has been specially created for the
+buffer. Windows that have shown another buffer before are not
+resized. A frame is resized only if `fit-frame-to-buffer' is
+non-nil.
This mode is used by `help', `apropos' and `completion' buffers,
and some others."
(add-hook 'temp-buffer-show-hook 'resize-temp-buffer-window 'append)
(remove-hook 'temp-buffer-show-hook 'resize-temp-buffer-window)))
-(defun resize-temp-buffer-window ()
- "Resize the selected window to fit its contents.
-Will not make it higher than `temp-buffer-max-height' nor smaller
-than `window-min-height'. Do nothing if the selected window is
-not vertically combined or some of its contents are scrolled out
-of view."
- (when (and (pos-visible-in-window-p (point-min))
- (window-iso-combined-p))
- (fit-window-to-buffer
- nil
- (if (functionp temp-buffer-max-height)
- (funcall temp-buffer-max-height (window-buffer))
- temp-buffer-max-height))))
+(defun resize-temp-buffer-window (&optional window)
+ "Resize WINDOW to fit its contents.
+WINDOW can be any live window and defaults to the selected one.
+
+Do not make WINDOW higher than `temp-buffer-max-height' nor
+smaller than `window-min-height'. Do nothing if WINDOW is not
+vertically combined, some of its contents are scrolled out of
+view, or WINDOW was not created by `display-buffer'."
+ (setq window (window-normalize-window window t))
+ (let ((buffer-name (buffer-name (window-buffer window))))
+ (let ((height (if (functionp temp-buffer-max-height)
+ (with-selected-window window
+ (funcall temp-buffer-max-height (window-buffer)))
+ temp-buffer-max-height))
+ (quit-cadr (cadr (window-parameter window 'quit-restore))))
+ (cond
+ ;; Resize WINDOW iff it was split off by `display-buffer'.
+ ((and (eq quit-cadr 'window)
+ (pos-visible-in-window-p (point-min) window)
+ (window-combined-p window))
+ (fit-window-to-buffer window height))
+ ;; Resize FRAME iff it was created by `display-buffer'.
+ ((and fit-frame-to-buffer
+ (eq quit-cadr 'frame)
+ (eq window (frame-root-window window)))
+ (let ((frame (window-frame window)))
+ (fit-frame-to-buffer
+ frame (+ (frame-height frame)
+ (- (window-total-size window))
+ height))))))))
;;; Help windows.
(defcustom help-window-select 'other
:group 'help
:version "23.1")
+(defcustom help-enable-auto-load t
+ "Whether Help commands can perform autoloading.
+If non-nil, whenever \\[describe-function] is called for an
+autoloaded function whose docstring contains any key substitution
+construct (see `substitute-command-keys'), the library is loaded,
+so that the documentation can show the right key bindings."
+ :type 'boolean
+ :group 'help
+ :version "24.3")
+
(defun help-window-display-message (quit-part window &optional scroll)
"Display message telling how to quit and scroll help window.
QUIT-PART is a string telling how to quit the help window WINDOW.
(message "%s"
(substitute-command-keys (concat quit-part scroll-part)))))
-(defun help-window-setup ()
+(defun help-window-setup (help-window)
"Set up help window for `with-help-window'.
-This relies on `display-buffer-window' being correctly set up by
-`display-buffer'."
- (let* ((help-window (car-safe display-buffer-window))
- (help-buffer (when (window-live-p help-window)
+HELP-WINDOW is the window used for displaying the help buffer."
+ (let* ((help-buffer (when (window-live-p help-window)
(window-buffer help-window)))
- (help-value (cdr-safe display-buffer-window)))
+ (help-setup (when (window-live-p help-window)
+ (car (window-parameter help-window 'quit-restore)))))
(when help-buffer
;; Handle `help-window-point-marker'.
(when (eq (marker-buffer help-window-point-marker) help-buffer)
(cond
((or (eq help-window (selected-window))
(and (or (eq help-window-select t)
+ (eq help-setup 'frame)
(and (eq help-window-select 'other)
(eq (window-frame help-window) (selected-frame))
(> (length (window-list nil 'no-mini)) 2)))
;; The help window is or gets selected ...
(help-window-display-message
(cond
- ((eq help-value 'new-window)
+ ((eq help-setup 'window)
;; ... and is new, ...
- "Type \"q\" to delete this window")
- ((eq help-value 'new-frame)
- ;; ... is on a new frame ...
- "Type \"q\" to delete this frame")
- ((eq help-value 'reuse-other-window)
+ "Type \"q\" to delete help window")
+ ((eq help-setup 'frame)
+ "Type \"q\" to delete help frame")
+ ((eq help-setup 'other)
;; ... or displayed some other buffer before.
"Type \"q\" to restore previous buffer"))
help-window t))
;; other one is the selected one.
(help-window-display-message
(cond
- ((eq help-value 'new-window)
+ ((eq help-setup 'window)
"Type \\[delete-other-windows] to delete the help window")
- ((eq help-value 'reuse-other-window)
- "Type \"q\" in other window to quit"))
+ ((eq help-setup 'other)
+ "Type \"q\" in help window to restore its previous buffer"))
help-window 'other))
(t
- ;; Not much to say here.
+ ;; The help window is not selected ...
(help-window-display-message
- "Type \"q\" in help window to quit" help-window))))))
+ (cond
+ ((eq help-setup 'window)
+ ;; ... and is new, ...
+ "Type \"q\" in help window to delete it")
+ ((eq help-setup 'other)
+ ;; ... or displayed some other buffer before.
+ "Type \"q\" in help window to restore previous buffer"))
+ help-window))))))
;; `with-help-window' is a wrapper for `with-output-to-temp-buffer'
;; providing the following additional twists:
(defmacro with-help-window (buffer-name &rest body)
"Display buffer with name BUFFER-NAME in a help window evaluating BODY.
Select help window if the actual value of the user option
-`help-window-select' says so. Return last value in BODY.
-
-You can specify where and how to show the buffer by binding the
-variable `temp-buffer-show-specifiers' to an appropriate value."
+`help-window-select' says so. Return last value in BODY."
(declare (indent 1) (debug t))
`(progn
- ;; Reset `display-buffer-window': `display-buffer' is
- ;; supposed to set this to the window displaying the buffer plus
- ;; some additional information.
- (setq display-buffer-window nil)
;; Make `help-window-point-marker' point nowhere. The only place
;; where this should be set to a buffer position is within BODY.
(set-marker help-window-point-marker nil)
- (prog1
- ;; Return value returned by `with-output-to-temp-buffer'.
- (with-output-to-temp-buffer ,buffer-name
- (progn ,@body))
- (when display-buffer-window (help-window-setup)))))
+ (let* (help-window
+ (temp-buffer-show-hook
+ (cons (lambda () (setq help-window (selected-window)))
+ temp-buffer-show-hook)))
+ ;; Return value returned by `with-output-to-temp-buffer'.
+ (prog1
+ (with-output-to-temp-buffer ,buffer-name
+ (progn ,@body))
+ (help-window-setup help-window)))))
;; Called from C, on encountering `help-char' when reading a char.
;; Don't print to *Help*; that would clobber Help history.