X-Git-Url: https://code.delx.au/gnu-emacs/blobdiff_plain/5ed99d3685cc8d13f8e4c63ad449a6e4d63c8eb0..382936d1460c215c93fd2d8b9ae15b118fd1e90c:/lisp/help.el diff --git a/lisp/help.el b/lisp/help.el index 0c8d67106d..4219dd8698 100644 --- a/lisp/help.el +++ b/lisp/help.el @@ -1,7 +1,7 @@ ;;; 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 @@ -24,7 +24,7 @@ ;;; 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: @@ -37,23 +37,13 @@ (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.") @@ -157,10 +147,6 @@ specifies what to do when the user exits the help buffer." ;; 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)) @@ -600,6 +586,8 @@ temporarily enables it to allow getting help on disabled items and buttons." (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 @@ -795,7 +783,10 @@ descriptions of the minor modes, each on a separate page. 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) @@ -951,7 +942,7 @@ is currently activated with completion." (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)) @@ -974,27 +965,38 @@ is currently activated with completion." result)) ;;; 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. + +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'. -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'. +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." @@ -1005,19 +1007,36 @@ 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 @@ -1037,6 +1056,16 @@ by `with-help-window'" :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. @@ -1066,7 +1095,7 @@ 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) - (window-parameter help-window 'help-setup)))) + (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) @@ -1077,7 +1106,7 @@ HELP-WINDOW is the window used for displaying the help buffer." (cond ((or (eq help-window (selected-window)) (and (or (eq help-window-select t) - (eq help-setup 'new-frame) + (eq help-setup 'frame) (and (eq help-window-select 'other) (eq (window-frame help-window) (selected-frame)) (> (length (window-list nil 'no-mini)) 2))) @@ -1085,12 +1114,12 @@ HELP-WINDOW is the window used for displaying the help buffer." ;; The help window is or gets selected ... (help-window-display-message (cond - ((eq help-setup 'new-window) + ((eq help-setup 'window) ;; ... and is new, ... "Type \"q\" to delete help window") - ((eq help-setup 'new-frame) + ((eq help-setup 'frame) "Type \"q\" to delete help frame") - ((eq help-setup 'reuse-other) + ((eq help-setup 'other) ;; ... or displayed some other buffer before. "Type \"q\" to restore previous buffer")) help-window t)) @@ -1100,19 +1129,19 @@ HELP-WINDOW is the window used for displaying the help buffer." ;; other one is the selected one. (help-window-display-message (cond - ((eq help-setup 'new-window) + ((eq help-setup 'window) "Type \\[delete-other-windows] to delete the help window") - ((eq help-setup 'reuse-other) + ((eq help-setup 'other) "Type \"q\" in help window to restore its previous buffer")) help-window 'other)) (t ;; The help window is not selected ... (help-window-display-message (cond - ((eq help-setup 'new-window) + ((eq help-setup 'window) ;; ... and is new, ... "Type \"q\" in help window to delete it") - ((eq help-setup 'reuse-other) + ((eq help-setup 'other) ;; ... or displayed some other buffer before. "Type \"q\" in help window to restore previous buffer")) help-window)))))) @@ -1134,10 +1163,7 @@ HELP-WINDOW is the window used for displaying the help buffer." (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 ;; Make `help-window-point-marker' point nowhere. The only place