Describe recent frame and window changes in manuals

* doc/emacs/emacs.texi (Top):
* doc/emacs/cmdargs.texi (Borders X): Clearly separate the terms
"outer border" (for the X border which can be set from within
Emacs) and "external border" (for the border which is added by
the window manager).
* doc/lispref/display.texi (Tooltips): Clarify slightly.
* doc/lispref/elisp.texi (Top): Update node and section names.
* doc/lispref/frames.texi (Frames): Describe difference between
top-level and child frames.
(Frame Layout): Describe outer border.  Add more details about
how Emacs obtains the outer size and position of a frame and
about menu bar/tool bar wrapping.  Add references to new frame
parameters.
(Size and Position): Remove subsection.
(Frame Position): New subsection excerpted from the earlier Size
and Position subsection.  Clarify positioning concepts and
some of their shortcomings.  Describe `move-frame-functions'.
(Frame Size): New subsection excerpted from the earlier Size
and Position subsection.  Describe how to track frame size
changes and the new function `frame-size-changed-p'.
(Position Parameters): Describe child frame positioning.  Warn
about negative offsets.  Describe 'z-group' parameter.
(Size Parameters): Describe 'text-pixels' specification
facility and new 'min-width' and 'min-height' parameters.
(Layout Parameters): Clarify description of 'tool-bar-lines' and
'menu-bar-lines' parameters.
(Frame Interaction Parameters): New subsubsection describing
'parent-frame', 'delete-before', 'mouse-wheel-frame' and
'no-other-frame' parameters.
(Management Parameters): Describe 'skip-taskbar',
'no-focus-on-map', 'no-accept-focus', 'undecorated' and
'override-redirect' parameters.
(Deleting Frames): Describe handling of 'delete-before'
parameter and child frames for `delete-frame' and
`delete-other-frames'.
(Finding All Frames): Describe `frame-list-z-order' and handling
of 'no-other-frame' parameter by `next-frame'.
(Minibuffers and Frames): Minor clarifications.
(Input Focus): Document `x-focus-frame'.  Clarify descriptions
of `focus-in-hook', `focus-out-hook' and `focus-follows-mouse'.
(Visibility of Frames): Describe mapping and how the visibility
of a parent frame affects that of its child frames.
(Raising and Lowering): Describe restacking of frames and
z-groups.
(Child Frames): New section.
* doc/lispref/windows.texi (Selecting Windows): Describe
additional semantics of NORECORD argument of `select-window' and
how `buffer-list-update-hook' can emulate a "select window
hook".
(Mouse Window Auto-selection): New section.

doc/emacs/cmdargs.texi

@@ -71,7 +71,7 @@ arguments.)
 * Font X::              Choosing a font for text, under X.
 * Colors X::            Choosing display colors.
 * Window Size X::       Start-up window size, under X.
-* Borders X::           Internal and external borders, under X.
+* Borders X::           Internal and outer borders, under X.
 * Title X::             Specifying the initial frame's title.
 * Icons X::             Choosing what sort of icon to use, under X.
 * Misc X::              Other display options.
@@ -1053,15 +1053,15 @@ program-specified and user-specified positions.  If these are set,
 Emacs fails to position the window correctly.
 
 @node Borders X
-@appendixsec Internal and External Borders
+@appendixsec Internal and Outer Borders
 @cindex borders (X Window System)
 
-  An Emacs frame has an internal border and an external border.  The
+  An Emacs frame has an internal border and an outer border.  The
 internal border is an extra strip of the background color around the
-text portion of the frame.  Emacs itself draws the internal border.
-The external border is added by the window manager outside the frame;
-depending on the window manager you use, it may contain various boxes
-you can click on to move or iconify the window.
+text portion of the frame.  Emacs itself draws the internal border.  The
+outer border is drawn by X outside the tool and menu bars of the frame.
+There is also an external border which is drawn by the window manager.
+The size of the external border cannot be set from within Emacs.
 
 @table @samp
 @item -ib @var{width}
@@ -1069,15 +1069,15 @@ you can click on to move or iconify the window.
 @itemx --internal-border=@var{width}
 @opindex --internal-border
 @cindex internal border width, command-line argument
-Specify @var{width} as the width of the internal border (between the text
-and the main border), in pixels.
+Specify @var{width} as the width of the internal border (around the
+frame's text area), in pixels.
 
 @item -bw @var{width}
 @opindex -bw
 @itemx --border-width=@var{width}
 @opindex --border-width
 @cindex main border width, command-line argument
-Specify @var{width} as the width of the main border, in pixels.
+Specify @var{width} as the width of the outer border, in pixels.
 @end table
 
   When you specify the size of the frame, that does not count the
@@ -1086,9 +1086,9 @@ external border.
 
   Use the @samp{-ib @var{n}} option to specify an internal border
 @var{n} pixels wide.  The default is 1.  Use @samp{-bw @var{n}} to
-specify the width of the external border (though the window manager may
-not pay attention to what you specify).  The default width of the
-external border is 2.
+specify the width of the outer border (though the window manager may not
+pay attention to what you specify).  The default width of the outer
+border is 2.
 
 @node Title X
 @appendixsec Frame Titles

doc/emacs/emacs.texi

@@ -1198,7 +1198,7 @@ Command Line Arguments for Emacs Invocation
 * Font X::              Choosing a font for text, under X.
 * Colors X::            Choosing display colors.
 * Window Size X::       Start-up window size, under X.
-* Borders X::           Internal and external borders, under X.
+* Borders X::           Internal and outer borders, under X.
 * Title X::             Specifying the initial frame's title.
 * Icons X::             Choosing what sort of icon to use, under X.
 * Misc X::              Other display options.

doc/lispref/display.texi

@@ -7190,20 +7190,22 @@ changing the value of the variable @code{x-gtk-use-system-tooltips} to
 @code{nil}.  The rest of this subsection describes how to control
 non-GTK+ tooltips, which are presented by Emacs itself.
 
-Since tooltips are special frames, they have their frame parameters
-(@pxref{Frame Parameters}).  Unlike other frames, the frame parameters
-for tooltips are stored in a special variable.
+@cindex tooltip frames
+Tooltips are displayed in special frames called tooltip frames, which
+have their own frame parameters (@pxref{Frame Parameters}).  Unlike
+other frames, the default parameters for tooltip frames are stored in a
+special variable.
 
 @defvar tooltip-frame-parameters
-This customizable option holds the frame parameters used for
-displaying tooltips.  Any font and color parameters are ignored, and
-the corresponding attributes of the @code{tooltip} face are used
-instead.  If @code{left} or @code{top} parameters are included, they
-are used as absolute frame-relative coordinates where the tooltip
-should be shown.  (Mouse-relative position of the tooltip can be
-customized using the variables described in @ref{Tooltips,,, emacs,
-The GNU Emacs Manual}.)  Note that the @code{left} and @code{top}
-parameters, if present, override the values of mouse-relative offsets.
+This customizable option holds the default frame parameters used for
+displaying tooltips.  Any font and color parameters are ignored, and the
+corresponding attributes of the @code{tooltip} face are used instead.
+If @code{left} or @code{top} parameters are included, they are used as
+absolute frame-relative coordinates where the tooltip should be shown.
+(Mouse-relative position of the tooltip can be customized using the
+variables described in @ref{Tooltips,,, emacs, The GNU Emacs Manual}.)
+Note that the @code{left} and @code{top} parameters, if present,
+override the values of mouse-relative offsets.
 @end defvar
 
 @vindex tooltip@r{ face}

doc/lispref/elisp.texi

@@ -1062,6 +1062,7 @@ Windows
 * Vertical Scrolling::      Moving the contents up and down on the window.
 * Horizontal Scrolling::    Moving the contents sideways on the window.
 * Coordinates and Windows:: Converting coordinates to windows.
+* Mouse Window Auto-selection:: Automatically selecting windows with the mouse.
 * Window Configurations::   Saving and restoring the state of the screen.
 * Window Parameters::       Associating additional information with windows.
 * Window Hooks::            Hooks for scrolling, window size changes,
@@ -1089,16 +1090,16 @@ Frames
 * Minibuffers and Frames::  How a frame finds the minibuffer to use.
 * Input Focus::             Specifying the selected frame.
 * Visibility of Frames::    Frames may be visible or invisible, or icons.
-* Raising and Lowering::    Raising a frame makes it hide other windows;
-                              lowering it makes the others hide it.
+* Raising and Lowering::    Raising, Lowering and Restacking Frames.
 * Frame Configurations::    Saving the state of all frames.
+* Child Frames::            Making a frame the child of another.
 * Mouse Tracking::          Getting events that say when the mouse moves.
 * Mouse Position::          Asking where the mouse is, or moving it.
 * Pop-Up Menus::            Displaying a menu for the user to select from.
 * Dialog Boxes::            Displaying a box to ask yes or no.
 * Pointer Shape::           Specifying the shape of the mouse pointer.
 * Window System Selections::Transferring text to and from other X clients.
-* Drag and Drop::               Internals of Drag-and-Drop implementation.
+* Drag and Drop::           Internals of Drag-and-Drop implementation.
 * Color Names::             Getting the definitions of color names.
 * Text Terminal Colors::    Defining colors for text terminals.
 * Resources::               Getting resource values from the server.
@@ -1108,7 +1109,8 @@ Frame Geometry
 
 * Frame Layout::            Basic layout of frames.
 * Frame Font::              The default font of a frame and how to set it.
-* Size and Position::       Changing the size and position of a frame.
+* Frame Position::          The position of a frame on its display.
+* Frame Size::              Specifying and retrieving a frame's size.
 * Implied Frame Resizing::  Implied resizing of frames and how to prevent it.
 
 Frame Parameters
@@ -1126,6 +1128,8 @@ Window Frame Parameters
 * Layout Parameters::       Size of parts of the frame, and
                               enabling or disabling some parts.
 * Buffer Parameters::       Which buffers have been or should be shown.
+* Frame Interaction Parameters::  Parameters for interacting with other
+                              frames.
 * Management Parameters::   Communicating with the window manager.
 * Cursor Parameters::       Controlling the cursor appearance.
 * Font and Color Parameters:: Fonts and colors for the frame text.

doc/lispref/windows.texi

@@ -42,6 +42,7 @@ is displayed in windows.
 * Vertical Scrolling::      Moving the contents up and down on the window.
 * Horizontal Scrolling::    Moving the contents sideways on the window.
 * Coordinates and Windows:: Converting coordinates to windows.
+* Mouse Window Auto-selection:: Automatically selecting windows with the mouse.
 * Window Configurations::   Saving and restoring the state of the screen.
 * Window Parameters::       Associating additional information with windows.
 * Window Hooks::            Hooks for scrolling, window size changes,
@@ -763,7 +764,7 @@ changing the size of its frame.  Because live windows do not overlap,
 these functions are meaningful only on frames that contain two or more
 windows: resizing a window also changes the size of a neighboring
 window.  If there is just one window on a frame, its size cannot be
-changed except by resizing the frame (@pxref{Size and Position}).
+changed except by resizing the frame (@pxref{Frame Size}).
 
   Except where noted, these functions also accept internal windows as
 arguments.  Resizing an internal window causes its child windows to be
@@ -1016,7 +1017,7 @@ A window can get resized explicitly by using one of the functions from
 the preceding section or implicitly, for example, when resizing an
 adjacent window, when splitting or deleting a window (@pxref{Splitting
 Windows}, @pxref{Deleting Windows}) or when resizing the window's frame
-(@pxref{Size and Position}).
+(@pxref{Frame Size}).
 
   It is possible to avoid implicit resizing of a specific window when
 there are one or more other resizable windows on the same frame.  For
@@ -1716,23 +1717,47 @@ value of @code{window-point} (@pxref{Window Point}) in @var{window}.
 @var{window} must be a live window.  The return value is @var{window}.
 
 By default, this function also moves @var{window}'s buffer to the front
-of the buffer list (@pxref{Buffer List}), and makes @var{window} the
-most recently selected window.  However, if the optional argument
-@var{norecord} is non-@code{nil}, these additional actions are omitted.
+of the buffer list (@pxref{Buffer List}) and makes @var{window} the most
+recently selected window.  If the optional argument @var{norecord} is
+non-@code{nil}, these additional actions are omitted.
 
-This function runs @code{buffer-list-update-hook} (@pxref{Buffer List})
-unless @var{norecord} is non-@code{nil}.  Note that applications and
-internal routines often temporarily select a window in order to simplify
-coding.  As a rule, such selections (including those made by the macros
-@code{save-selected-window} and @code{with-selected-window} below) are
-not recorded thus avoiding to pollute @code{buffer-list-update-hook}.
-Selections that really count are those causing a visible change in
-the next redisplay of @var{window}'s frame and should be always
-recorded.  This also means that to run a function each time a window
-gets selected, putting it on @code{buffer-list-update-hook} should be
-the right choice.
+In addition, this function by default also tells the display engine to
+update the display of @var{window} when its frame gets redisplayed the
+next time.  If @var{norecord} is non-@code{nil}, such updates are
+usually not performed.  If, however, @var{norecord} equals the special
+symbol @code{mark-for-redisplay}, the additional actions mentioned above
+are omitted but @var{window} will be nevertheless updated.
 @end defun
 
+@cindex select window hook
+@cindex running a hook when a windows gets selected
+For historical reasons, Emacs does not run a separate hook whenever a
+window gets selected.  Applications and internal routines often
+temporarily select a window to perform a few actions on it.  They do
+that either to simplify coding---because many functions by default
+operate on the selected window when no @var{window} argument is
+specified---or because some functions did not (and still do not) take a
+window as argument and always operate(d) on the selected window instead.
+Running a hook every time a window gets selected for a short time and
+once more when the previously selected window gets restored is not
+useful.
+
+  However, when its @var{norecord} argument is @code{nil},
+@code{select-window} updates the buffer list and thus indirectly runs
+the normal hook @code{buffer-list-update-hook} (@pxref{Buffer List}).
+Consequently, that hook provides a reasonable way to run a function
+whenever a window gets selected more ``permanently''.
+
+  Since @code{buffer-list-update-hook} is also run by functions that are
+not related to window management, it will usually make sense to save the
+value of the selected window somewhere and compare it with the value of
+@code{selected-window} while running that hook.  Also, to avoid false
+positives when using @code{buffer-list-update-hook} it is good practice
+that every @code{select-window} call supposed to select a window only
+temporarily, passes a non-@code{nil} @var{norecord} argument.  If
+possible, the macro @code{with-selected-window} (see below) should be
+used in such cases.
+
 @cindex most recently selected windows
   The sequence of calls to @code{select-window} with a non-@code{nil}
 @var{norecord} argument determines an ordering of windows by their
@@ -1761,13 +1786,13 @@ the buffer list.
 
 @defmac with-selected-window window forms@dots{}
 This macro selects @var{window}, executes @var{forms} in sequence, then
-restores the previously selected window and current buffer.  The ordering
-of recently selected windows and the buffer list remain unchanged unless
-you deliberately change them within @var{forms}; for example, by calling
-@code{select-window} with argument @var{norecord} @code{nil}.
-
-This macro does not change the order of recently selected windows or
-the buffer list.
+restores the previously selected window and current buffer.  The
+ordering of recently selected windows and the buffer list remain
+unchanged unless you deliberately change them within @var{forms}; for
+example, by calling @code{select-window} with argument @var{norecord}
+@code{nil}.  Hence, this macro is the preferred way to temporarily work
+with @var{window} as the selected window without needlessly running
+@code{buffer-list-update-hook}.
 @end defmac
 
 @defun frame-selected-window &optional frame
@@ -4566,6 +4591,55 @@ point in the selected window, it's sufficient to write:
 @end defun
 
 
+@node Mouse Window Auto-selection
+@section Mouse Window Auto-selection
+@cindex window auto-selection
+@cindex auto-selection of window
+The following option allows to automatically select the window under the
+mouse pointer.  This accomplishes a policy similar to that of window
+managers that give focus to a frame (and thus trigger its subsequent
+selection) whenever the mouse pointer enters its window-system window
+(@pxref{Input Focus}).
+
+@defvar mouse-autoselect-window
+If this variable is non-@code{nil}, Emacs will try to automatically
+select the window under the mouse pointer.  The following values are
+meaningful:
+
+@table @asis
+@item A positive number
+This specifies a delay in seconds after which auto-selection triggers.
+The window under the mouse pointer is selected after the mouse has
+remained in it for the entire duration of the delay.
+
+@item A negative number
+A negative number has a similar effect as a positive number, but selects
+the window under the mouse pointer only after the mouse pointer has
+remained in it for the entire duration of the absolute value of that
+number and in addition has stopped moving.
+
+@item Other value
+Any other non-@code{nil} value means to select a window instantaneously
+as soon as the mouse pointer enters it.
+@end table
+
+In either case the mouse pointer must enter the text area of a window in
+order to trigger its selection.  Dragging the scroll bar slider or the
+mode line of a window conceptually should not cause its auto-selection.
+
+Mouse auto-selection selects the minibuffer window only if it is active,
+and never deselects the active minibuffer window.
+@end defvar
+
+Mouse auto-selection can be used to emulate a focus follows mouse policy
+for child frames (@pxref{Child Frames}) which usually are not tracked by
+the window manager.  This requires to set the value of
+@code{focus-follows-mouse} (@pxref{Input Focus}) to a non-@code{nil}
+value.  If the value of @code{focus-follows-mouse} is @code{auto-raise},
+entering a child frame with the mouse will raise it automatically above
+all other child frames of that frame's parent frame.
+
+
 @node Window Configurations
 @section Window Configurations
 @cindex window configurations