;;; help.el --- help commands for Emacs
-;; Copyright (C) 1985-1986, 1993-1994, 1998-2012 Free Software Foundation, Inc.
+;; Copyright (C) 1985-1986, 1993-1994, 1998-2014 Free Software
+;; Foundation, Inc.
;; Maintainer: FSF
;; Keywords: help, internal
;; `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))
including their special commands.
n Display news of recent Emacs changes.
p TOPIC Find packages matching a given topic keyword.
+P PACKAGE Describe the given Emacs Lisp package.
r Display the Emacs manual in Info mode.
s Display contents of current syntax table, plus explanations.
S SYMBOL Show the section for the given symbol in the on-line manual
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 (messages-buffer)
+ (goto-char (point-max))
+ (display-buffer (current-buffer))))
(defun view-order-manuals ()
- "Display the Emacs ORDERS file."
+ "Display information on how to buy printed copies of Emacs manuals."
(interactive)
- (view-help-file "ORDERS"))
+;; (view-help-file "ORDERS")
+ (info "(emacs)Printed Books"))
(defun view-emacs-FAQ ()
"Display the Emacs Frequently Asked Questions (FAQ) file."
(interactive)
(view-help-file "DEBUG"))
+;; This used to visit MORE.STUFF; maybe it should just be removed.
(defun view-external-packages ()
- "Display external packages and information about Emacs."
+ "Display info on where to get more Emacs packages."
(interactive)
- (view-help-file "MORE.STUFF"))
+ (info "(efaq)Packages that do not come with Emacs"))
(defun view-lossage ()
"Display last 300 input keystrokes.
The optional argument PREFIX, if non-nil, should be a key sequence;
then we display only bindings that start with that prefix."
(let ((buf (current-buffer)))
- (with-help-window "*Help*"
- (with-current-buffer standard-output
- (describe-buffer-bindings buf prefix menus)))))
+ (with-help-window (help-buffer)
+ (describe-buffer-bindings buf prefix menus))))
(defun where-is (definition &optional insert)
"Print message listing key sequences that invoke the command DEFINITION.
(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
(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
function is called, the window to be resized is selected."
:type '(choice integer function)
:group 'help
- :version "20.4")
+ :version "24.3")
+
+(defcustom temp-buffer-max-width
+ (lambda (buffer)
+ (if (eq (selected-window) (frame-root-window))
+ (/ (x-display-pixel-width) (frame-char-width) 2)
+ (/ (- (frame-width) 2) 2)))
+ "Maximum width of a window displaying a temporary buffer.
+This is effective only when Temp Buffer Resize mode is enabled.
+The value is the maximum width (in columns) 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 width 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 "24.4")
(define-minor-mode temp-buffer-resize-mode
- "Toggle auto-shrinking temp buffer windows (Temp Buffer Resize mode).
+ "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.
When Temp Buffer Resize mode is enabled, the windows in which we
-show a temporary buffer are automatically reduced in height to
+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."
:global t :group 'help
(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-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 must be a live window and defaults to the selected one.
+Do not resize if WINDOW was not created by `display-buffer'.
+
+If WINDOW is part of a vertical combination, restrain its new
+size by `temp-buffer-max-height' and do not resize if its minimum
+accessible position is scrolled out of view. If WINDOW is part
+of a horizontal combination, restrain its new size by
+`temp-buffer-max-width'. In both cases, the value of the option
+`fit-window-to-buffer-horizontally' can inhibit resizing.
+
+If WINDOW is the root window of its frame, resize the frame
+provided `fit-frame-to-buffer' is non-nil."
+ (setq window (window-normalize-window window t))
+ (let ((height (if (functionp temp-buffer-max-height)
+ (with-selected-window window
+ (funcall temp-buffer-max-height (window-buffer)))
+ temp-buffer-max-height))
+ (width (if (functionp temp-buffer-max-width)
+ (with-selected-window window
+ (funcall temp-buffer-max-width (window-buffer)))
+ temp-buffer-max-width))
+ (quit-cadr (cadr (window-parameter window 'quit-restore))))
+ ;; Resize WINDOW iff it was made by `display-buffer'.
+ (when (or (and (eq quit-cadr 'window)
+ (or (and (window-combined-p window)
+ (not (eq fit-window-to-buffer-horizontally
+ 'only))
+ (pos-visible-in-window-p (point-min) window))
+ (and (window-combined-p window t)
+ fit-window-to-buffer-horizontally)))
+ (and (eq quit-cadr 'frame)
+ fit-frame-to-buffer
+ (eq window (frame-root-window window))))
+ (fit-window-to-buffer window height nil width))))
;;; 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 (help-window)
- "Set up help window for `with-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-setup (when (window-live-p help-window)
- (car (window-parameter help-window 'quit-restore)))))
+(defun help-window-setup (window &optional value)
+ "Set up help window WINDOW for `with-help-window'.
+WINDOW is the window used for displaying the help buffer.
+Return VALUE."
+ (let* ((help-buffer (when (window-live-p window)
+ (window-buffer window)))
+ (help-setup (when (window-live-p window)
+ (car (window-parameter window 'quit-restore)))))
(when help-buffer
;; Handle `help-window-point-marker'.
(when (eq (marker-buffer help-window-point-marker) help-buffer)
- (set-window-point help-window help-window-point-marker)
+ (set-window-point window help-window-point-marker)
;; Reset `help-window-point-marker'.
(set-marker help-window-point-marker nil))
(cond
- ((or (eq help-window (selected-window))
+ ((or (eq 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))
+ (eq (window-frame window) (selected-frame))
(> (length (window-list nil 'no-mini)) 2)))
- (select-window help-window)))
+ (select-window window)))
;; The help window is or gets selected ...
(help-window-display-message
(cond
;; ... and is new, ...
"Type \"q\" to delete help window")
((eq help-setup 'frame)
- "Type \"q\" to delete help frame")
+ "Type \"q\" to quit the help frame")
((eq help-setup 'other)
;; ... or displayed some other buffer before.
"Type \"q\" to restore previous buffer"))
- help-window t))
- ((and (eq (window-frame help-window) (selected-frame))
+ window t))
+ ((and (eq (window-frame window) (selected-frame))
(= (length (window-list nil 'no-mini)) 2))
;; There are two windows on the help window's frame and the
;; other one is the selected one.
"Type \\[delete-other-windows] to delete the help window")
((eq help-setup 'other)
"Type \"q\" in help window to restore its previous buffer"))
- help-window 'other))
+ window 'other))
(t
;; The help window is not selected ...
(help-window-display-message
((eq help-setup 'other)
;; ... or displayed some other buffer before.
"Type \"q\" in help window to restore previous buffer"))
- help-window))))))
+ window))))
+ ;; Return VALUE.
+ value))
-;; `with-help-window' is a wrapper for `with-output-to-temp-buffer'
+;; `with-help-window' is a wrapper for `with-temp-buffer-window'
;; providing the following additional twists:
-;; (1) Issue more accurate messages telling how to scroll and quit the
-;; help window.
+;; (1) It puts the buffer in `help-mode' (via `help-mode-setup') and
+;; adds cross references (via `help-mode-finish').
+
+;; (2) It issues a message telling how to scroll and quit the help
+;; window (via `help-window-setup').
-;; (2) An option (customizable via `help-window-select') to select the
+;; (3) An option (customizable via `help-window-select') to select the
;; help window automatically.
-;; (3) A marker (`help-window-point-marker') to move point in the help
+;; (4) A marker (`help-window-point-marker') to move point in the help
;; window to an arbitrary buffer position.
;; Note: It's usually always wrong to use `help-print-return-message' in
;; the body of `with-help-window'.
(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
+Select help window if the current value of the user option
`help-window-select' says so. Return last value in BODY."
(declare (indent 1) (debug t))
`(progn
;; 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)
- (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)))))
+ (let ((temp-buffer-window-setup-hook
+ (cons 'help-mode-setup temp-buffer-window-setup-hook))
+ (temp-buffer-window-show-hook
+ (cons 'help-mode-finish temp-buffer-window-show-hook)))
+ (with-temp-buffer-window
+ ,buffer-name nil 'help-window-setup (progn ,@body)))))
;; Called from C, on encountering `help-char' when reading a char.
;; Don't print to *Help*; that would clobber Help history.