unofficial mirror of bug-gnu-emacs@gnu.org 
 help / color / mirror / code / Atom feed
* bug#52537: [DOC] ‘top-visible’ and ‘bottom-visible’ (erroneous indications)
@ 2021-12-16  5:58 Kevin Vigouroux via Bug reports for GNU Emacs, the Swiss army knife of text editors
  2021-12-16  8:15 ` Eli Zaretskii
  2021-12-16  8:43 ` martin rudalics
  0 siblings, 2 replies; 8+ messages in thread
From: Kevin Vigouroux via Bug reports for GNU Emacs, the Swiss army knife of text editors @ 2021-12-16  5:58 UTC (permalink / raw)
  To: 52537

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





^ permalink raw reply	[flat|nested] 8+ messages in thread

* bug#52537: [DOC] ‘top-visible’ and ‘bottom-visible’ (erroneous indications)
  2021-12-16  5:58 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
@ 2021-12-16  8:15 ` Eli Zaretskii
  2021-12-16 11:11   ` Kevin Vigouroux via Bug reports for GNU Emacs, the Swiss army knife of text editors
  2021-12-16  8:43 ` martin rudalics
  1 sibling, 1 reply; 8+ messages in thread
From: Eli Zaretskii @ 2021-12-16  8:15 UTC (permalink / raw)
  To: Kevin Vigouroux; +Cc: 52537

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





^ permalink raw reply	[flat|nested] 8+ messages in thread

* bug#52537: [DOC] ‘top-visible’ and ‘bottom-visible’ (erroneous indications)
  2021-12-16  5:58 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
  2021-12-16  8:15 ` Eli Zaretskii
@ 2021-12-16  8:43 ` martin rudalics
  2021-12-16 11:35   ` Kevin Vigouroux via Bug reports for GNU Emacs, the Swiss army knife of text editors
  2021-12-19 12:11   ` Lars Ingebrigtsen
  1 sibling, 2 replies; 8+ messages in thread
From: martin rudalics @ 2021-12-16  8:43 UTC (permalink / raw)
  To: 52537

 > 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






^ permalink raw reply	[flat|nested] 8+ messages in thread

* bug#52537: [DOC] ‘top-visible’ and ‘bottom-visible’ (erroneous indications)
  2021-12-16  8:15 ` Eli Zaretskii
@ 2021-12-16 11:11   ` Kevin Vigouroux via Bug reports for GNU Emacs, the Swiss army knife of text editors
  2021-12-16 11:20     ` Kevin Vigouroux via Bug reports for GNU Emacs, the Swiss army knife of text editors
  0 siblings, 1 reply; 8+ messages in thread
From: Kevin Vigouroux via Bug reports for GNU Emacs, the Swiss army knife of text editors @ 2021-12-16 11:11 UTC (permalink / raw)
  To: Eli Zaretskii; +Cc: 52537

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





^ permalink raw reply	[flat|nested] 8+ messages in thread

* bug#52537: [DOC] ‘top-visible’ and ‘bottom-visible’ (erroneous indications)
  2021-12-16 11:11   ` Kevin Vigouroux via Bug reports for GNU Emacs, the Swiss army knife of text editors
@ 2021-12-16 11:20     ` Kevin Vigouroux via Bug reports for GNU Emacs, the Swiss army knife of text editors
  0 siblings, 0 replies; 8+ messages in thread
From: Kevin Vigouroux via Bug reports for GNU Emacs, the Swiss army knife of text editors @ 2021-12-16 11:20 UTC (permalink / raw)
  To: Eli Zaretskii; +Cc: 52537

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





^ permalink raw reply	[flat|nested] 8+ messages in thread

* bug#52537: [DOC] ‘top-visible’ and ‘bottom-visible’ (erroneous indications)
  2021-12-16  8:43 ` martin rudalics
@ 2021-12-16 11:35   ` Kevin Vigouroux via Bug reports for GNU Emacs, the Swiss army knife of text editors
  2021-12-19 17:04     ` martin rudalics
  2021-12-19 12:11   ` Lars Ingebrigtsen
  1 sibling, 1 reply; 8+ messages in thread
From: Kevin Vigouroux via Bug reports for GNU Emacs, the Swiss army knife of text editors @ 2021-12-16 11:35 UTC (permalink / raw)
  To: 52537

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





^ permalink raw reply	[flat|nested] 8+ messages in thread

* bug#52537: [DOC] ‘top-visible’ and ‘bottom-visible’ (erroneous indications)
  2021-12-16  8:43 ` martin rudalics
  2021-12-16 11:35   ` Kevin Vigouroux via Bug reports for GNU Emacs, the Swiss army knife of text editors
@ 2021-12-19 12:11   ` Lars Ingebrigtsen
  1 sibling, 0 replies; 8+ messages in thread
From: Lars Ingebrigtsen @ 2021-12-19 12:11 UTC (permalink / raw)
  To: martin rudalics; +Cc: 52537

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





^ permalink raw reply	[flat|nested] 8+ messages in thread

* bug#52537: [DOC] ‘top-visible’ and ‘bottom-visible’ (erroneous indications)
  2021-12-16 11:35   ` Kevin Vigouroux via Bug reports for GNU Emacs, the Swiss army knife of text editors
@ 2021-12-19 17:04     ` martin rudalics
  0 siblings, 0 replies; 8+ messages in thread
From: martin rudalics @ 2021-12-19 17:04 UTC (permalink / raw)
  To: 52537

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







^ permalink raw reply	[flat|nested] 8+ messages in thread

end of thread, other threads:[~2021-12-19 17:04 UTC | newest]

Thread overview: 8+ messages (download: mbox.gz follow: Atom feed
-- links below jump to the message on this page --
2021-12-16  5:58 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
2021-12-16  8:15 ` Eli Zaretskii
2021-12-16 11:11   ` Kevin Vigouroux via Bug reports for GNU Emacs, the Swiss army knife of text editors
2021-12-16 11:20     ` Kevin Vigouroux via Bug reports for GNU Emacs, the Swiss army knife of text editors
2021-12-16  8:43 ` martin rudalics
2021-12-16 11:35   ` Kevin Vigouroux via Bug reports for GNU Emacs, the Swiss army knife of text editors
2021-12-19 17:04     ` martin rudalics
2021-12-19 12:11   ` Lars Ingebrigtsen

Code repositories for project(s) associated with this public inbox

	https://git.savannah.gnu.org/cgit/emacs.git

This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).