[Emacs-diffs] master 01827de: Update documentation of Temporary Displays.

[Martin Rudalics]

branch: master
commit 01827de4518c8da974821da0439f2ad4984d49da
Author: Martin Rudalics <address@hidden>
Commit: Martin Rudalics <address@hidden>

    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.
---
 doc/lispref/ChangeLog    |    8 ++++++
 doc/lispref/display.texi |   64 ++++++++++++++++++++++++++++++++++++++-------
 src/frame.c              |    2 +-
 3 files changed, 63 insertions(+), 11 deletions(-)

diff --git a/doc/lispref/ChangeLog b/doc/lispref/ChangeLog
index ad9af13..c9f576a 100644
--- a/doc/lispref/ChangeLog
+++ b/doc/lispref/ChangeLog
@@ -1,3 +1,11 @@
+2014-12-30  Martin Rudalics  <address@hidden>
+
+       * 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  <address@hidden>
 
        * control.texi (Pattern matching case statement):
diff --git a/doc/lispref/display.texi b/doc/lispref/display.texi
index e26d649..14a98f3 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}.
address@hidden 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
address@hidden  The final return value is then whatever
address@hidden returns.
address@hidden  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
address@hidden but differ from it as specified:
+
address@hidden 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
address@hidden
address@hidden defmac
+
address@hidden 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}.
address@hidden defmac
+
+A window showing a temporary buffer can be fit to the size of that
+buffer using the following mode:
+
address@hidden 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
address@hidden below.
address@hidden defopt
+
address@hidden 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.
address@hidden defopt
+
address@hidden 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.
address@hidden 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 2ad1c1b5..82a85bc 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