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

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

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

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

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

[Eli Zaretskii]

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

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

[Richard Stallman]

[[[ 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)

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

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

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

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

[Eli Zaretskii]

> From: Richard Stallman <rms@gnu.org>
> Date: Wed, 01 Jul 2020 23:47:13 -0400
> Cc: 42154@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.

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

[Eli Zaretskii]

> From: Kevin Vigouroux <ke.vigouroux@laposte.net>
> Cc: 42154@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.

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

[Eli Zaretskii]

> Date: Thu, 02 Jul 2020 16:03:17 +0300
> From: Eli Zaretskii <eliz@gnu.org>
> Cc: ke.vigouroux@laposte.net, 42154@debbugs.gnu.org
> 
> > From: Richard Stallman <rms@gnu.org>
> > Date: Wed, 01 Jul 2020 23:47:13 -0400
> > Cc: 42154@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.

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

[Richard Stallman]

[[[ 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)

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

[Eli Zaretskii]

> From: Richard Stallman <rms@gnu.org>
> Cc: 42154@debbugs.gnu.org, eliz@gnu.org, ke.vigouroux@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.