From: Martin Rudalics <rudalics@gmx.at>
Date: Sun, 19 Dec 2021 16:59:15 +0000 (+0100)
Subject: Clarify description of two mouse dragging parameters (Bug#52537)
X-Git-Tag: emacs-28.0.91~40
X-Git-Url: http://git.eshelyaron.com/gitweb/?a=commitdiff_plain;h=f11b996a3c;p=emacs.git

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).
---

diff --git a/doc/lispref/frames.texi b/doc/lispref/frames.texi
index 56ac7118135..756f2745d69 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