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.

1 files changed, 33 insertions, 26 deletions

diff --git a/doc/lispref/frames.texi b/doc/lispref/frames.texi
index f7dfb51dd42..81a3dc660cd 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