bug#52537: [DOC] ‘top-visible’ and ‘bottom-visible’ (erroneous indications)

[martin rudalics <rudalics@gmx.at>]

 > In the Emacs Lisp Reference Manual, section 29.14 Child Frames,

This is section 30.14 in Emacs 28.

 > a
 > paragraph contains some errors about ‘top-visible’ and ‘bottom-visible’.
 >
 > #+begin_quote
 > The ‘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-‘nil’
 > ‘drag-with-header-line’ parameter.

Although the description is not overly exhaustive, I cannot see an error
here.  When I do (set-frame-parameter nil 'top-visible 100) for a child
frame with a header line and mouse-drag that frame via the header line
towards the bottom edge of its parent frame, at least 100 pixels of that
frame will remain visible.

 > The ‘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-‘nil’ ‘drag-with-mode-line’
 > parameter.
 > #+end_quote
 >
 > The correct description is given in the Emacs Lisp Reference
 > Manual, section 29.4.3.7 Mouse Dragging Parameters.

Which has become section 30.4.3.7 in Emacs 28.

 > #+begin_quote
 > ‘top-visible’
 >       If this parameter is a number, >>the top edge of the frame never
 >       appears above the top edge<< of its display or parent frame.

Do you mean this part should be mentioned in section 30.14 too ...

 >       Moreover, as many pixels of the frame as specified by that number
 >       will remain visible >>when the frame is moved against any of the
 >       remaining edges<< of its display or parent frame.  Setting this
 >       parameter is useful to guard against dragging a child frame with a
 >       non-‘nil’ ‘drag-with-header-line’ parameter completely out of the
 >       area of its parent frame.
 >
 > ‘bottom-visible’
 >       If this parameter is a number, >>the bottom edge of the frame never
 >       appears below the bottom edge<< of its display or parent frame.

... and also this part?

 >       Moreover, as many pixels of the frame as specified by that number
 >       will remain visible >>when the frame is moved against any of the
 >       remaining edges<< of its display or parent frame.  Setting this
 >       parameter is useful to guard against dragging a child frame with a
 >       non-‘nil’ ‘drag-with-mode-line’ parameter completely out of the
 >       area of its parent frame.
 > #+end_quote
 >
 > We may move the child frame with the mouse but not above (below) the top
 > (bottom) edge of the native frame of the parent frame: this is the role
 > of ‘top-visible’ (‘bottom-visible’) parameter.

Please elaborate: Is it "just" that these two parts are missing from the
Child Frames section (in which case I will happily add them there) or is
there a more intrinsic error in that section?

Thanks, martin