Update documentation of Temporary Displays.

* display.texi (Temporary Displays): Amend description of
`with-temp-buffer-window'.  Add descriptions for
`with-current-buffer-window', `with-displayed-buffer-window' and
`temp-buffer-resize-mode', `temp-buffer-max-height' and
`temp-buffer-max-width'.

* frame.c (frame_inhibit_implied_resize): Escape left paren in
doc-string.

3 files changed, 63 insertions, 11 deletions

diff --git a/doc/lispref/ChangeLog b/doc/lispref/ChangeLog
index ad9af13488e..c9f576af5e6 100644
--- a/doc/lispref/ChangeLog
+++ b/doc/lispref/ChangeLog
@@ -1,3 +1,11 @@
+2014-12-30  Martin Rudalics  <rudalics@gmx.at>
+
+        * display.texi (Temporary Displays): Amend description of
+        `with-temp-buffer-window'.  Add descriptions for
+        `with-current-buffer-window', `with-displayed-buffer-window' and
+        `temp-buffer-resize-mode', `temp-buffer-max-height' and
+        `temp-buffer-max-width'.
+
 2014-12-27  Glenn Morris  <rgm@gnu.org>
 
         * control.texi (Pattern matching case statement):
diff --git a/doc/lispref/display.texi b/doc/lispref/display.texi
index e26d6491850..14a98f32ffb 100644
--- a/doc/lispref/display.texi
+++ b/doc/lispref/display.texi
@@ -1194,12 +1194,6 @@ it prints into the buffer named @var{buffer-or-name} and displays that
 buffer in some window.  Unlike @code{with-output-to-temp-buffer},
 however, it does not automatically switch that buffer to Help mode.
 
-Like @code{with-output-to-temp-buffer} it neither makes the buffer
-specified by @var{buffer-or-name} current when executing @var{body}.
-@findex with-current-buffer-window
-The otherwise identical macro @code{with-current-buffer-window} can be
-used to execute @var{body} with that buffer current.
-
 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
@@ -1207,14 +1201,14 @@ 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.
+passes the @var{action} argument to @code{display-buffer}
+(@pxref{Choosing Window}) in order to display the buffer.
 
 The value of the last form in @var{body} 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{body}.  The final return value is then whatever
-@var{quit-function} returns.
+@var{body}.  The final return value is then whatever @var{quit-function}
+returns.
 
 @vindex temp-buffer-window-setup-hook
 @vindex temp-buffer-window-show-hook
@@ -1223,6 +1217,56 @@ and @code{temp-buffer-window-show-hook} in place of the analogous hooks
 run by @code{with-output-to-temp-buffer}.
 @end defmac
 
+The two constructs described next are mostly identical to
+@code{with-temp-buffer-window} but differ from it as specified:
+
+@defmac with-current-buffer-window buffer-or-name action quit-function &rest body
+This macro is like @code{with-temp-buffer-window} but unlike that makes
+the buffer specified by @var{buffer-or-name} current for running
+@var{body}.
+@end defmac
+
+@defmac with-displayed-buffer-window buffer-or-name action quit-function &rest body
+This macro is like @code{with-current-buffer-window} but unlike that
+displays the buffer specified by @var{buffer-or-name} @emph{before}
+running @var{body}.
+@end defmac
+
+A window showing a temporary buffer can be fit to the size of that
+buffer using the following mode:
+
+@defopt temp-buffer-resize-mode
+When this minor mode is enabled, windows showing a temporary buffer are
+automatically resized to fit their buffer's contents.
+
+A window is resized if and only if it has been specially created for the
+buffer.  In particular, windows that have shown another buffer before
+are not resized.  By default, this mode uses @code{fit-window-to-buffer}
+(@pxref{Resizing Windows}) for resizing.  You can specify a different
+function by customizing the options @code{temp-buffer-max-height} and
+@code{temp-buffer-max-width} below.
+@end defopt
+
+@defopt temp-buffer-max-height
+This option specifies the maximum height (in lines) of a window
+displaying a temporary buffer when @code{temp-buffer-resize-mode} is
+enabled.  It can also be a function to be called to 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.
+@end defopt
+
+@defopt temp-buffer-max-width
+This option specifies the maximum width of a window (in columns)
+displaying a temporary buffer when @code{temp-buffer-resize-mode} is
+enabled.  It can also be a function to be called to choose the width 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.
+@end defopt
+
+The following function uses the current buffer for temporal display:
+
 @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/src/frame.c b/src/frame.c
index 2ad1c1b52b7..82a85bc48e6 100644
--- a/src/frame.c
+++ b/src/frame.c
@@ -5057,7 +5057,7 @@ keep it unchanged if this option is either `t' or a list containing
 `vertical-scroll-bars'.
 
 The default value is '(tool-bar-lines) on Lucid, Motif and Windows
-(which means that adding/removing a tool bar does not change the frame
+\(which means that adding/removing a tool bar does not change the frame
 height), nil on all other window systems including GTK+ (which means
 that changing any of the parameters listed above may change the size of
 the frame), and `t' otherwise (which means the frame size never changes