Document pixelwise frame resizing and fix related bug on Windows.

* w32term.c (x_set_window_size): When frame-resize-pixelwise is
nil, always resize character wise to avoid potential loss of the
mode line (Bug#16923 related).
* display.texi (Temporary Displays): Say that
with-temp-buffer-window makes its buffer current.
* frames.texi (Size and Position): Describe new option
`frame-resize-pixelwise'.  Rewrite descriptions of
`set-frame-size', `set-frame-height' and `set-frame-width'.

3 files changed, 59 insertions, 15 deletions

diff --git a/doc/lispref/ChangeLog b/doc/lispref/ChangeLog
index 274d9fa4fea..047a7c6f3b7 100644
--- a/doc/lispref/ChangeLog
+++ b/doc/lispref/ChangeLog
@@ -1,3 +1,11 @@
+2014-03-14  Martin Rudalics  <rudalics@gmx.at>
+
+        * display.texi (Temporary Displays): Say that
+        with-temp-buffer-window makes its buffer current.
+        * frames.texi (Size and Position): Describe new option
+        `frame-resize-pixelwise'.  Rewrite descriptions of
+        `set-frame-size', `set-frame-height' and `set-frame-width'.
+
 2014-03-09  Martin Rudalics  <rudalics@gmx.at>
 
         * elisp.texi (Top): Rename section "Width" to "Size of Displayed
diff --git a/doc/lispref/display.texi b/doc/lispref/display.texi
index bffb840bfeb..5037f0c9032 100644
--- a/doc/lispref/display.texi
+++ b/doc/lispref/display.texi
@@ -1175,12 +1175,11 @@ 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.
+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} and displays the
+buffer in some window.  Unlike @code{with-output-to-temp-buffer},
+however, this makes the buffer current and 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,
diff --git a/doc/lispref/frames.texi b/doc/lispref/frames.texi
index 206f14e751e..59881afb903 100644
--- a/doc/lispref/frames.texi
+++ b/doc/lispref/frames.texi
@@ -1147,21 +1147,46 @@ font.  If you don't supply @var{frame}, these functions use the selected
 frame.
 @end defun
 
-@defun set-frame-size frame cols rows
+@defopt frame-resize-pixelwise
+If this option is @code{nil}, a frame's size is usually rounded to a
+multiple of the current values of that frame's @code{frame-char-height}
+and @code{frame-char-width}.  If this is non-@code{nil}, no rounding
+occurs, hence frame sizes can increase/decrease by one pixel.
+
+Setting this causes the next resize operation to pass the corresponding
+size hints to the window manager.  This means that this variable should
+be set only in a user's initial file; applications should never bind it
+temporarily.
+
+The precise semantics of a value of @code{nil} for this option depends
+on the toolkit used: Dragging the frame border with the mouse is usually
+always done character-wise.  Calling @code{set-frame-size} (see below)
+with arguments that do not specify the frame size as an integer multiple
+of its character size may be, however, either ignored or cause a
+rounding (GTK+, Windows) or get accepted (Lucid, Motif).  This also
+means that with some toolkits and a display whose size is not an
+integral multiple of your default font, you may have to set this to
+non-@code{nil} in order to fully maximize a frame.
+@end defopt
+
+@defun set-frame-size frame width height pixelwise
 This function sets the size of @var{frame}, measured in characters;
-@var{cols} and @var{rows} specify the new width and height.
+@var{width} and @var{height} specify the new width in columns and the
+new height in lines.
 
-To set the size based on values measured in pixels, use
-@code{frame-char-height} and @code{frame-char-width} to convert
-them to units of characters.
+The optional argument @var{pixelwise} non-@code{nil} means to measure
+the new width and height in units of pixels instead.  Note that if
+@code{frame-resize-pixelwise} is @code{nil}, some toolkits may refuse to
+fully honor the request if it does not increase/decrease the frame size
+to a multiple of its character size.
 @end defun
 
-@defun set-frame-height frame lines &optional pretend
-This function resizes @var{frame} to a height of @var{lines} lines.  The
+@defun set-frame-height frame height &optional pretend pixelwise
+This function resizes @var{frame} to a height of @var{height} lines.  The
 sizes of existing windows in @var{frame} are altered proportionally to
 fit.
 
-If @var{pretend} is non-@code{nil}, then Emacs displays @var{lines}
+If @var{pretend} is non-@code{nil}, then Emacs displays @var{height}
 lines of output in @var{frame}, but does not change its value for the
 actual height of the frame.  This is only useful on text terminals.
 Using a smaller height than the terminal actually implements may be
@@ -1170,12 +1195,24 @@ terminal malfunctions when using its whole screen.  Setting the frame
 height ``for real'' does not always work, because knowing the correct
 actual size may be necessary for correct cursor positioning on
 text terminals.
+
+The optional fourth argument @var{pixelwise} non-@code{nil} means that
+@var{frame} should be @var{height} pixels high.  Note that if
+@code{frame-resize-pixelwise} is @code{nil}, some toolkits may refuse to
+fully honor the request if it does not increase/decrease the frame
+height to a multiple of its character height.
 @end defun
 
-@defun set-frame-width frame width &optional pretend
+@defun set-frame-width frame width &optional pretend pixelwise
 This function sets the width of @var{frame}, measured in characters.
 The argument @var{pretend} has the same meaning as in
 @code{set-frame-height}.
+
+The optional fourth argument @var{pixelwise} non-@code{nil} means that
+@var{frame} should be @var{width} pixels wide.  Note that if
+@code{frame-resize-pixelwise} is @code{nil}, some toolkits may refuse to
+fully honor the request if it does not increase/decrease the frame width
+to a multiple of its character width.
 @end defun
 
 @c FIXME?  Belongs more in Emacs manual than here?