GNU bug report logs - #42154
26.3; [DOC] This wording is too complex: frame's window-system window.

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 42154 in the body.
You can then email your comments to 42154 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: 26.3; [DOC] This wording is too complex: frame's window-system window.
Date: Wed, 01 Jul 2020 18:21:22 +0200

Unfortunately, I do not know the English very well. What does the
following wording mean?

"If this is above, the **frame's window-system window** is displayed above
all other window-system windows that do not have the above property
set."

Reference: Elisp manual, 29.4.3.2 Position Parameters, c.f. "z-group".

Best regards,
Kevin Vigouroux

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

From: Eli Zaretskii <eliz <at> gnu.org>
To: Kevin Vigouroux <ke.vigouroux <at> laposte.net>
Cc: 42154 <at> debbugs.gnu.org
Subject: Re: bug#42154: 26.3;
 [DOC] This wording is too complex: frame's window-system window.
Date: Wed, 01 Jul 2020 19:49:46 +0300

> Date: Wed, 01 Jul 2020 18:21:22 +0200
> From: Kevin Vigouroux via "Bug reports for GNU Emacs,
>  the Swiss army knife of text editors" <bug-gnu-emacs <at> gnu.org>
> 
> Unfortunately, I do not know the English very well. What does the
> following wording mean?
> 
> "If this is above, the **frame's window-system window** is displayed above
> all other window-system windows that do not have the above property
> set."

Is the below more clear?

  If this is above, the window-system's window that corresponds to the
  frame is displayed above all other window-system's windows that do
  not have the above property set.

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

From: Richard Stallman <rms <at> gnu.org>
To: Kevin Vigouroux <ke.vigouroux <at> laposte.net>
Cc: 42154 <at> debbugs.gnu.org
Subject: Re: bug#42154: 26.3;
 [DOC] This wording is too complex: frame's window-system window.
Date: Wed, 01 Jul 2020 23:47:13 -0400

[[[ To any NSA and FBI agents reading my email: please consider    ]]]
[[[ whether defending the US Constitution against all enemies,     ]]]
[[[ foreign or domestic, requires you to follow Snowden's example. ]]]

  > "If this is above, the **frame's window-system window** is displayed above

One thing I notice is that this uses passive voice.
That tends to be harder to read; also, it leaves the
subject unstated, and that vagueness can hurt.

(I don't know what that doc string text means.)

-- 
Dr Richard Stallman
Chief GNUisance of the GNU Project (https://gnu.org)
Founder, Free Software Foundation (https://fsf.org)
Internet Hall-of-Famer (https://internethalloffame.org)

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

From: Kevin Vigouroux <ke.vigouroux <at> laposte.net>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: 42154 <at> debbugs.gnu.org
Subject: Re: bug#42154: 26.3;
 [DOC] This wording is too complex: frame's window-system window.
Date: Thu, 02 Jul 2020 14:15:09 +0200

Yes, it is more clear.

Can we replace the expression "window-system's window" by "graphical
application" if appropriate?

The former expression is a bit of jargon. See the following rewording.

   On a graphical terminal we distinguish two types of frames. A normal
"top-level frame" is a usual graphical application; this Emacs frame may
be directly managed by the window system. A child frame is a kind of
special frame that depends on another frame and is handled by Emacs.

[Elisp manual, chapter 19. Frames]

   On a graphical terminal we distinguish two types of frames: A normal
“top-level frame” is a frame whose window-system window is a child of
the window-system’s root window for that terminal.  A child frame is a
frame whose window-system window is the child of the window-system
window of another Emacs frame.  *Note Child Frames*.

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

From: Eli Zaretskii <eliz <at> gnu.org>
To: rms <at> gnu.org
Cc: ke.vigouroux <at> laposte.net, 42154 <at> debbugs.gnu.org
Subject: Re: bug#42154: 26.3;
 [DOC] This wording is too complex: frame's window-system window.
Date: Thu, 02 Jul 2020 16:03:17 +0300

> From: Richard Stallman <rms <at> gnu.org>
> Date: Wed, 01 Jul 2020 23:47:13 -0400
> Cc: 42154 <at> debbugs.gnu.org
> 
> One thing I notice is that this uses passive voice.
> That tends to be harder to read; also, it leaves the
> subject unstated, and that vagueness can hurt.

Is the below better?

  If this is 'above', the window-system displays the window that
  corresponds to the frame above all other window-system's windows
  that do not have the 'above' property set.

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

From: Eli Zaretskii <eliz <at> gnu.org>
To: Kevin Vigouroux <ke.vigouroux <at> laposte.net>
Cc: 42154 <at> debbugs.gnu.org
Subject: Re: bug#42154: 26.3;
 [DOC] This wording is too complex: frame's window-system window.
Date: Thu, 02 Jul 2020 16:30:14 +0300

> From: Kevin Vigouroux <ke.vigouroux <at> laposte.net>
> Cc: 42154 <at> debbugs.gnu.org
> Date: Thu, 02 Jul 2020 14:15:09 +0200
> 
> Yes, it is more clear.

Thanks, I will install it shortly.

> Can we replace the expression "window-system's window" by "graphical
> application" if appropriate?

AFAIU, that's inaccurate.  The intent here is that the Emacs frame is
"wrapped" by what is known in the GUI world as "window"; and the
window-system is X Window System or any equivalent windowing
environment.  (We explain what is a "window-system" elsewhere in the
manual.)

If you can suggest some wording that is more clear, but doesn't lose
the important point, please do.

Message #25 received at 42154-done <at> debbugs.gnu.org (full text, mbox):

From: Eli Zaretskii <eliz <at> gnu.org>
To: ke.vigouroux <at> laposte.net
Cc: 42154-done <at> debbugs.gnu.org, rms <at> gnu.org
Subject: Re: bug#42154: 26.3;
 [DOC] This wording is too complex: frame's window-system window.
Date: Sat, 04 Jul 2020 10:21:39 +0300

> Date: Thu, 02 Jul 2020 16:03:17 +0300
> From: Eli Zaretskii <eliz <at> gnu.org>
> Cc: ke.vigouroux <at> laposte.net, 42154 <at> debbugs.gnu.org
> 
> > From: Richard Stallman <rms <at> gnu.org>
> > Date: Wed, 01 Jul 2020 23:47:13 -0400
> > Cc: 42154 <at> debbugs.gnu.org
> > 
> > One thing I notice is that this uses passive voice.
> > That tends to be harder to read; also, it leaves the
> > subject unstated, and that vagueness can hurt.
> 
> Is the below better?
> 
>   If this is 'above', the window-system displays the window that
>   corresponds to the frame above all other window-system's windows
>   that do not have the 'above' property set.

I installed that rewording, and I'm marking this bug done.

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

From: Richard Stallman <rms <at> gnu.org>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: ke.vigouroux <at> laposte.net, eliz <at> gnu.org, 42154 <at> debbugs.gnu.org
Subject: Re: bug#42154: 26.3;
 [DOC] This wording is too complex: frame's window-system window.
Date: Sat, 04 Jul 2020 22:35:20 -0400

[[[ To any NSA and FBI agents reading my email: please consider    ]]]
[[[ whether defending the US Constitution against all enemies,     ]]]
[[[ foreign or domestic, requires you to follow Snowden's example. ]]]

  > > Is the below better?
  > > 
  > >   If this is 'above', the window-system displays the window that
  > >   corresponds to the frame above all other window-system's windows
  > >   that do not have the 'above' property set.

It is better, but still ambiguous in

    the window that
      > >   corresponds to the frame above all other window-system's windows

the frame above?
displays the window above?
Also, what does "above" mean here?  y axis?  z axis?

-- 
Dr Richard Stallman
Chief GNUisance of the GNU Project (https://gnu.org)
Founder, Free Software Foundation (https://fsf.org)
Internet Hall-of-Famer (https://internethalloffame.org)

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

From: Eli Zaretskii <eliz <at> gnu.org>
To: rms <at> gnu.org
Cc: ke.vigouroux <at> laposte.net, 42154 <at> debbugs.gnu.org
Subject: Re: bug#42154: 26.3;
 [DOC] This wording is too complex: frame's window-system window.
Date: Sun, 05 Jul 2020 17:33:02 +0300

> From: Richard Stallman <rms <at> gnu.org>
> Cc: 42154 <at> debbugs.gnu.org, eliz <at> gnu.org, ke.vigouroux <at> laposte.net
> Date: Sat, 04 Jul 2020 22:35:20 -0400
> 
>   > > Is the below better?
>   > > 
>   > >   If this is 'above', the window-system displays the window that
>   > >   corresponds to the frame above all other window-system's windows
>   > >   that do not have the 'above' property set.
> 
> It is better, but still ambiguous in
> 
>     the window that
>       > >   corresponds to the frame above all other window-system's windows
> 
> the frame above?
> displays the window above?

Concrete suggestions and patches are welcome.

> Also, what does "above" mean here?  y axis?  z axis?

This is explained in the preceding paragraph:

  ‘z-group’
       This parameter specifies a relative position of the frame’s
       window-system window in the stacking (Z-) order of the frame’s
       display.

Previous Next

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