Subject: bug#31031: 27.0; (elisp) `Position Parameters', floating-point values

From: martin rudalics <[email-masked]>
Date: Wed, 04 Apr 2018 09:51:06 +0200

> Yes.  But I'm not sure why you mention that here.
 > What might I be missing?

Because the desktop restore algorithm cannot restore the originally
intended positioning, namely flushing the frame to the right whatever
the size of the display is.

 > I have limited access to multiple monitors, myself.  The
 > manual says that the monitor that dominates a frame is
 > "the monitor that contains the largest part of the window"
 > ((elisp) `Creating Frames').  And:
 >
 >    A frame is “dominated” by a physical monitor when either the
 >    largest area of the frame resides in that monitor, or (if the frame
 >    does not intersect any physical monitors) that monitor is the
 >    closest to the frame.  Every (non-tooltip) frame (whether visible
 >    or not) in a graphical display is dominated by exactly one physical
 >    monitor at a time, though the frame can span multiple (or no)
 >    physical monitors.  -- (elisp) `Multiple Terminals'

I read that text but since I have no experience with multiple monitors
I have no idea of its practical implications.

 > With a single monitor it does indeed do what you say, and
 > what one would expect.  When I tried with left and right
 > monitors I saw what I described (I don't have access to
 > multiple monitors today, but that is definitely what I
 > saw).

Robert's experience seems to confirm yours.

 > I'm guessing now that `modify-frame-parameters' pays no
 > attention to the dominating monitor and expects its
 > position inputs to always use screen coordinates, i.e.,
 > relative to all monitors combined, not relative to the
 > dominating monitor.

Maybe.  But then your problem should also show up when you try to
position the left or top position of your frame by giving the offset
of the left or top edge of the dominating monitor and that dominating
monitor is not the left-/top-most one.  Right?

 > If so then the doc about floating-point perhaps just needs
 > to be modified to not talk about "display" (which can be,
 > at least in some other places, the dominating monitor),
 > and instead talk about "screen" (which seems to always
 > refer to the space of all monitors taken together.

Maybe, again.  Is that display-screen dichotomy something we already
document somewhere?  If not we should fix the nomenclature first and I
have no good idea how to do that (in Emacs sources you will still find
places where the terms "frame" and "screen" are considered
equivalents).  So if there is some reasonable common understanding of
this matter, we should specify what the terms "screen", "display",
"monitor", "terminal" and "keyboard" stand for and how they relate to
each other.

 > However, this part of the doc this report is about is
 > unclear in this regard:
 >
 >    If you want to be sure the position you specify is not
 >                ^^^^^^^^^^
 >    ignored, specify a non-‘nil’ value for the ‘user-position’
 >    parameter
 >
 > That suggests that here, at least, the parameter makes sure
 > that you get what you ask for.

Ideally, yes.  But all too often the window manager might want to
correct that position to assure, for example, that a frame stays
completely on-screen.

 > 1. Corrected wrt mention of "display", if it is in fact
 >     the whole screen that is meant (e.g., in the case of
 >     multiple monitors.

I have to leave this part to someone who understands the implications
of the use of multiple monitors.

 > 2. The text is pretty dense.  This, in particular:
 >
 >      A floating-point value ... specifies the
 >      left edge’s offset via the “left position ratio” of the
 >      frame—the ratio of the left edge of its outer frame to the
 >      width of the frame’s workarea (*note Multiple Terminals::) or
 >      its parent’s native frame (*note Child Frames::) minus the
 >      width of the outer frame.
 >
 > Maybe split that sentence into at least two sentences, but
 > probably three or four (or five).
 >
 > Maybe say "length of the left edge" instead of "left edge".

These proposals are valuable.

 > What's the "outer frame" in the case of a non-child frame?

The "outer frame" is described in section 29.3.1 Frame Layout.

 > Maybe say "screen area" instead of "frame's workarea"?  The
 > latter is undefined, AFAIK, and can suggest the dominating
 > monitor and not the total screen area of all monitors.

We want to position a frame within its workarea to avoid that the
frame overlaps the windowing system's taskbar etc.

 > Maybe add "to" before "its parent's...", to make it more
 > clear that it's the ratio of the left-edge length to ___
 > or ___ (minus...), not the ratio of the left-edge length
 > or ___ to ___ (minus...).  But splitting the sentence up
 > into constituent pieces would help most.
 >
 > Maybe each term used should be defined here, rather than
 > sending readers elsewhere.  If a reader has to go study
 > 4 other dense nodes to understand the terms used here in
 > a super-dense spec, then there are too many obstacles to
 > understanding.

I understand your concerns but as you can see the "floating-point
value" entry is already much larger than the remaining ones and since
(if I understand Robert correctly) the "(- POS)" entry faces the same
problems wrt multiple monitors, we have to sort out this more general
problem anyway.

In either case, reading the Frame Geometry section will remain a
prerequsite for understanding some of the rest of the Frames chapter
in the Elisp manual.

martin