master 152b94e: Merge from origin/emacs-28

[Stefan Kangas]

branch: master
commit 152b94ed0f57e81563b5dab34ee0183ecfac9394
Merge: 1ffb757 16ed9fa
Author: Stefan Kangas <stefan@marxist.se>
Commit: Stefan Kangas <stefan@marxist.se>

    Merge from origin/emacs-28
    
    16ed9fad2c ; * doc/lispref/frames.texi (Child Frames): Improve wording.
    f11b996a3c Clarify description of two mouse dragging parameters (Bug#...
---
 doc/lispref/frames.texi | 30 ++++++++++++++++--------------
 1 file changed, 16 insertions(+), 14 deletions(-)

diff --git a/doc/lispref/frames.texi b/doc/lispref/frames.texi
index 712c842..3708ef9 100644
--- a/doc/lispref/frames.texi
+++ b/doc/lispref/frames.texi
@@ -3362,20 +3362,22 @@ are handy (@pxref{Window Parameters}).  These allow to 
remove an
 unwanted mode line (when @code{drag-with-header-line} is chosen) and to
 remove mouse-sensitive areas which might interfere with frame dragging.
 
-  To avoid that dragging moves a frame completely out of its parent's
-native frame, something which might happen when the mouse cursor
-overshoots and makes the frame difficult to retrieve once the mouse
-button has been released, it is advisable to set the frame's
-@code{top-visible} or @code{bottom-visible} parameter correspondingly.
-
-  The @code{top-visible} parameter specifies the number of pixels at the
-top of the frame that always remain visible within the parent's native
-frame during dragging and should be set when specifying a non-@code{nil}
-@code{drag-with-header-line} parameter.  The @code{bottom-visible}
-parameter specifies the number of pixels at the bottom of the frame that
-always remain visible within the parent's native frame during dragging
-and should be preferred when specifying a non-@code{nil}
-@code{drag-with-mode-line} parameter.
+  When the user drags a frame with a mouse and overshoots, it's easy
+to drag a frame out of the screen area of its parent.  Retrieving such
+a frame can be hairy once the mouse button has been released.  To
+prevent such a situation, it is advisable to set the frame's
+@code{top-visible} or @code{bottom-visible} parameter (@pxref{Mouse
+Dragging Parameters}).
+
+  Set the @code{top-visible} parameter of a child frame to a number
+when you intend to allow the user dragging that frame by its header
+line.  Setting @code{top-visible} to a number inhibits dragging the
+top edge of the child frame above the top edge of its parent.  Set the
+@code{bottom-visible} parameter to a number when you intend to drag
+that frame via its mode line; this inhibits dragging the bottom edge
+of the child frame beneath the bottom edge of its parent.  In either
+case, that number also specifies width and height (in pixels) of the
+area of the child frame that remains visible during dragging.
 
   When a child frame is used for displaying a buffer via
 @code{display-buffer-in-child-frame} (@pxref{Buffer Display Action