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

Previous Next

To add a comment to this bug, you must first unarchive it, by sending
a message to control AT debbugs.gnu.org, with unarchive 52537 in the body.
You can then email your comments to 52537 AT debbugs.gnu.org in the normal way.

Toggle the display of automated, internal messages from the tracker.

Message #5 received at submit <at> debbugs.gnu.org (full text, mbox):

From: Kevin Vigouroux <ke.vigouroux <at> laposte.net>
To: bug-gnu-emacs <at> gnu.org
Subject: [DOC] ‘top-visible’ and
 ‘bottom-visible’ (erroneous indications)
Date: Thu, 16 Dec 2021 06:58:35 +0100

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

Message #8 received at submit <at> debbugs.gnu.org (full text, mbox):

From: Eli Zaretskii <eliz <at> gnu.org>
To: Kevin Vigouroux <ke.vigouroux <at> laposte.net>
Cc: bug-gnu-emacs <at> gnu.org
Subject: Re: bug#52537: [DOC] ‘top-visible’ and
 ‘bottom-visible’ (erroneous indications)
Date: Thu, 16 Dec 2021 10:15:06 +0200

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

Message #11 received at submit <at> debbugs.gnu.org (full text, mbox):

From: martin rudalics <rudalics <at> gmx.at>
To: bug-gnu-emacs <at> gnu.org
Subject: Re: bug#52537: [DOC] ‘top-visible’ and ‘bottom-visible’ (erroneous indications)
Date: Thu, 16 Dec 2021 09:43:01 +0100

> 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

Message #14 received at submit <at> debbugs.gnu.org (full text, mbox):

From: Kevin Vigouroux <ke.vigouroux <at> laposte.net>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: bug-gnu-emacs <at> gnu.org
Subject: Re: bug#52537: [DOC] ‘top-visible’ and
 ‘bottom-visible’ (erroneous indications)
Date: Thu, 16 Dec 2021 12:11:14 +0100

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

Message #17 received at submit <at> debbugs.gnu.org (full text, mbox):

From: Kevin Vigouroux <ke.vigouroux <at> laposte.net>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: bug-gnu-emacs <at> gnu.org
Subject: Re: bug#52537: [DOC] ‘top-visible’ and
 ‘bottom-visible’ (erroneous indications)
Date: Thu, 16 Dec 2021 12:20:33 +0100

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

Message #20 received at submit <at> debbugs.gnu.org (full text, mbox):

From: Kevin Vigouroux <ke.vigouroux <at> laposte.net>
To: bug-gnu-emacs <at> gnu.org
Subject: Re: bug#52537: [DOC] ‘top-visible’ and
 ‘bottom-visible’ (erroneous indications)
Date: Thu, 16 Dec 2021 12:35:32 +0100

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

Message #23 received at 52537 <at> debbugs.gnu.org (full text, mbox):

From: Lars Ingebrigtsen <larsi <at> gnus.org>
To: martin rudalics <rudalics <at> gmx.at>
Cc: 52537 <at> debbugs.gnu.org
Subject: Re: bug#52537: [DOC] ‘top-visible’ and
 ‘bottom-visible’ (erroneous indications)
Date: Sun, 19 Dec 2021 13:11:40 +0100

martin rudalics <rudalics <at> 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 <at> 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

Message #28 received at submit <at> debbugs.gnu.org (full text, mbox):

From: martin rudalics <rudalics <at> gmx.at>
To: bug-gnu-emacs <at> gnu.org
Subject: Re: bug#52537: [DOC] ‘top-visible’ and ‘bottom-visible’ (erroneous indications)
Date: Sun, 19 Dec 2021 18:04:37 +0100

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

Previous Next

GNU bug tracking system
Copyright (C) 1999 Darren O. Benham, 1997,2003 nCipher Corporation Ltd, 1994-97 Ian Jackson.