emacs-28 f11b996: Clarify description of two mouse dragging parameters (Bug#52537)

[Martin Rudalics]

branch: emacs-28
commit f11b996a3c7fad35d9a1221d06abcd28242bd16c
Author: Martin Rudalics <rudalics@gmx.at>
Commit: Martin Rudalics <rudalics@gmx.at>

    Clarify description of two mouse dragging parameters (Bug#52537)
    
    * doc/lispref/frames.texi (Child Frames): Clarify description of
    'top-visible' and 'bottom-visible' parameters (Bug#52537).
---
 doc/lispref/frames.texi | 28 ++++++++++++++--------------
 1 file changed, 14 insertions(+), 14 deletions(-)

diff --git a/doc/lispref/frames.texi b/doc/lispref/frames.texi
index 56ac711..756f274 100644
--- a/doc/lispref/frames.texi
+++ b/doc/lispref/frames.texi
@@ -3343,20 +3343,20 @@ 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 mouse cursor 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 drag that frame via its header line.  This 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