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

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

[Kevin Vigouroux via Bug reports for GNU Emacs, the Swiss army knife of text editors]

In the Emacs Lisp Reference Manual, section 29.14 Child Frames, 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.  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.

#+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.
     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.
     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.
-- 
Best regards,
Kevin Vigouroux

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

[Eli Zaretskii]

> Date: Thu, 16 Dec 2021 06:58:35 +0100
> From:  Kevin Vigouroux via "Bug reports for GNU Emacs,
>  the Swiss army knife of text editors" <bug-gnu-emacs@gnu.org>
> 
> In the Emacs Lisp Reference Manual, section 29.14 Child Frames, 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.  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.
> 
> #+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.
>      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.
>      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.

Maybe I'm missing something, but I don't necessarily see the error in
the first text vs the second one.  Could you please point out the
part(s) that is/are incorrect there?  (Having one description be
general and another more specific and accurate is not a problem, it's
how our manuals are written in general.)

Thanks.

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

[martin rudalics]

 > 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

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

[Kevin Vigouroux via Bug reports for GNU Emacs, the Swiss army knife of text editors]

Indeed, I find the wording ambivalent. It could be rephrased like this.

#+begin_quote
The ‘top-visible’ parameter specifies that the number of pixels is /the
*top area* of the child frame that *always* remain visible/ within the
parent’s native frame during dragging [...] The ‘bottom-visible’
parameters specifies that the number of pixels is /the *bottom area* of
the child frame that *always* remain visible/ within the parent’s native
frame during dragging [...].
#+end_quote

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

[Kevin Vigouroux via Bug reports for GNU Emacs, the Swiss army knife of text editors]

P.S.: I forgot to mention that “minimum” area about the (top/bottom)
visible area. Please, take into account this adjective.

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

[Kevin Vigouroux via Bug reports for GNU Emacs, the Swiss army knife of text editors]

I am somewhat dyspraxic so making things as clear as possible keeps me
from getting confused about directions (space).
-- 
Best regards,
Kevin Vigouroux

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

[Lars Ingebrigtsen]

martin rudalics <rudalics@gmx.at> writes:

> 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?

Kevin Vigouroux <ke.vigouroux@laposte.net> writes:

> I am somewhat dyspraxic so making things as clear as possible keeps me
> from getting confused about directions (space).

Reading the documentation, it seems pretty clear to me?  The proposed
changed didn't make things any clearer (to me, at least), so I'm not
sure whether there's anything actionable in this bug report?

-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no

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

[martin rudalics]

close 52537 28.1
quit

> I am somewhat dyspraxic so making things as clear as possible keeps me
> from getting confused about directions (space).

I checked in a fix on the release branch that should clarify things.
Closing this bug.

Thanks, martin