From 7cc613dc68b8c388a7ccd8f79e37a641ad05312c Mon Sep 17 00:00:00 2001
From: Martin Rudalics <rudalics@gmx.at>
Date: Thu, 13 Apr 2017 17:45:12 +0200
Subject: [PATCH] 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   |   26 +-
 doc/emacs/emacs.texi     |    2 +-
 doc/lispref/display.texi |   26 +-
 doc/lispref/elisp.texi   |   12 +-
 doc/lispref/frames.texi  | 1091 ++++++++++++++++++++++++++++++--------
 doc/lispref/windows.texi |  122 ++++-
 6 files changed, 997 insertions(+), 282 deletions(-)

diff --git a/doc/emacs/cmdargs.texi b/doc/emacs/cmdargs.texi
index 6c866708245..721a2cebb22 100644
--- a/doc/emacs/cmdargs.texi
+++ b/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
diff --git a/doc/emacs/emacs.texi b/doc/emacs/emacs.texi
index a6f2896231b..599b373fd4c 100644
--- a/doc/emacs/emacs.texi
+++ b/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.
diff --git a/doc/lispref/display.texi b/doc/lispref/display.texi
index 57dd16decaf..7a6a21649e4 100644
--- a/doc/lispref/display.texi
+++ b/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}
diff --git a/doc/lispref/elisp.texi b/doc/lispref/elisp.texi
index bff3112d73b..7cc91a8f7e3 100644
--- a/doc/lispref/elisp.texi
+++ b/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.
diff --git a/doc/lispref/frames.texi b/doc/lispref/frames.texi
index 68aa40fe4dd..2fac8020ffb 100644
--- a/doc/lispref/frames.texi
+++ b/doc/lispref/frames.texi
@@ -77,6 +77,13 @@ displayed on that terminal; the list of possible values is the same as
 for @code{framep} above.
 @end defun
 
+@cindex top-level frame
+On a graphical terminal we distinguish two types of frames: A normal
+@dfn{top-level frame} is a frame whose window-system window is a child
+of the window-system's root window for that terminal.  A child frame is
+a frame whose window-system window is the child of the window-system
+window of another Emacs frame.  @xref{Child Frames}.
+
 @menu
 * Creating Frames::             Creating additional frames.
 * Multiple Terminals::          Displaying on several different devices.
@@ -89,9 +96,9 @@ for @code{framep} above.
 * 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.
@@ -436,7 +443,8 @@ has to specify a live frame (@pxref{Deleting Frames}).  If omitted or
 @menu
 * 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.
 @end menu
 
@@ -446,14 +454,16 @@ has to specify a live frame (@pxref{Deleting Frames}).  If omitted or
 @cindex frame layout
 @cindex layout of frame
 
-The drawing below sketches the layout of a frame on a graphical
-terminal:
+A visible frame occupies a rectangular area on its terminal's display.
+This area may contain a number of nested rectangles, each serving a
+different purpose.  The drawing below sketches the layout of a frame on
+a graphical terminal:
 @smallexample
 @group
 
         <------------ Outer Frame Width ----------->
-        ___________________________________________
-     ^(0)  ___________ External Border __________   |
+        ____________________________________________
+     ^(0)  ________ External/Outer Border _______   |
      | |  |_____________ Title Bar ______________|  |
      | | (1)_____________ Menu Bar ______________|  | ^
      | | (2)_____________ Tool Bar ______________|  | ^
@@ -468,14 +478,14 @@ Height |  | | Height                           | |  | Height
      | |  | |   |                              | |  | |
      | |  | |___v______________________________| |  | |
      | |  |___________ Internal Border __________|  | v
-     v |______________ External Border _____________|
+     v |___________ External/Outer Border __________|
            <-------- Native Frame Width -------->
 
 @end group
 @end smallexample
 
 In practice not all of the areas shown in the drawing will or may be
-present.  The meaning of these areas is:
+present.  The meaning of these areas is described below.
 
 @table @samp
 @item Outer Frame
@@ -483,50 +493,100 @@ present.  The meaning of these areas is:
 @cindex outer edges
 @cindex outer width
 @cindex outer height
+@cindex outer size
 The @dfn{outer frame} is a rectangle comprising all areas shown in the
 drawing.  The edges of that rectangle are called the @dfn{outer edges}
-of the frame.  The @dfn{outer width} and @dfn{outer height} of the frame
-specify the size of that rectangle.
+of the frame.  Together, the @dfn{outer width} and @dfn{outer height} of
+the frame specify the @dfn{outer size} of that rectangle.
+
+Knowing the outer size of a frame is useful for fitting a frame into the
+working area of its display (@pxref{Multiple Terminals}) or for placing
+two frames adjacent to each other on the screen.  Usually, the outer
+size of a frame is available only after the frame has been mapped (made
+visible, @pxref{Visibility of Frames}) at least once.  For the initial
+frame or a frame that has not been created yet, the outer size can be
+estimated only or must be calculated from the window-system's or window
+manager defaults.  One workaround is to obtain the differences of the
+outer and native (see below) sizes of a mapped frame and use them for
+calculating the outer size of the new frame.
 
 @cindex outer position
 The upper left corner of the outer frame (indicated by @samp{(0)} in the
-drawing above) is the @dfn{outer position} or the frame.  It is
-specified by and settable via the @code{left} and @code{top} frame
-parameters (@pxref{Position Parameters}) as well as the functions
-@code{frame-position} and @code{set-frame-position} (@pxref{Size and
-Position}).
+drawing above) is the @dfn{outer position} of the frame.  The outer
+position of a graphical frame is also referred to as ``the position'' of
+the frame because it usually remains unchanged on its display whenever
+the frame is resized or its layout is changed.
+
+The outer position is specified by and can be set via the @code{left}
+and @code{top} frame parameters (@pxref{Position Parameters}).  For a
+normal, top-level frame these parameters usually represent its absolute
+position (see below) with respect to its display's origin.  For a child
+frame (@pxref{Child Frames}) these parameters represent its position
+relative to the native position (see below) of its parent frame.  For
+frames on text terminals the values of these parameters are meaningless
+and always zero.
 
 @item External Border
 @cindex external border
 The @dfn{external border} is part of the decorations supplied by the
-window manager.  It's typically used for resizing the frame with the
-mouse.  The external border is normally not shown on ``fullboth'' and
-maximized frames (@pxref{Size Parameters}) and doesn't exist for text
-terminal frames.
-
-   The external border should not be confused with the @dfn{outer
-border} specified by the @code{border-width} frame parameter
-(@pxref{Layout Parameters}).  Since the outer border is usually ignored
-on most platforms it is not covered here.
+window manager.  It is typically used for resizing the frame with the
+mouse and is therefore not shown on ``fullboth'' and maximized frames
+(@pxref{Size Parameters}).  Its width is determined by the window
+manager and cannot be changed by Emacs' functions.
+
+External borders don't exist on text terminal frames.  For graphical
+frames, their display can be suppressed by setting the
+@code{override-redirect} or @code{undecorated} frame parameter
+(@pxref{Management Parameters}).
+
+@item Outer Border
+@cindex outer border
+The @dfn{outer border} is a separate border whose width can be specified
+with the @code{border-width} frame parameter (@pxref{Layout
+Parameters}).  In practice, either the external or the outer border of a
+frame are displayed but never both at the same time.  Usually, the outer
+border is shown only for special frames that are not (fully) controlled
+by the window manager like tooltip frames (@pxref{Tooltips}), child
+frames (@pxref{Child Frames}) and @code{undecorated} or
+@code{override-redirect} frames (@pxref{Management Parameters}).
+
+Outer borders are never shown on text terminal frames and on frames
+generated by GTK+ routines.  On Windows, the outer border is emulated
+with the help of a one pixel wide external border.  Non-toolkit builds
+allow to change the color of the outer border by setting the
+@code{border-color} frame parameter (@pxref{Layout Parameters}).
 
 @item Title Bar
 @cindex title bar
 The @dfn{title bar} is also part of the window manager's decorations and
 typically displays the title of the frame (@pxref{Frame Titles}) as well
-as buttons for minimizing, maximizing and deleting the frame.  The title
-bar is usually not displayed on fullboth (@pxref{Size Parameters})
-or tooltip frames.  Title bars don't exist for text terminal frames.
+as buttons for minimizing, maximizing and deleting the frame.  It can be
+also used for dragging the frame with the mouse.  The title bar is
+usually not displayed for fullboth (@pxref{Size Parameters}), tooltip
+(@pxref{Tooltips}) and child frames (@pxref{Child Frames}) and doesn't
+exist for terminal frames.  Display of the title bar can be suppressed
+by setting the @code{override-redirect} or the @code{undecorated} frame
+parameters (@pxref{Management Parameters}).
 
 @item Menu Bar
 @cindex internal menu bar
 @cindex external menu bar
 The menu bar (@pxref{Menu Bar}) can be either internal (drawn by Emacs
-itself) or external (drawn by a toolkit).  Most builds (GTK+, Lucid,
+itself) or external (drawn by the toolkit).  Most builds (GTK+, Lucid,
 Motif and Windows) rely on an external menu bar.  NS also uses an
 external menu bar which, however, is not part of the outer frame.
 Non-toolkit builds can provide an internal menu bar.  On text terminal
 frames, the menu bar is part of the frame's root window (@pxref{Windows
-and Frames}).
+and Frames}).  As a rule, menu bars are never shown on child frames
+(@pxref{Child Frames}).  Display of the menu bar can be suppressed by
+setting the @code{menu-bar-lines} parameter (@pxref{Layout Parameters})
+to zero.
+
+It depends on the toolkit whether to wrap or truncate the menu bar
+whenever it becomes too long to fit on its frame.  Usually, only Motif
+and Windows builds can wrap the menu bar.  When they (un-)wrap the menu
+bar, they try to keep the outer height of the frame unchanged, so the
+native height of the frame (see below) will change instead.
 
 @item Tool Bar
 @cindex internal tool bar
@@ -536,21 +596,39 @@ internal (drawn by Emacs itself) or external (drawn by a toolkit).  The
 GTK+ and NS builds have the tool bar drawn by the toolkit.  The
 remaining builds use internal tool bars.  With GTK+ the tool bar can be
 located on either side of the frame, immediately outside the internal
-border, see below.
+border, see below.  Tool bars are usually not shown for child frames
+(@pxref{Child Frames}).  Display of the tool bar can be suppressed by
+setting the @code{tool-bar-lines} parameter (@pxref{Layout
+Parameters}) to zero.
+
+If the variable @code{auto-resize-tool-bars} is non-@code{nil}, Emacs
+wraps the internal tool bar when it becomes too long for its frame.  If
+and when Emacs (un-)wraps the internal tool bar, it by default keeps the
+outer height of the frame unchanged, so the native height of the frame
+(see below) will change instead.  Emacs built with GTK+, on the other
+hand, never wraps the tool bar but may automatically increase the outer
+width of a frame in order to accommodate an overlong tool bar.
 
 @item Native Frame
 @cindex native frame
 @cindex native edges
 @cindex native width
 @cindex native height
-@cindex display area
+@cindex native size
 The @dfn{native frame} is a rectangle located entirely within the outer
-frame.  It excludes the areas occupied by the external border, the title
-bar and any external menu or external tool bar.  The area enclosed by
-the native frame is sometimes also referred to as the @dfn{display area}
-of the frame.  The edges of the native frame are called the @dfn{native
-edges} of the frame.  The @dfn{native width} and @dfn{native height} of
-the frame specify the size of the rectangle.
+frame.  It excludes the areas occupied by an external or outer border,
+the title bar and any external menu or tool bar.  The edges of the
+native frame are called the @dfn{native edges} of the frame.  Together,
+the @dfn{native width} and @dfn{native height} of a frame specify the
+@dfn{native size} of the frame.
+
+The native size of a frame is the size Emacs passes to the window-system
+or window manager when creating or resizing the frame from within Emacs.
+It is also the size Emacs receives from the window-system or window
+manager whenever these resize the frame's window-system window, for
+example, after maximizing the frame by clicking on the corresponding
+button in the title bar or when dragging its external border with the
+mouse.
 
 @cindex native position
 The top left corner of the native frame specifies the @dfn{native
@@ -565,30 +643,42 @@ position for the various builds:
 @item (3) GTK+ and NS frames
 @end itemize
 
-Accordingly, the native height of a frame includes the height of the
+Accordingly, the native height of a frame may include the height of the
 tool bar but not that of the menu bar (Lucid, Motif, Windows) or those
 of the menu bar and the tool bar (non-toolkit and text terminal frames).
 
-The native position of a frame is the reference position of functions
+The native position of a frame is the reference position for functions
 that set or return the current position of the mouse (@pxref{Mouse
 Position}) and for functions dealing with the position of windows like
 @code{window-edges}, @code{window-at} or @code{coordinates-in-window-p}
-(@pxref{Coordinates and Windows}).
+(@pxref{Coordinates and Windows}).  It also specifies the (0, 0) origin
+for locating and positioning child frames within this frame
+(@pxref{Child Frames}).
+
+Note also that the native position of a frame usually remains unaltered
+on its display when removing or adding the window manager decorations by
+changing the frame's @code{override-redirect} or @code{undecorated}
+parameter (@pxref{Management Parameters}).
 
 @item Internal Border
-The internal border (@pxref{Layout Parameters}) is a border drawn by
-Emacs around the inner frame (see below).
+The internal border is a border drawn by Emacs around the inner frame
+(see below).  Its width is specified by the @code{internal-border-width}
+frame parameter (@pxref{Layout Parameters}).  Its color is specified by
+the background of the @code{internal-border} face.
 
 @item Inner Frame
 @cindex inner frame
 @cindex inner edges
 @cindex inner width
 @cindex inner height
+@cindex inner size
+@cindex display area
 The @dfn{inner frame} is the rectangle reserved for the frame's windows.
 It's enclosed by the internal border which, however, is not part of the
 inner frame.  Its edges are called the @dfn{inner edges} of the frame.
-The @dfn{inner width} and @dfn{inner height} specify the size of the
-rectangle.
+The @dfn{inner width} and @dfn{inner height} specify the @dfn{inner
+size} of the rectangle.  The inner frame is sometimes also referred to
+as the @dfn{display area} of the frame.
 
 @cindex minibuffer-less frame
 @cindex minibuffer-only frame
@@ -603,22 +693,39 @@ configurations.
 
 @item Text Area
 @cindex text area
-The @dfn{text area} of a frame is a somewhat fictitious area located
-entirely within the native frame.  It can be obtained by removing from
-the native frame any internal borders, one vertical and one horizontal
-scroll bar, and one left and one right fringe as specified for this
-frame, see @ref{Layout Parameters}.
+The @dfn{text area} of a frame is a somewhat fictitious area that can be
+embedded in the native frame.  Its position is unspecified.  Its width
+can be obtained by removing from that of the native width the widths of
+the internal border, one vertical scroll bar, and one left and one right
+fringe as specified for this frame, see @ref{Layout Parameters}.  Its
+height can be obtained by removing from that of the native height the
+widths of the internal border and the heights of the frame's internal
+menu and tool bars and one horizontal scroll bar as specified for this
+frame.
 @end table
 
 @cindex absolute position
-The @dfn{absolute position} of a frame or its edges is usually given in
-terms of pixels counted from an origin at position (0, 0) of the frame's
-display.  Note that with multiple monitors the origin does not
-necessarily coincide with the top left corner of the entire usable
-display area.  Hence the absolute outer position of a frame or the
-absolute positions of the edges of the outer, native or inner frame can
-be negative in such an environment even when that frame is completely
-visible.
+@cindex absolute frame position
+@cindex absolute edges
+@cindex absolute frame edges
+@cindex display origin
+@cindex origin of display
+The @dfn{absolute position} of a frame is given as a pair (X, Y) of
+horizontal and vertical pixel offsets relative to an origin (0, 0) of
+the frame's display.  Correspondingly, the @dfn{absolute edges} of a
+frame are given as pixel offsets from that origin.
+
+  Note that with multiple monitors the origin of the display does not
+necessarily coincide with the top-left corner of the entire usable
+display area of the terminal.  Hence the absolute position of a frame
+can be negative in such an environment even when that frame is
+completely visible.
+
+  By convention, vertical offsets increase ``downwards''.  This means
+that the height of a frame is obtained by subtracting the offset of its
+top edge from that of its bottom edge.  Horizontal offsets increase
+``leftwards'' as expected so a frame's width is calculated by
+subtracting the offset of its left edge from that of its right edge.
 
   For a frame on a graphical terminal the following function returns the
 sizes of the areas described above:
@@ -626,13 +733,15 @@ sizes of the areas described above:
 @defun frame-geometry &optional frame
 This function returns geometric attributes of @var{frame}.  The return
 value is an association list of the attributes listed below.  All
-coordinate, height and width values are integers counting pixels.
+coordinate, height and width values are integers counting pixels.  Note
+that if @var{frame} has not been mapped (@pxref{Visibility of Frames})
+yet, some of the return values may only represent approximations of the
+actual values---those that can be seen after the frame has been mapped.
 
 @table @code
 @item outer-position
-A cons of the absolute X- and Y-coordinates of the outer position of
-@var{frame}, relative to the origin at position (0, 0) of @var{frame}'s
-display.
+A cons representing the absolute position of the outer @var{frame},
+relative to the origin at position (0, 0) of @var{frame}'s display.
 
 @item outer-size
 A cons of the outer width and height of @var{frame}.
@@ -643,6 +752,10 @@ borders as supplied by the window manager.  If the window manager
 doesn't supply these values, Emacs will try to guess them from the
 coordinates of the outer and inner frame.
 
+@item outer-border-width
+The width of the outer border of @var{frame}.  The value is meaningful
+for non-GTK+ X builds only.
+
 @item title-bar-size
 A cons of the width and height of the title bar of @var{frame} as
 supplied by the window manager or operating system.  If both of them are
@@ -677,24 +790,27 @@ The following function can be used to retrieve the edges of the outer,
 native and inner frame.
 
 @defun frame-edges &optional frame type
-This function returns the edges of the outer, native or inner frame of
-@var{frame}.  @var{frame} must be a live frame and defaults to the
-selected one.  The list returned has the form (@var{left} @var{top}
+This function returns the absolute edges of the outer, native or inner
+frame of @var{frame}.  @var{frame} must be a live frame and defaults to
+the selected one.  The list returned has the form (@var{left} @var{top}
 @var{right} @var{bottom}) where all values are in pixels relative to the
-position (0, 0) of @var{frame}'s display.  For terminal frames
-@var{left} and @var{top} are both zero.
+origin of @var{frame}'s display.  For terminal frames the values
+returned for @var{left} and @var{top} are always zero.
 
 Optional argument @var{type} specifies the type of the edges to return:
-@var{type} @code{outer-edges} means to return the outer edges of
-@var{frame}, @code{native-edges} (or @code{nil}) means to return its
-native edges and @code{inner-edges} means to return its inner edges.
+@code{outer-edges} means to return the outer edges of @var{frame},
+@code{native-edges} (or @code{nil}) means to return its native edges and
+@code{inner-edges} means to return its inner edges.
 
-Notice that the pixels at the positions @var{bottom} and @var{right}
-lie immediately outside the corresponding frame.  This means that if you
-have, for example, two side-by-side frames positioned such that the
-right outer edge of the frame on the left equals the left outer edge of
-the frame on the right, the pixels representing that edge are part
-of the frame on the right.
+By convention, the pixels of the display at the values returned for
+@var{left} and @var{top} are inside (part of) @var{frame}.  Hence, if
+@var{left} and @var{top} are both zero, the pixel at the display's
+origin is part of @var{frame}.  The pixels at @var{bottom} and
+@var{right}, on the other hand, lie immediately outside @var{frame}.
+This means that if you have, for example, two side-by-side frames
+positioned such that the right outer edge of the frame on the left
+equals the left outer edge of the frame on the right, the pixels at that
+edge show a part of the frame on the right.
 @end defun
 
 
@@ -751,62 +867,112 @@ and all future graphical frames.
 @end deffn
 
 
-@node Size and Position
-@subsection Size and Position
-@cindex frame size
+@node Frame Position
+@subsection Frame Position
 @cindex frame position
 @cindex position of frame
 
-You can read or change the position of a frame using the frame
-parameters @code{left} and @code{top} (@pxref{Position Parameters}) and
-its size using the @code{height} and @code{width} parameters
-(@pxref{Size Parameters}).  Here are some special features for working
-with sizes and positions.  For all of these functions the argument
-@var{frame} must denote a live frame and defaults to the selected frame.
+On graphical systems, the position of a normal top-level frame is
+specified as the absolute position of its outer frame (@pxref{Frame
+Geometry}).  The position of a child frame (@pxref{Child Frames}) is
+specified via pixel offsets of its outer edges relative to the native
+position of its parent frame.
+
+  You can read or change the position of a frame using the frame
+parameters @code{left} and @code{top} (@pxref{Position Parameters}).
+Here are two additional functions for working with the positions of an
+existing, visible frame.  For both functions, the argument @var{frame}
+must denote a live frame and defaults to the selected frame.
 
 @defun frame-position &optional frame
-This function returns the outer position (@pxref{Frame Layout}) of
-@var{frame} in pixels.  The value is a cons giving the coordinates of
-the top left corner of the outer frame of @var{frame} relative to an
-origin at the position (0, 0) of the frame's display.  On a text
-terminal frame both values are zero.
+For a normal, non-child frame this function returns a cons of the (X, Y)
+pixel coordinates of its outer position (@pxref{Frame Layout}) with
+respect to the origin (0, 0) of its display.  For a child frame
+(@pxref{Child Frames}) this function returns the pixel coordinates of
+its outer position with respect to an origin (0, 0) at the native
+position of @var{frame}'s parent.
+
+Negative return values never indicate an offset from the right or bottom
+edge of @var{frame}'s display or parent frame.  Rather, they mean that
+@var{frame}'s outer position is on the left and/or above the origin of
+its display or the native position of its parent frame.  This usually
+means that @var{frame} is only partially visible (or completely
+invisible).  However, on systems where the display's origin does not
+coincide with its top-left corner, the frame may be visible on a
+secondary monitor.
+
+On a text terminal frame both values are zero.
 @end defun
 
 @defun set-frame-position frame x y
-This function sets the outer frame position of @var{frame} to @var{x}
-and @var{y}.  The latter arguments specify pixels and normally count
-from an origin at the position (0, 0) of @var{frame}'s display.
+This function sets the outer frame position of @var{frame} to (@var{x},
+@var{y}).  The latter arguments specify pixels and normally count from
+an origin at the position (0, 0) of @var{frame}'s display.  For child
+frames, they count from the native position of @var{frame}'s parent
+frame.
+
+Negative parameter values position the right edge of the outer frame by
+@var{-x} pixels left from the right edge of the screen (or the parent
+frame's native rectangle) and the bottom edge by @var{-y} pixels up from
+the bottom edge of the screen (or the parent frame's native rectangle).
 
-A negative parameter value positions the right edge of the outer frame
-by @var{-x} pixels left from the right edge of the screen or the bottom
-edge by @var{-y} pixels up from the bottom edge of the screen.
+Note that negative values do not permit to align the right or bottom
+edge of @var{frame} exactly at the right or bottom edge of its display
+or parent frame.  Neither do they allow to specify a position that does
+not lie within the edges of the display or parent frame.  The frame
+parameters @code{left} and @code{top} (@pxref{Position Parameters})
+allow to do that but may still fail to provide good results for the
+initial or a new frame.
 
 This function has no effect on text terminal frames.
 @end defun
 
-@defun frame-pixel-height &optional frame
-@defunx frame-pixel-width &optional frame
-   These functions return the inner height and width (the height and
-width of the display area, see @ref{Frame Layout}) of @var{frame} in
-pixels.  For a text terminal, the results are in characters rather than
-pixels.
-@end defun
+@defvar move-frame-functions
+This hook specifies the functions run when an Emacs frame is moved
+(assigned a new position) by the window-system or window manager.  The
+functions are run with one argument, the frame that moved.  For a child
+frame (@pxref{Child Frames}), the functions are run only when the
+position of the frame changes in relation to that of its parent frame.
+@end defvar
+
+
+@node Frame Size
+@subsection Frame Size
+@cindex frame size
+@cindex text width of a frame
+@cindex text height of a frame
+@cindex text size of a frame
+The canonical way to specify the @dfn{size of a frame} from within Emacs
+is by specifying its @dfn{text size}---a tuple of the width and height
+of the frame's text area (@pxref{Frame Layout}).  It can be measured
+either in pixels or in terms of the frame's canonical character size
+(@pxref{Frame Font}).
+
+  For frames with an internal menu or tool bar, the frame's native
+height cannot be told exactly before the frame has been actually drawn.
+This means that in general you cannot use the native size to specify the
+initial size of a frame.  As soon as you know the native size of a
+visible frame, you can calculate its outer size (@pxref{Frame Layout})
+by adding in the remaining components from the return value of
+@code{frame-geometry} .  For invisible frames or for frames that have
+yet to be created, however, the outer size can be estimated only.  This
+also means that calculating an exact initial position of a frame
+specified via offsets from the right or bottom edge of the screen
+(@pxref{Frame Position}) is impossible.
+
+  The text size of any frame can be set and retrieved with the help of
+the @code{height} and @code{width} frame parameters (@pxref{Size
+Parameters}).  The text size of the initial frame can be also set with
+the help of an X-style geometry specification.  @xref{Emacs Invocation,,
+Command Line Arguments for Emacs Invocation, emacs, The GNU Emacs
+Manual}.  Below we list some functions to access and set the size of an
+existing, visible frame.
 
 @defun frame-text-height &optional frame
 @defunx frame-text-width &optional frame
 These functions return the height and width of the text area of
 @var{frame} (@pxref{Frame Layout}), measured in pixels.  For a text
 terminal, the results are in characters rather than pixels.
-
-The value returned by @code{frame-text-height} differs from that
-returned by @code{frame-pixel-height} by not including the heights of
-any internal tool bar or menu bar, the height of one horizontal scroll
-bar and the widths of the internal border.
-
-The value returned by @code{frame-text-width} differs from that returned
-by @code{frame-pixel-width} by not including the width of one vertical
-scroll bar, the widths of one left and one right fringe and the widths
-of the internal border.
 @end defun
 
 @defun frame-height &optional frame
@@ -823,12 +989,28 @@ rounded down to the number of characters of the default font that fully
 fit into the text area.
 @end defun
 
+@defun frame-pixel-height &optional frame
+@defunx frame-pixel-width &optional frame
+These functions return the native width and height, see @ref{Frame
+Layout}) of @var{frame} in pixels.  For a text terminal, the results are
+in characters rather than pixels.
+@end defun
+
+On window systems that support it, Emacs tries by default to make the
+text size of a frame measured in pixels a multiple of the frame's
+character size.  This, however, usually means that a frame can be
+resized only in character size increments when dragging its external
+borders.  It also may break attempts to truly maximize the frame or
+making it ``fullheight'' or ``fullwidth'' (@pxref{Size Parameters})
+leaving some empty space below and/or on the right of the frame.  The
+following option may help in that case.
+
 @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} whenever the frame is resized.  If this is
-non-@code{nil}, no rounding occurs, hence frame sizes can
-increase/decrease by one pixel.
+If this option is @code{nil}, a frame's text pixel size is usually
+rounded to a multiple of the current values of that frame's
+@code{frame-char-height} and @code{frame-char-width} whenever the frame
+is resized.  If this is non-@code{nil}, no rounding occurs, hence frame
+sizes can increase/decrease by one pixel.
 
 Setting this variable usually causes the next resize operation to pass
 the corresponding size hints to the window manager.  This means that
@@ -855,7 +1037,7 @@ terms of the canonical height and width of a character on @var{frame}
 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
+truly honor the request if it does not increase/decrease the frame size
 to a multiple of its character size.
 @end defun
 
@@ -876,9 +1058,9 @@ 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.
+@code{frame-resize-pixelwise} is @code{nil}, some window managers may
+refuse to truly 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 pixelwise
@@ -888,9 +1070,9 @@ in characters.  The argument @var{pretend} has the same meaning as in
 
 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.
+@code{frame-resize-pixelwise} is @code{nil}, some window managers 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
 
 None of these three functions will make a frame smaller than needed to
@@ -899,7 +1081,25 @@ margins, dividers, mode and header lines.  This contrasts with requests
 by the window manager triggered, for example, by dragging the external
 border of a frame with the mouse.  Such requests are always honored by
 clipping, if necessary, portions that cannot be displayed at the right,
-bottom corner of the frame.
+bottom corner of the frame.  The parameters @code{min-width} and
+@code{min-height} (@pxref{Size Parameters}) can be used to obtain a
+similar behavior when changing the frame size from within Emacs.
+
+@cindex tracking frame size changes
+  The abnormal hook @code{window-size-change-functions} (@pxref{Window
+Hooks}) tracks all changes of the inner size of a frame including those
+induced by request of the window-system or window manager.  To rule out
+false positives that might occur when changing only the sizes of a
+frame's windows without actually changing the size of the inner frame,
+use the following function.
+
+@defun frame-size-changed-p &optional frame
+This function returns non-@code{nil} when the inner width or height of
+@var{frame} has changed since @code{window-size-change-functions} was
+run the last time for @var{frame}.  It always returns @code{nil}
+immediately after running @code{window-size-change-functions} for
+@var{frame}.
+@end defun
 
 
 @node Implied Frame Resizing
@@ -916,7 +1116,7 @@ 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.
 
-   Occasionally, such @dfn{implied frame resizing} may be unwanted, for
+  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:
@@ -928,7 +1128,7 @@ 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.
 
-The value of this option can be also be a list of frame parameters.  In
+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},
@@ -1135,6 +1335,8 @@ text terminals.
 * 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.
@@ -1180,64 +1382,81 @@ If you specify the frame name explicitly when you create the frame, the
 name is also used (instead of the name of the Emacs executable) when
 looking up X resources for the frame.
 
+@vindex explicit-name, a frame parameter
 @item explicit-name
 If the frame name was specified explicitly when the frame was created,
 this parameter will be that name.  If the frame wasn't explicitly
 named, this parameter will be @code{nil}.
 @end table
 
+
 @node Position Parameters
 @subsubsection Position Parameters
 @cindex window position on display
 @cindex frame position
 
-  Position parameters' values are measured in pixels.  (Note that none
-of these parameters exist on TTY frames.)
+Parameters describing the X- and Y-offsets of a frame are always
+measured in pixels.  For normal, non-child frames they specify the
+frame's absolute outer position (@pxref{Frame Geometry}) with respect to
+its display's origin.  For a child frame (@pxref{Child Frames}) they
+specify the frame's outer position relative to the native position of
+the frame's parent frame.  (Note that none of these parameters is
+meaningful on TTY frames.)
 
 @table @code
 @vindex left, a frame parameter
 @item left
-The position, in pixels, of the left (or right) edge of the frame with
-respect to the left (or right) edge of the screen.  The value may be:
+The position, in pixels, of the left outer edge of the frame with
+respect to the left edge of the frame's display or parent frame.
 
 @table @asis
 @item an integer
-A positive integer relates the left edge of the frame to the left edge
-of the screen.  A negative integer relates the right frame edge to the
-right screen edge.
+A positive integer always relates the left edge of the frame to the left
+edge of its display or parent frame.  A negative integer relates the
+right frame edge to the right edge of the display or parent frame.
 
 @item @code{(+ @var{pos})}
 This specifies the position of the left frame edge relative to the left
-screen edge.  The integer @var{pos} may be positive or negative; a
-negative value specifies a position outside the screen or on a monitor
-other than the primary one (for multi-monitor displays).
+edge of its display or parent frame.  The integer @var{pos} may be
+positive or negative; a negative value specifies a position outside the
+screen or parent frame or on a monitor other than the primary one (for
+multi-monitor displays).
 
 @item @code{(- @var{pos})}
-This specifies the position of the right frame edge relative to the right
-screen edge.  The integer @var{pos} may be positive or negative; a
-negative value specifies a position outside the screen or on a monitor
-other than the primary one (for multi-monitor displays).
+This specifies the position of the right frame edge relative to the
+right edge of the display or parent frame.  The integer @var{pos} may be
+positive or negative; a negative value specifies a position outside the
+screen or parent frame or on a monitor other than the primary one (for
+multi-monitor displays).
 @end table
 
 Some window managers ignore program-specified positions.  If you want to
 be sure the position you specify is not ignored, specify a
-non-@code{nil} value for the @code{user-position} parameter as well.
-
-If the window manager refuses to align a frame at the left or top screen
-edge, combining position notation and @code{user-position} as in
+non-@code{nil} value for the @code{user-position} parameter as in the
+following example:
 
 @example
 (modify-frame-parameters
   nil '((user-position . t) (left . (+ -4))))
 @end example
 
-may help to override that.
+In general, it is not a good idea to specify negative offsets to
+position a frame relative to the right or bottom edge of its display.
+Positioning the initial or a new frame is either not accurate (because
+the size of the outer frame is not yet fully known before the frame has
+been made visible) or will cause additional flicker (if the frame is
+repositioned after becoming visible).
+
+  Note also, that negative offsets are not stored internally and are not
+returned by the function @code{frame-parameters}.  This means that the
+desktop saving routines will restore the frame from the positive offsets
+obtained by that function.
 
 @vindex top, a frame parameter
 @item top
 The screen position of the top (or bottom) edge, in pixels, with respect
-to the top (or bottom) edge of the screen.  It works just like
-@code{left}, except vertically instead of horizontally.
+to the top (or bottom) edge of the display or parent frame.  It works
+just like @code{left}, except vertically instead of horizontally.
 
 @vindex icon-left, a frame parameter
 @item icon-left
@@ -1273,6 +1492,22 @@ When you call @code{make-frame}, you should specify a non-@code{nil}
 value for this parameter if the values of the @code{left} and @code{top}
 parameters represent the user's stated preference; otherwise, use
 @code{nil}.
+
+@vindex z-group, a frame parameter
+@item z-group
+This parameter specifies a relative position of the frame's
+window-system window in the stacking (Z-) order of the frame's display.
+
+If this is @code{above}, the frame's window-system window is displayed
+above all other window-system windows that do not have the @code{above}
+property set.  If this is nil, the frame's window is displayed below all
+windows that have the @code{above} property set and above all windows
+that have the @code{below} property set.  If this is @code{below}, the
+frame's window is displayed below all windows that do not have the
+@code{below} property set.
+
+To position the frame above or below a specific other frame use the
+function @code{frame-restack} (@pxref{Raising and Lowering}).
 @end table
 
 
@@ -1285,15 +1520,19 @@ graphical displays, the @code{default} face determines the actual
 pixel sizes of these character units (@pxref{Face Attributes}).
 
 @table @code
-@vindex height, a frame parameter
-@item height
-The height of the frame's text area (@pxref{Frame Geometry}), in
-characters.
-
 @vindex width, a frame parameter
 @item width
 The width of the frame's text area (@pxref{Frame Geometry}), in
-characters.
+characters.  The value can be also a cons cell of the symbol
+@code{text-pixels} and an integer denoting the width of the text area in
+pixels.
+
+@vindex height, a frame parameter
+@item height
+The height of the frame's text area (@pxref{Frame Geometry}), in
+characters.  The value can be also a cons cell of the symbol
+@code{text-pixels} and an integer denoting the height of the text area
+in pixels.
 
 @vindex user-size, a frame parameter
 @item user-size
@@ -1302,6 +1541,28 @@ the @code{user-position} parameter (@pxref{Position Parameters,
 user-position}) does for the position parameters @code{top} and
 @code{left}.
 
+@vindex min-width, a frame parameter
+@item min-width
+This parameter specifies the minimum native width of the frame
+(@pxref{Frame Geometry}), in characters.  Normally, the functions that
+establish a frame's initial width or resize a frame horizontally make
+sure that all the frame's windows, vertical scroll bars, fringes,
+margins and vertical dividers can be displayed.  This parameter, if
+non-@code{nil} allows to make a frame narrower than that with the
+consequence that any components that do not fit on the frame will be
+clipped by the window manager.
+
+@vindex min-height, a frame parameter
+@item min-height
+This parameter specifies the minimum height of the native (@pxref{Frame
+Geometry}), in characters.  Normally, the functions that establish a
+frame's initial size or resize a frame make sure that all the frame's
+windows, horizontal scroll bars and dividers, mode and header lines, the
+echo area and the internal menu and tool bar can be displayed.  This
+parameter, if non-@code{nil} allows to make a frame smaller than that
+with the consequence that any components that do not fit on the frame
+will be clipped by the window-system or window manager.
+
 @cindex fullboth frames
 @cindex fullheight frames
 @cindex fullwidth frames
@@ -1327,10 +1588,10 @@ of maximized and full-height frames and the widths of maximized and
 full-width frames often differ by a few pixels.
 
 With some window managers you may have to customize the variable
-@code{frame-resize-pixelwise} (@pxref{Size and Position}) in order to
-make a frame truly appear maximized or full-screen.  Moreover,
-some window managers might not support smooth transition between the
-various full-screen or maximization states.  Customizing the variable
+@code{frame-resize-pixelwise} (@pxref{Frame Size}) in order to make a
+frame truly appear maximized or full-screen.  Moreover, some window
+managers might not support smooth transition between the various
+full-screen or maximization states.  Customizing the variable
 @code{x-frame-normalize-before-maximize} can help to overcome that.
 
 @vindex fullscreen-restore, a frame parameter
@@ -1364,11 +1625,12 @@ frame, or control their sizes.
 @table @code
 @vindex border-width, a frame parameter
 @item border-width
-The width in pixels of the frame's border.
+The width in pixels of the frame's outer border (@pxref{Frame Geometry}).
 
 @vindex internal-border-width, a frame parameter
 @item internal-border-width
-The distance in pixels between text (or fringe) and the frame's border.
+The width in pixels of the frame's internal border (@pxref{Frame
+Geometry}).
 
 @vindex vertical-scroll-bars, a frame parameter
 @item vertical-scroll-bars
@@ -1418,21 +1680,25 @@ to not draw bottom dividers.
 
 @vindex menu-bar-lines frame parameter
 @item menu-bar-lines
-The number of lines to allocate at the top of the frame for a menu
-bar.  The default is 1 if Menu Bar mode is enabled, and 0 otherwise.
-@xref{Menu Bars,,,emacs, The GNU Emacs Manual}.
+The number of lines to allocate at the top of the frame for a menu bar.
+The default is one if Menu Bar mode is enabled and zero otherwise.
+@xref{Menu Bars,,,emacs, The GNU Emacs Manual}.  For an external menu
+bar, this value remains unchanged even when the menu bar wraps to two or
+more lines.  In that case, the @code{menu-bar-size} value returned by
+@code{frame-geometry} (@pxref{Frame Geometry}) allows to derive whether
+the menu bar actually occupies one or more lines.
 
 @vindex tool-bar-lines frame parameter
 @item tool-bar-lines
-The number of lines to use for the tool bar.  The default is 1 if Tool
-Bar mode is enabled, and 0 otherwise.  @xref{Tool Bars,,,emacs, The
-GNU Emacs Manual}.
+The number of lines to use for the tool bar.  The default is one if Tool
+Bar mode is enabled and zero otherwise.  @xref{Tool Bars,,,emacs, The
+GNU Emacs Manual}.  This value may change whenever the tool bar wraps.
 
 @vindex tool-bar-position frame parameter
 @item tool-bar-position
 The position of the tool bar.  Currently only for the GTK tool bar.
 Value can be one of @code{top}, @code{bottom} @code{left}, @code{right}.
-The default is  @code{top}.
+The default is @code{top}.
 
 @vindex line-spacing, a frame parameter
 @item line-spacing
@@ -1440,6 +1706,7 @@ Additional space to leave below each text line, in pixels (a positive
 integer).  @xref{Line Height}, for more information.
 @end table
 
+
 @node Buffer Parameters
 @subsubsection Buffer Parameters
 @cindex frame, which buffers to display
@@ -1478,6 +1745,40 @@ most-recently-selected first.
 If non-@code{nil}, this frame's window is never split automatically.
 @end table
 
+@node Frame Interaction Parameters
+@subsubsection Frame Interaction Parameters
+
+These parameters supply forms of interactions between different frames.
+
+@table @code
+@vindex parent-frame, a frame parameter
+@item parent-frame
+If non-@code{nil}, this means that this frame is a child frame
+(@pxref{Child Frames}) and this parameter specifies its parent frame.
+If nil, this means that this frame is a normal, top-level frame.
+
+@vindex delete-before, a frame parameter
+@item delete-before
+If non-@code{nil}, this parameter specifies another frame whose deletion
+will automatically trigger the deletion of this frame.  @xref{Deleting
+Frames}.
+
+@vindex mouse-wheel-frame, a frame parameter
+@item mouse-wheel-frame
+If non-@code{nil}, this parameter specifies the frame whose windows will
+be scrolled whenever the mouse wheel is scrolled with the mouse pointer
+hovering over this frame (@pxref{Mouse Commands,,, emacs, The GNU Emacs
+Manual}).
+
+@vindex no-other-frame, a frame parameter
+@item no-other-frame
+If this is non-@code{nil}, then this frame is not eligible as candidate
+for the functions @code{next-frame}, @code{previous-frame}
+(@pxref{Finding All Frames}) and @code{other-frame} (@pxref{Frame
+Commands,,, emacs, The GNU Emacs Manual}).
+@end table
+
+
 @node Management Parameters
 @subsubsection Window Management Parameters
 @cindex window manager interaction, and frame parameters
@@ -1541,10 +1842,56 @@ with virtual desktops.
 
 @vindex inhibit-double-buffering, a frame parameter
 @item inhibit-double-buffering
-If non-@code{nil}, the frame is drawn to the screen without double buffering.
-Emacs normally attempts to use double buffering, where available, to
-reduce flicker.  Set this property if you experience display bugs or
-pine for that retro, flicker-y feeling.
+If non-@code{nil}, the frame is drawn to the screen without double
+buffering.  Emacs normally attempts to use double buffering, where
+available, to reduce flicker.  Set this property if you experience
+display bugs or pine for that retro, flicker-y feeling.
+
+@vindex skip-taskbar, a frame parameter
+@item skip-taskbar
+If non-@code{nil}, this tells the window manager to remove the frame's
+icon from the taskbar associated with the frame's display and inhibit
+switching to the frame's window via the combination @kbd{Alt-@key{TAB}}.
+On Windows, iconifying such a frame will "roll in" its window-system
+window at the bottom of the desktop.  Some window managers may not honor
+this parameter.
+
+@vindex no-focus-on-map, a frame parameter
+@item no-focus-on-map
+If non-@code{nil}, this means that the frame dos not want to receive
+input focus when it is mapped (@pxref{Visibility of Frames}).  Some
+window managers may not honor this parameter.
+
+@vindex no-accept-focus, a frame parameter
+@item no-accept-focus
+If non-@code{nil}, this means that the frame does not want to receive
+input focus via explicit mouse clicks or when moving the mouse into it
+either via @code{focus-follows-mouse} (@pxref{Input Focus}) or
+@code{mouse-autoselect-window} (@pxref{Mouse Window Auto-selection}).
+This may have the unwanted side-effect that a user cannot scroll a
+non-selected frame with the mouse.  Some window managers may not honor
+this parameter.
+
+@vindex undecorated, a frame parameter
+@item undecorated
+If non-@code{nil}, this frame's window-system window is drawn without
+decorations like title, minimize/maximize boxes and external borders.
+This usually means that the window cannot be dragged, resized,
+iconified, maximized or deleted with the mouse.  If nil, the frame's
+window is usually drawn with all the elements listed above unless their
+display has been suspended via window manager settings.
+
+Under X, Emacs uses the Motif window manager hints to turn off
+decorations.  Some window managers may not honor these hints.
+
+@vindex override-redirect, a frame parameter
+@item override-redirect
+@cindex override redirect frames
+If non-@code{nil}, this means that this is an @dfn{override redirect}
+frame---a frame not handled by window managers under X.  Override
+redirect frames have no window manager decorations, can be positioned
+and resized only via Emacs' positioning and resizing functions and are
+usually drawn on top of all other frames.
 
 @ignore
 @vindex parent-id, a frame parameter
@@ -1557,6 +1904,7 @@ it and see if it works.)
 @end ignore
 @end table
 
+
 @node Cursor Parameters
 @subsubsection Cursor Parameters
 @cindex cursor, and frame parameters
@@ -1904,21 +2252,28 @@ while processing @code{frame-title-format} or
 @section Deleting Frames
 @cindex deleting frames
 
-  A @dfn{live frame} is one that has not been deleted.  When a frame
-is deleted, it is removed from its terminal display, although it may
-continue to exist as a Lisp object until there are no more references
-to it.
+A @dfn{live frame} is one that has not been deleted.  When a frame is
+deleted, it is removed from its terminal display, although it may
+continue to exist as a Lisp object until there are no more references to
+it.
 
 @deffn Command delete-frame &optional frame force
 @vindex delete-frame-functions
 This function deletes the frame @var{frame}.  The argument @var{frame}
 must specify a live frame (see below) and defaults to the selected
-frame.  Unless @var{frame} specifies a tooltip, this function first runs
-the hook @code{delete-frame-functions} (each function getting one
-argument, @var{frame}).
+frame.
 
-A frame cannot be deleted as long as its minibuffer serves as surrogate
-minibuffer for another frame (@pxref{Minibuffers and Frames}).
+It first deletes any child frame of @var{frame} (@pxref{Child Frames})
+and any frame whose @code{delete-before} frame parameter (@pxref{Frame
+Interaction Parameters}) specifies @var{frame}.  All such deletions are
+performed recursively; so this step makes sure that there will not exist
+any other frames with @var{frame} as their ancestor.  Then, unless
+@var{frame} specifies a tooltip, this function runs the hook
+@code{delete-frame-functions} (each function getting one argument,
+@var{frame}) before actually killing the frame.
+
+Note that a frame cannot be deleted as long as its minibuffer serves as
+surrogate minibuffer for another frame (@pxref{Minibuffers and Frames}).
 Normally, you cannot delete a frame if all other frames are invisible,
 but if @var{force} is non-@code{nil}, then you are allowed to do so.
 @end deffn
@@ -1942,8 +2297,13 @@ minibuffer frame is left untouched.  The argument @var{frame} must
 specify a live frame and defaults to the selected frame.  Internally,
 this command works by calling @code{delete-frame} with @var{force}
 @code{nil} for all frames that shall be deleted.
+
+This function does not delete any of @var{frame}'s child frames
+(@pxref{Child Frames}).  If @var{frame} is a child frame, it deletes
+@var{frame}'s siblings only.
 @end deffn
 
+
 @node Finding All Frames
 @section Finding All Frames
 @cindex frames, scanning all
@@ -1962,12 +2322,29 @@ This function returns a list of just the currently visible frames.
 visible, even though only the selected one is actually displayed.
 @end defun
 
+@defun frame-list-z-order &optional display
+This function returns a list of Emacs' frames, in Z (stacking) order
+(@pxref{Raising and Lowering}).  The optional argument @var{display}
+specifies which display to poll.  @var{display} should be either a frame
+or a display name (a string).  If omitted or @code{nil}, that stands for
+the selected frame's display.  It returns @code{nil} if @var{display}
+contains no Emacs frame.
+
+Frames are listed from topmost (first) to bottommost (last).  As a
+special case, if @var{display} is non-@code{nil} and specifies a live
+frame, it returns the child frames of that frame in Z (stacking) order.
+
+This function is not meaningful on text terminals.
+@end defun
+
 @defun next-frame &optional frame minibuf
 This function lets you cycle conveniently through all the frames on a
 specific terminal from an arbitrary starting point.  It returns the
 frame following @var{frame}, in the list of all live frames, on
 @var{frame}'s terminal.  The argument @var{frame} must specify a live
-frame and defaults to the selected frame.
+frame and defaults to the selected frame.  It never returns a frame
+whose @code{no-other-frame} parameter (@pxref{Frame Interaction
+Parameters}) is non-@code{nil}.
 
 The second argument, @var{minibuf}, says which frames to consider:
 
@@ -1998,8 +2375,8 @@ Window Ordering}.
 @section Minibuffers and Frames
 
 Normally, each frame has its own minibuffer window at the bottom, which
-is used whenever that frame is selected.  If the frame has a minibuffer,
-you can get it with @code{minibuffer-window} (@pxref{Minibuffer Windows}).
+is used whenever that frame is selected.  You can get that window with
+the function @code{minibuffer-window} (@pxref{Minibuffer Windows}).
 
 @cindex frame without a minibuffer
 @cindex surrogate minibuffer frame
@@ -2009,9 +2386,10 @@ will serve as @dfn{surrogate minibuffer frame} for this frame and cannot
 be deleted via @code{delete-frame} (@pxref{Deleting Frames}) as long as
 this frame is live.
 
-When you create the frame, you can explicitly specify the minibuffer
-window to use (in some other frame).  If you don't, then the minibuffer
-is found in the frame which is the value of the variable
+When you create the frame, you can explicitly specify its minibuffer
+window (in some other frame) with the @code{minibuffer} frame parameter
+(@pxref{Buffer Parameters}).  If you don't, then the minibuffer is found
+in the frame which is the value of the variable
 @code{default-minibuffer-frame}.  Its value should be a frame that does
 have a minibuffer.
 
@@ -2026,13 +2404,14 @@ the current terminal and cannot be buffer-local.  @xref{Multiple
 Terminals}.
 @end defvar
 
+
 @node Input Focus
 @section Input Focus
 @cindex input focus
-@c @cindex selected frame    Duplicates selected-frame, same for selected-window.
+@cindex selected frame
 
-At any time, one frame in Emacs is the @dfn{selected frame}.  The selected
-window always resides on the selected frame.
+At any time, one frame in Emacs is the @dfn{selected frame}.  The
+selected window always resides on the selected frame.
 
 When Emacs displays its frames on several terminals (@pxref{Multiple
 Terminals}), each terminal has its own selected frame.  But only one
@@ -2077,6 +2456,26 @@ same meaning as for @code{select-frame} (see below).  The return value
 of this function is not significant.
 @end defun
 
+Ideally, the function described next should focus a frame without also
+raising it above other frames.  Unfortunately, many window-systems or
+window managers may refuse to comply.
+
+@defun x-focus-frame &optional frame noactivate
+This function gives @var{frame} the focus of the X server without
+necessarily raising it.  @var{frame} @code{nil} means use the selected
+frame.  Under X, the optional argument @var{noactivate}, if
+non-@code{nil}, means to avoid making @var{frame}'s window-system window
+the ``active'' window which should insist a bit more on avoiding to
+raise @var{frame} above other frames.
+
+On Windows the @var{noactivate} argument has no effect.  However, if
+@var{frame} is a child frame (@pxref{Child Frames}), this function
+usualy does focus @var{frame} without raising it above other child
+frames.
+
+If there is no window system support, this function does nothing.
+@end defun
+
 @deffn Command select-frame frame &optional norecord
 This function selects frame @var{frame}, temporarily disregarding the
 focus of the X server if any.  The selection of @var{frame} lasts until
@@ -2091,7 +2490,7 @@ becomes the selected terminal.  This function then calls
 @code{select-window} as a subroutine, passing the window selected
 within @var{frame} as its first argument and @var{norecord} as its
 second argument (hence, if @var{norecord} is non-@code{nil}, this
-avoids changing the order of recently selected windows nor the buffer
+avoids changing the order of recently selected windows and the buffer
 list).  @xref{Selecting Windows}.
 
 This function returns @var{frame}, or @code{nil} if @var{frame} has
@@ -2147,20 +2546,64 @@ change it.
 @end defun
 
 @defvar focus-in-hook
-This is a normal hook run when an Emacs frame gains input focus.
+This is a normal hook run when an Emacs frame gains input focus.  The
+frame gaining focus is selected when this hook is run.
 @end defvar
 
 @defvar focus-out-hook
-This is a normal hook run when an Emacs frame loses input focus.
+This is a normal hook run when an Emacs frame has lost input focus and
+no other Emacs frame has gained input focus instead.
 @end defvar
 
 @defopt focus-follows-mouse
-This option is how you inform Emacs whether the window manager transfers
-focus when the user moves the mouse.  Non-@code{nil} says that it does.
-When this is so, the command @code{other-frame} moves the mouse to a
-position consistent with the new selected frame.
+This option informs Emacs whether and how the window manager transfers
+focus when you move the mouse pointer into a frame.  It can have three
+meaningful values:
+
+@table @asis
+@item @code{nil}
+The default value @code{nil} should be used when your window manager
+follows a ``click-to-focus'' policy where you have to click the mouse
+inside of a frame in order for that frame to gain focus.
+
+@item @code{t}
+The value @code{t} should be used when your window manager has the focus
+automatically follow the position of the mouse pointer but a frame that
+gains focus is not raised automatically and may even remain occluded by
+other window-system windows.
+
+@item @code{auto-raise}
+The value @code{auto-raise} should be used when your window manager has
+the focus automatically follow the position of the mouse pointer and a
+frame that gains focus is raised automatically.
+@end table
+
+If this option is non-@code{nil}, Emacs moves the mouse pointer to the
+frame selected by @code{select-frame-set-input-focus}.  That function is
+used by a number of commands like, for example, @code{other-frame} and
+@code{pop-to-buffer}.
+
+The distinction between the values @code{t} and @code{auto-raise} is not
+needed for ``normal'' frames because the window manager usually takes
+care of raising them.  It is useful to automatically raise child frames
+via @code{mouse-autoselect-window} (@pxref{Mouse Window
+Auto-selection}).
+
+Note that this option does not distinguish ``sloppy'' focus (where the
+frame that previously had focus retains focus as long as the mouse
+pointer does not move into another window manager window) from
+``strict'' focus (where a frame immediately loses focus when it's left
+by the mouse pointer).  It neither recognizes whether your window
+manager supports delayed focusing or auto-raising where you can
+explicitly specify the time until a new frame gets focus or is
+auto-raised.
+
+You can supply a ``focus follows mouse'' policy for individual Emacs
+windows by customizing the variable @code{mouse-autoselect-window}
+(@pxref{Mouse Window Auto-selection}).
 @end defopt
 
+
 @node Visibility of Frames
 @section Visibility of Frames
 @cindex visible frame
@@ -2169,16 +2612,26 @@ position consistent with the new selected frame.
 @cindex minimized frame
 @cindex frame visibility
 
-A frame on a graphical display may be @dfn{visible}, @dfn{invisible},
-or @dfn{iconified}.  If it is visible, its contents are displayed in
-the usual manner.  If it is iconified, its contents are not displayed,
-but there is a little icon somewhere to bring the frame back into view
-(some window managers refer to this state as @dfn{minimized} rather
-than @dfn{iconified}, but from Emacs' point of view they are the same
-thing).  If a frame is invisible, it is not displayed at all.
+A frame on a graphical display may be @dfn{visible}, @dfn{invisible}, or
+@dfn{iconified}.  If it is visible, its contents are displayed in the
+usual manner.  If it is iconified, its contents are not displayed, but
+there is a little icon somewhere to bring the frame back into view (some
+window managers refer to this state as @dfn{minimized} rather than
+@dfn{iconified}, but from Emacs' point of view they are the same thing).
+If a frame is invisible, it is not displayed at all.
+
+@cindex mapped frame
+@cindex unmapped frame
+  The concept of visibility is strongly related to that of (un-)mapped
+frames.  A frame (or, more precisely, its window-system window) is and
+becomes @dfn{mapped} when it is displayed for the first time and
+whenever it changes its state of visibility from @code{iconified} or
+@code{invisible} to @code{visible}.  Conversely, a frame is and becomes
+@dfn{unmapped} whenever it changes its status from @code{visible} to
+@code{iconified} or @code{invisible}.
 
   Visibility is meaningless on text terminals, since only the selected
-one is actually displayed in any case.
+frame is actually displayed in any case.
 
 @defun frame-visible-p frame
 This function returns the visibility status of frame @var{frame}.  The
@@ -2192,22 +2645,28 @@ purposes of this function, even though only one frame is displayed.
 
 @deffn Command iconify-frame &optional frame
 This function iconifies frame @var{frame}.  If you omit @var{frame}, it
-iconifies the selected frame.
+iconifies the selected frame.  This usually makes all child frames of
+@var{frame} (and their descendants) invisible (@pxref{Child Frames}).
 @end deffn
 
 @deffn Command make-frame-visible &optional frame
-This function makes frame @var{frame} visible.  If you omit
-@var{frame}, it makes the selected frame visible.  This does not raise
-the frame, but you can do that with @code{raise-frame} if you wish
-(@pxref{Raising and Lowering}).
+This function makes frame @var{frame} visible.  If you omit @var{frame},
+it makes the selected frame visible.  This does not raise the frame, but
+you can do that with @code{raise-frame} if you wish (@pxref{Raising and
+Lowering}).
+
+Making a frame visible usually makes all its child frames (and their
+descendants) visible too (@pxref{Child Frames}).
 @end deffn
 
 @deffn Command make-frame-invisible &optional frame force
 This function makes frame @var{frame} invisible.  If you omit
-@var{frame}, it makes the selected frame invisible.
+@var{frame}, it makes the selected frame invisible.  Usually, this makes
+all child frames of @var{frame} (and their descendants) invisible too
+(@pxref{Child Frames}).
 
 Unless @var{force} is non-@code{nil}, this function refuses to make
-@var{frame} invisible if all other frames are invisible..
+@var{frame} invisible if all other frames are invisible.
 @end deffn
 
   The visibility status of a frame is also available as a frame
@@ -2223,27 +2682,79 @@ being rendered with double buffering.  @var{frame} defaults to the
 selected frame.
 @end defun
 
+
 @node Raising and Lowering
-@section Raising and Lowering Frames
+@section Raising, Lowering and Restacking Frames
 
 @cindex raising a frame
 @cindex lowering a frame
-  Most window systems use a desktop metaphor.  Part of this metaphor
-is the idea that system-level windows (e.g., Emacs frames) are
-stacked in a notional third dimension perpendicular to the screen
-surface.  Where two overlap, the one higher up covers the one
-underneath.  You can @dfn{raise} or @dfn{lower} a frame using the
-functions @code{raise-frame} and @code{lower-frame}.
+@cindex restacking a frame
+@cindex frame stacking order
+@cindex frame Z-order
+  Most window systems use a desktop metaphor.  Part of this metaphor is
+the idea that system-level windows (representing, e.g., Emacs frames)
+are stacked in a notional third dimension perpendicular to the screen
+surface.  The order induced by stacking is total and usually referred to
+as stacking (or Z-) order.  Where the areas of two windows overlap, the
+one higher up in that order will (partially) cover the one underneath.
+
+  You can @dfn{raise} a frame to the top of that order or @dfn{lower} a
+frame to its bottom by using the functions @code{raise-frame} and
+@code{lower-frame}.  You can @dfn{restack} a frame directly above or
+below another frame using the function @code{frame-restack}.
+
+  Note that all functions described below will respect the adherence of
+frames (and all other window-system windows) to their respective z-group
+(@pxref{Position Parameters}).  For example, you usually cannot lower a
+frame below that of the desktop window and you cannot raise a frame
+whose @code{z-group} parameter is @code{nil} above the window-system's
+taskbar or tooltip window.
 
 @deffn Command raise-frame &optional frame
-This function raises frame @var{frame} (default, the selected frame).
-If @var{frame} is invisible or iconified, this makes it visible.
+This function raises frame @var{frame} (default, the selected frame)
+above all other frames belonging to the same or a lower z-group as
+@var{frame}.  If @var{frame} is invisible or iconified, this makes it
+visible.  If @var{frame} is a child frame (@pxref{Child Frames}), this
+raises @var{frame} above all other child frames of its parent.
 @end deffn
 
 @deffn Command lower-frame &optional frame
-This function lowers frame @var{frame} (default, the selected frame).
+This function lowers frame @var{frame} (default, the selected frame)
+below all other frames belonging to the same or a higher z-group as
+@var{frame}.  If @var{frame} is a child frame (@pxref{Child Frames}),
+this lowers @var{frame} below all other child frames of its parent.
 @end deffn
 
+@defun frame-restack frame1 frame2 &optional above
+This function restacks @var{frame1} below @var{frame2}.  This implies
+that if both frames are visible and their display areas overlap,
+@var{frame2} will (partially) obscure @var{frame1}.  If the optional
+third argument @var{above} is non-@code{nil}, this function restacks
+@var{frame1} above @var{frame2}.  This means that if both frames are
+visible and their display areas overlap, @var{frame1} will (partially)
+obscure @var{frame2}.
+
+Technically, this function may be thought of as an atomic action
+performed in two steps: The first step removes @var{frame1}'s
+window-system window from the display.  The second step reinserts
+@var{frame1}'s window into the display below (above if @var{above} is
+true) that of @var{frame2}.  Hence the position of @var{frame2} in its
+display's Z (stacking) order relative to all other frames excluding
+@var{frame1} remains unaltered.
+
+Some window managers may refuse to restack windows.
+@end defun
+
+Note that the effect of restacking will only hold as long as neither of
+the involved frames is iconified or made invisible.  You can use the
+@code{z-group} (@pxref{Position Parameters}) frame parameter to add a
+frame to a group of frames permanently shown above or below other
+frames.  As long as a frame belongs to one of these groups, restacking
+it will only affect its relative stacking position within that group.
+The effect of restacking frames belonging to different z-groups is
+undefined.  You can list frames in their current stacking order with the
+function @code{frame-list-z-order} (@pxref{Finding All Frames}).
+
 @defopt minibuffer-auto-raise
 If this is non-@code{nil}, activation of the minibuffer raises the frame
 that the minibuffer window is in.
@@ -2265,6 +2776,7 @@ or @code{nil} (meaning the selected frame's terminal).  If it does not
 refer to a text terminal, the return value is @code{nil}.
 @end defun
 
+
 @node Frame Configurations
 @section Frame Configurations
 @cindex frame configuration
@@ -2288,6 +2800,135 @@ Ordinarily, this function deletes all existing frames not listed in
 unwanted frames are iconified instead.
 @end defun
 
+
+@node Child Frames
+@section Child Frames
+@cindex child frames
+@cindex parent frames
+
+On some window-systems the @code{parent-frame} parameter (@pxref{Frame
+Interaction Parameters}) can be used to make a frame a child of the
+frame specified by that parameter.  The frame specified by that
+parameter will then be the frame's parent frame as long as the parameter
+is not changed or reset.  Technically, this makes the child frame's
+window-system window a child window of the parent frame's window-system
+window.
+
+  The @code{parent-frame} parameter can be changed at any time.  Setting
+it to another frame ``reparents'' the child frame.  Setting it to
+another child frame makes the frame a ``nested'' child frame.  Setting
+it to @code{nil} restores the frame's status as a top-level frame---one
+whose window-system window is a child of its display's root window.
+
+  Since child frames can be arbitrarily nested, a frame can be both a
+child and a parent frame.  Also, the relative roles of child and parent
+frame may be reversed at any time (though it's usually a good idea to
+keep the size of child frames sufficiently smaller than that of their
+parent).  An error will be signalled for the attempt to make a frame an
+ancestor of itself.
+
+  A child frame is clipped at the native edges (@pxref{Frame Geometry})
+of its parent frame---everything outside these edges is invisible.  Its
+@code{left} and @code{top} parameters specify positions relative to the
+top-left corner of its parent's native frame.  When either of the frames
+is resized, the relative position of the child frame remains unaltered.
+Hence, resizing either of these frames can hide or reveal parts of the
+child frame.
+
+  Usually, moving a parent frame moves along all its child frames and
+their descendants as well, keeping their relative positions unaltered.
+The hook @code{move-frame-functions} (@pxref{Frame Position}) is run for
+a child frame only when the position of the child frame relative to its
+parent frame changes.  When a parent frame is resized, the child frame
+retains its position respective to the left and upper native edges of
+its parent.  In this case, the position respective to the lower or right
+native edge of the parent frame is usually lost.
+
+  A visible child frame always appears on top of its parent frame thus
+obscuring parts of it.  This is comparable to the window-system window
+of a top-level frame which also always appears on top of its parent
+window---the desktop's root window.  When a parent frame is iconified or
+made invisible (@pxref{Visibility of Frames}), its child frames are made
+invisible.  When a parent frame is deiconified or made visible, its
+child frames are made visible.  When a parent frame is about to be
+deleted, (@pxref{Deleting Frames}) its child frames are recursively
+deleted before it.
+
+  Whether a child frame can have a menu or tool bar is window-system or
+window manager dependent.  Most window-systems explicitly disallow menus
+bars for child frames.  It seems advisable to disable both, menu and
+tool bars, via the frame's initial parameters settings.
+
+  Usually, child frames do not exhibit window manager decorations like a
+title bar or external borders (@pxref{Frame Geometry}).  When the child
+frame does not show a menu or tool bar, any other of the frame's borders
+(@pxref{Layout Parameters}) can be used instead of the external borders.
+
+  In particular, under X (but not when building with GTK+), the frame's
+outer border can be used.  On Windows, specifying a non-zero outer
+border width will show a one pixel wide external border.  Under all
+window-systems, the internal border can be used.  In either case, it's
+advisable to disable a child frame's window manager decorations with the
+@code{undecorated} frame parameter @pxref{Management Parameters}).
+
+  The behavior of child frames deviates from that of top-level frames in
+a number of other ways as well.  Here we sketch a few of them:
+
+@itemize @bullet
+@item
+The semantics of maximizing and iconifying child frames is highly
+window-system dependent.  As a rule, applications should never invoke
+these operations for child frames.
+
+@item
+Raising, lowering and restacking child frames (@pxref{Raising and
+Lowering}) or changing the @code{z-group} (@pxref{Position Parameters})
+of a child frame changes only the stacking order of child frames with
+the same parent.
+
+@item
+Many window-systems are not able to change the opacity (@pxref{Font and
+Color Parameters}) of child frames.
+
+@item
+Transferring focus from a child frame to an ancestor that is not its
+parent by clicking with the mouse in a visible part of that ancestor's
+window may fail with some window-systems.  You may have to click into
+the direct parent's window-system window first.
+
+@item
+Window managers might not bother to extend their focus follows mouse
+policy to child frames.  Customizing @code{mouse-autoselect-window} can
+help in this regard (@pxref{Mouse Window Auto-selection}).
+
+@item
+Dropping (@pxref{Drag and Drop}) on child frames is not guaranteed too
+work on all window-systems.  Some will drop the object on the parent
+frame or some ancestor instead.
+@end itemize
+
+  The following two functions may be useful when working with child and
+parent frames:
+
+@defun frame-parent &optional frame
+This function returns the parent frame of @var{frame}.  The parent frame
+of @var{frame} is the Emacs frame whose window-system window is the
+parent window of @var{frame}'s window-system window.  If such a frame
+exists, @var{frame} is considered a child frame of that frame.
+
+This function returns @code{nil} if @var{frame} has no parent frame.
+@end defun
+
+@defun frame-ancestor-p &optional ancestor descendant
+This functions returns non-@code{nil} if @var{ancestor} is an ancestor
+of @var{descendant}.  @var{ancestor} is an ancestor of @var{descendant}
+when it is either @var{descendant}'s parent frame or it is an ancestor
+of @var{descendant}'s parent frame.  Both, @var{ancestor} and
+@var{descendant} must specify live frames and default to the selected
+frame.
+@end defun
+
+
 @node Mouse Tracking
 @section Mouse Tracking
 @cindex mouse tracking
@@ -3203,9 +3844,3 @@ ever be developed and distributed noncommercially.
 This variable's value is @code{t} if no X window manager is in use.
 @end defvar
 @end ignore
-
-@ignore
-@item
-The functions @code{x-pixel-width} and @code{x-pixel-height} return the
-width and height of an X Window frame, measured in pixels.
-@end ignore
diff --git a/doc/lispref/windows.texi b/doc/lispref/windows.texi
index 6aa9591e09f..931d1060d5d 100644
--- a/doc/lispref/windows.texi
+++ b/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.
-
-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.
+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.
+
+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
-- 
2.39.2