master 1e75853: Fix documentation of implied frame resizing (Bug#38684)

[Martin Rudalics]

branch: master
commit 1e758530b06befc6feb44031b9f84734e2165e2e
Author: Martin Rudalics <address@hidden>
Commit: Martin Rudalics <address@hidden>

    Fix documentation of implied frame resizing (Bug#38684)
    
    * src/frame.c (frame_inhibit_implied_resize): Fix doc-string.
    * doc/lispref/frames.texi (Implied Frame Resizing): Update and
    rewrite section.
---
 doc/lispref/frames.texi | 59 +++++++++++++++++++++++++++----------------------
 src/frame.c             | 10 ++++-----
 2 files changed, 38 insertions(+), 31 deletions(-)

diff --git a/doc/lispref/frames.texi b/doc/lispref/frames.texi
index f7dfb51..81a3dc6 100644
--- a/doc/lispref/frames.texi
+++ b/doc/lispref/frames.texi
@@ -1166,30 +1166,27 @@ immediately after running 
@code{window-size-change-functions} for
 @cindex implied resizing of frame
 
 By default, Emacs tries to keep the number of lines and columns of a
-frame's text area unaltered when, for example, adding or removing the
-menu bar, changing the default font or setting the width of the frame's
-scroll bars.  This means, however, that in such case Emacs must ask the
-window manager to resize the outer frame in order to accommodate the
-size change.  Note that wrapping a menu or tool bar usually does not
-resize the frame's outer size, hence this will alter the number of
-displayed lines.
+frame's text area unaltered when, for example, toggling its menu or
+tool bar, changing its default font or setting the width of any of its
+scroll bars.  This means that in such case Emacs must ask the window
+manager to resize the frame's window in order to accommodate the size
+change.
 
   Occasionally, such @dfn{implied frame resizing} may be unwanted, for
-example, when the frame is maximized or made full-screen (where it's
-turned off by default).  In other cases you can disable implied resizing
-with the following option:
+example, when a frame has been maximized or made full-screen (where
+it's turned off by default).  In general, users can disable implied
+resizing with the following option:
 
 @defopt frame-inhibit-implied-resize
-If this option is @code{nil}, changing font, menu bar, tool bar,
-internal borders, fringes or scroll bars of a specific frame may
-implicitly resize the frame's display area in order to preserve the
-number of columns or lines the frame displays.  If this option is
-non-@code{nil}, no implied resizing is done.
+If this option is @code{nil}, changing a frame's font, menu bar, tool
+bar, internal borders, fringes or scroll bars may resize its outer
+frame in order to keep the number of columns or lines of its text area
+unaltered.  If this option is @code{t}, no such resizing is done.
 
 The value of this option can be also a list of frame parameters.  In
-that case, implied resizing is inhibited when changing a parameter that
-appears in this list.  The frame parameters currently handled by this
-option are: @code{font}, @code{font-backend},
+that case, implied resizing is inhibited for the change of a parameter
+that appears in this list.  Parameters currently handled by this
+option are @code{font}, @code{font-backend},
 @code{internal-border-width}, @code{menu-bar-lines} and
 @code{tool-bar-lines}.
 
@@ -1200,20 +1197,30 @@ as if the frame contained just one live window.  This 
means, for
 example, that removing vertical scroll bars on a frame containing
 several side by side windows will shrink the outer frame width by the
 width of one scroll bar provided this option is @code{nil} and keep it
-unchanged if this option is either @code{t} or a list containing
+unchanged if this option is @code{t} or a list containing
 @code{vertical-scroll-bars}.
 
-The default value is @code{'(tool-bar-lines)} for Lucid, Motif and
-MS-Windows (which means that adding/removing a tool bar there does not
-change the outer frame height), @code{nil} on all other window systems
-including GTK+ (which means that changing any of the parameters listed
-above may change the size of the outer frame), and @code{t} otherwise
-(which means the outer frame size never changes implicitly when there's
-no window system support).
+The default value is @code{'(tab-bar-lines tool-bar-lines)} for Lucid,
+Motif and MS-Windows (which means that adding/removing a tool or tab
+bar there does not change the outer frame height),
+@code{'(tab-bar-lines)} on all other window systems including GTK+
+(which means that changing any of the parameters listed above with the
+exception of @code{tab-bar-lines} may change the size of the outer
+frame), and @code{t} otherwise (which means the outer frame size never
+changes implicitly when there's no window system support).
 
 Note that when a frame is not large enough to accommodate a change of
 any of the parameters listed above, Emacs may try to enlarge the frame
 even if this option is non-@code{nil}.
+
+Note also that window managers usually do not ask for resizing a frame
+when they change the number of lines occupied by an external menu or
+tool bar.  Typically, such ``wrappings'' occur when a user shrinks a
+frame horizontally, making it impossible to display all elements of
+its menu or tool bar.  They may also result from a change of the major
+mode altering the number of items of a menu or tool bar.  Any such
+wrappings may implicitly alter the number of lines of a frame's text
+area and are unaffected by the setting of this option.
 @end defopt
 
 
diff --git a/src/frame.c b/src/frame.c
index df4c98c..0ab9613 100644
--- a/src/frame.c
+++ b/src/frame.c
@@ -6272,11 +6272,11 @@ this option is t, no such resizing is done.  Note that 
the size of
 fullscreen and maximized frames, the height of fullheight frames and the
 width of fullwidth frames never change implicitly.
 
-The value of this option can be also be a list of frame parameters.  In
-this case, resizing is inhibited when changing a parameter that appears
-in that list.  The parameters currently handled by this option include
-`font', `font-backend', `internal-border-width', `menu-bar-lines',
-`tool-bar-lines' and `tab-bar-lines'.
+The value of this option can be also a list of frame parameters.  In
+this case, resizing is inhibited when changing a parameter that
+appears in that list.  The parameters currently handled by this option
+include `font', `font-backend', `internal-border-width',
+`menu-bar-lines', `tool-bar-lines' and `tab-bar-lines'.
 
 Changing any of the parameters `scroll-bar-width', `scroll-bar-height',
 `vertical-scroll-bars', `horizontal-scroll-bars', `left-fringe' and