From 95f0501e74d997dab47ae043e78c9d147d0c7e89 Mon Sep 17 00:00:00 2001 From: Glenn Morris Date: Fri, 16 Nov 2012 21:03:58 -0500 Subject: [PATCH] Reword previous with-temp-buffer-window doc fixes * lisp/window.el (with-temp-buffer-window): Reword the doc to be more similar to with-output-to-temp-buffer. * lisp/subr.el (with-output-to-temp-buffer): Add doc xref to with-temp-buffer-window. --- lisp/ChangeLog | 2 ++ lisp/subr.el | 5 ++++- lisp/window.el | 44 +++++++++++++++++++++++++------------------- 3 files changed, 31 insertions(+), 20 deletions(-) diff --git a/lisp/ChangeLog b/lisp/ChangeLog index e67bc5b556c..64075665bab 100644 --- a/lisp/ChangeLog +++ b/lisp/ChangeLog @@ -5,6 +5,8 @@ Use set-face-underline rather than the alias set-face-underline-p. * window.el (with-temp-buffer-window): Doc fix. + * subr.el (with-output-to-temp-buffer): + Add doc xref to with-temp-buffer-window. 2012-11-16 Stefan Monnier diff --git a/lisp/subr.el b/lisp/subr.el index bb142e8680f..2088c7887b3 100644 --- a/lisp/subr.el +++ b/lisp/subr.el @@ -3188,6 +3188,7 @@ in which case `save-window-excursion' cannot help." ;; Return nil. nil) +;; Doc is very similar to with-temp-buffer-window. (defmacro with-output-to-temp-buffer (bufname &rest body) "Bind `standard-output' to buffer BUFNAME, eval BODY, then show that buffer. @@ -3213,7 +3214,9 @@ with the buffer BUFNAME temporarily current. It runs the hook `temp-buffer-show-hook' after displaying buffer BUFNAME, with that buffer temporarily current, and the window that was used to display it temporarily selected. But it doesn't run `temp-buffer-show-hook' -if it uses `temp-buffer-show-function'." +if it uses `temp-buffer-show-function'. + +See the related form `with-temp-buffer-window'." (declare (debug t)) (let ((old-dir (make-symbol "old-dir")) (buf (make-symbol "buf"))) diff --git a/lisp/window.el b/lisp/window.el index 486bb166fc1..d378ea5ff14 100644 --- a/lisp/window.el +++ b/lisp/window.el @@ -142,40 +142,46 @@ to `display-buffer'." ;; Return the window. window)))) +;; Doc is very similar to with-output-to-temp-buffer. (defmacro with-temp-buffer-window (buffer-or-name action quit-function &rest body) - "Evaluate BODY and display the buffer specified by BUFFER-OR-NAME. + "Bind `standard-output' to BUFFER-OR-NAME, eval BODY, show the buffer. BUFFER-OR-NAME must specify either a live buffer, or the name of a buffer (if it does not exist, this macro creates it). -This first empties the specified buffer. It does not make the -buffer current, but rather binds `standard-output', so that -output generated with `prin1' and similar functions in BODY goes -into the buffer. +This construct makes buffer BUFFER-OR-NAME empty before running BODY. +It does not make the buffer current for BODY. +Instead it binds `standard-output' to that buffer, so that output +generated with `prin1' and similar functions in BODY goes into +the buffer. -After evaluating BODY, it marks the specified buffer unmodified and -read-only, and displays it in a window via `display-buffer', passing -ACTION as the action argument to `display-buffer'. It automatically -shrinks the relevant window if `temp-buffer-resize-mode' is enabled. +At the end of BODY, this marks the specified buffer unmodified and +read-only, and displays it in a window (but does not select it, or make +the buffer current). The display happens by calling `display-buffer' +with the ACTION argument. If `temp-buffer-resize-mode' is enabled, +the relevant window shrinks automatically. -Returns the value returned by BODY, unless QUIT-FUNCTION specifies -a function. In that case, runs the function with two arguments - +This returns the value returned by BODY, unless QUIT-FUNCTION specifies +a function. In that case, it runs the function with two arguments - the window showing the specified buffer and the value returned by BODY - and returns the value returned by that function. -Since this macro calls `display-buffer', the window displaying -the buffer is usually not selected and the specified buffer -usually not made current. QUIT-FUNCTION can override that. If the buffer is displayed on a new frame, the window manager may decide to select that frame. In that case, it's usually a good strategy if QUIT-FUNCTION selects the window showing the buffer before reading any value from the minibuffer; for example, when asking a `yes-or-no-p' question. -This construct is similar to `with-output-to-temp-buffer', but does -not put the buffer in help mode, or call `temp-buffer-show-function'. -It also runs different hooks, namely `temp-buffer-window-setup-hook' -\(with the specified buffer current) and `temp-buffer-window-show-hook' -\(with the specified buffer current and the window showing it selected)." +This runs the hook `temp-buffer-window-setup-hook' before BODY, +with the specified buffer temporarily current. It runs the +hook `temp-buffer-window-show-hook' after displaying the buffer, +with that buffer temporarily current, and the window that was used to +display it temporarily selected. + +This construct is similar to `with-output-to-temp-buffer', but +runs different hooks. In particular, it does not run +`temp-buffer-setup-hook', which usually puts the buffer in Help mode. +Also, it does not call `temp-buffer-show-function' (the ACTION +argument replaces this)." (declare (debug t)) (let ((buffer (make-symbol "buffer")) (window (make-symbol "window")) -- 2.11.4.GIT