1 files changed, 12 insertions, 13 deletions

diff --git a/lisp/window.el b/lisp/window.el
index 9ac3a4ecda0..486bb166fc1 100644
--- a/lisp/window.el
+++ b/lisp/window.el
@@ -147,12 +147,12 @@ to `display-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).
 
-Make sure the specified buffer is empty before evaluating BODY.
-Do not make that buffer current for BODY.  Instead, bind
-`standard-output' to that buffer, so that output generated with
-`prin1' and similar functions in BODY goes into that buffer.
+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.
 
-After evaluating BODY, this marks the specified buffer unmodified and
+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.
@@ -162,21 +162,20 @@ a function.  In that case, 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 the function specified by QUIT-FUNCTION selects the
-window showing the buffer before reading a value from the
-minibuffer; for example, when asking a `yes-or-no-p' question.
+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).
-
-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."
+\(with the specified buffer current and the window showing it selected)."
   (declare (debug t))
   (let ((buffer (make-symbol "buffer"))
         (window (make-symbol "window"))