[Emacs-diffs] /srv/bzr/emacs/emacs-24 r110893: * display.texi (Temporary Displays): Document with-temp-buffer-window.

[Glenn Morris]

------------------------------------------------------------
revno: 110893
committer: Glenn Morris <address@hidden>
branch nick: emacs-24
timestamp: Fri 2012-11-16 21:29:58 -0500
message:
  * display.texi (Temporary Displays): Document with-temp-buffer-window.
  
  * etc/NEWS: Related edit.
modified:
  doc/lispref/ChangeLog
  doc/lispref/display.texi
  etc/NEWS

=== modified file 'doc/lispref/ChangeLog'
--- a/doc/lispref/ChangeLog     2012-11-17 01:33:26 +0000
+++ b/doc/lispref/ChangeLog     2012-11-17 02:29:58 +0000
@@ -1,5 +1,7 @@
 2012-11-17  Glenn Morris  <address@hidden>
 
+       * 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.

=== modified file 'doc/lispref/display.texi'
--- a/doc/lispref/display.texi  2012-11-15 07:30:46 +0000
+++ b/doc/lispref/display.texi  2012-11-17 02:29:58 +0000
@@ -1078,7 +1078,8 @@
 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 @@
 is current, and the window it was displayed in is selected.
 @end defvar
 
address@hidden with-temp-buffer-window buffer-or-name action quit-function 
address@hidden
+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
address@hidden 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.
+
address@hidden temp-buffer-window-setup-hook
address@hidden 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}.
address@hidden 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

=== modified file 'etc/NEWS'
--- a/etc/NEWS  2012-11-17 01:33:26 +0000
+++ b/etc/NEWS  2012-11-17 02:29:58 +0000
@@ -846,7 +846,9 @@
 +++
 *** 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