* display.texi (Temporary Displays): Document with-temp-buffer-window.

* etc/NEWS: Related edit.

3 files changed, 38 insertions, 2 deletions

diff --git a/doc/lispref/ChangeLog b/doc/lispref/ChangeLog
index b7baac9c2fe..6726c6d2ad0 100644
--- a/doc/lispref/ChangeLog
+++ b/doc/lispref/ChangeLog
@@ -1,5 +1,7 @@
 2012-11-17  Glenn Morris  <rgm@gnu.org>
 
+        * display.texi (Temporary Displays): Document with-temp-buffer-window.
+
         * frames.texi (Size and Position): Add fit-frame-to-buffer command.
         * windows.texi (Resizing Windows): Add fit-frame-to-buffer option.
         (Window Sizes): Add vindex for window-min-height, window-min-width.
diff --git a/doc/lispref/display.texi b/doc/lispref/display.texi
index 9fedd162da6..475a9550f99 100644
--- a/doc/lispref/display.texi
+++ b/doc/lispref/display.texi
@@ -1078,7 +1078,8 @@ editing.  Many help commands use this feature.
 This function executes @var{forms} while arranging to insert any output
 they print into the buffer named @var{buffer-name}, which is first
 created if necessary, and put into Help mode.  Finally, the buffer is
-displayed in some window, but not selected.
+displayed in some window, but not selected.  (See the similar
+form @code{with-temp-buffer-window} below.)
 
 If the @var{forms} do not change the major mode in the output buffer,
 so that it is still Help mode at the end of their execution, then
@@ -1152,6 +1153,37 @@ displaying the temporary buffer.  When the hook runs, the temporary buffer
 is current, and the window it was displayed in is selected.
 @end defvar
 
+@defmac with-temp-buffer-window buffer-or-name action quit-function forms@dots{}
+This macro is similar to @code{with-output-to-temp-buffer}.
+Like that construct, it executes @var{forms} while arranging to insert
+any output they print into the buffer named @var{buffer-or-name}.
+Finally, the buffer is displayed in some window, but not selected.
+Unlike @code{with-output-to-temp-buffer}, this does not switch to Help
+mode.
+
+The argument @var{buffer-or-name} specifies the temporary buffer.
+It can be either a buffer, which must already exist, or a string,
+in which case a buffer of that name is created if necessary.
+The buffer is marked as unmodified and read-only when
+@code{with-temp-buffer-window} exits.
+
+This macro does not call @code{temp-buffer-show-function}.  Rather, it
+passes the @var{action} argument to @code{display-buffer} in order to
+display the buffer.
+
+The value of the last form in @var{forms} is returned, unless the
+argument @var{quit-function} is specified.  In that case,
+it is called with two arguments: the window showing the buffer
+and the result of @var{forms}.  The final return value is then
+whatever @var{quit-function} returns.
+
+@vindex temp-buffer-window-setup-hook
+@vindex temp-buffer-window-show-hook
+This macro uses the normal hooks @code{temp-buffer-window-setup-hook}
+and @code{temp-buffer-window-show-hook} in place of the analogous hooks
+run by @code{with-output-to-temp-buffer}.
+@end defmac
+
 @defun momentary-string-display string position &optional char message
 This function momentarily displays @var{string} in the current buffer at
 @var{position}.  It has no effect on the undo list or on the buffer's
diff --git a/etc/NEWS b/etc/NEWS
index a951677bd1d..d040ba7ddf8 100644
--- a/etc/NEWS
+++ b/etc/NEWS
@@ -846,7 +846,9 @@ now accept a third argument to avoid choosing the selected window.
 +++
 *** Additional values recognized for option `window-combination-limit'.
 
-*** New macro `with-temp-buffer-window'.
++++
+*** New macro `with-temp-buffer-window', similar to
+`with-output-to-temp-buffer'.
 
 ---
 *** `temp-buffer-resize-mode' no longer resizes windows that have been