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

[Drew Adams]

>  > Of course, the "out" is that it says, "In general, it is not a good idea
>  > to position a frame relative to the right or bottom edge of its
>  > display."  But the only case discussed in that context is an initial/new
>  > frame.
> 
> It also talks about how these positions are stored and restored, for
> example, when saving the desktop.

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

>  > And there is a similar caveat about using not using
>  > floating-point with decorated frames.  But again, it speaks only about
>  > "when CREATING decorated frames.
> 
> Because Emacs does not know the size of decorations _before_ a frame
> has been created.

Yes.  The case I'm asking about is the case of an existing frame.
I don't expect any magic for the new-frame case.  That part is
clear enough, I think.

>  > The text talks about positioning flush to edges of the "display", which
>  > I'm interpreting as the dominating monitor in the case of multiple
>  > monitors.  (Is that wrong?)
> 
> I can't tell because I don't use multiple monitors and don't know what
> a dominating monitor is.  Anyone who does - please compare behavior
> and manual with what she experiences in practical work and try to fix
> any errors she sees.

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'

>  > What I see is that the dominating monitor seems to have no effect, so I
>  > wonder what "display" means here.
>  >
>  > And in fact using any of the following on an existing frame dominated by
>  > the left monitor or the right monitor sends the frame to the _same_
>  > location: its left edge flush with the left edge of the right monitor:
>  >
>  > (modify-frame-parameters nil '((left .   0.0)))
>  > (modify-frame-parameters nil '((left . - 0.0)))
> 
> The last specification is wrong - floating point values must be
> unsigned.

Ah yes.  My bad.  The doc does say 0.0 to 1.0.
 
>  > (modify-frame-parameters nil '((left .   1.0)))
> 
> On my single monitor display, evaluating the last form flushes the
> frame to the right of the display.  If it doesn't on yours, then
> please try on a single monitor display first and then describe the
> observed misbehavior on your multiple monitor display.  Maybe we can
> improve it, maybe we have to add a caveat to the manual.

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

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.

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.

>  > (And adding (user-position . t) changes nothing in this regard.)
> 
> 'user-position' has no effect on Windows and can be silently ignored
> by window managers on GNU/Linux.  Don't rely on it.

OK.  And the doc has generally made that clear.

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.

>  > What am I misunderstanding, here?  Can this text please be made more
>  > clear?  It's not really clear how floating-point values are supposed to
>  > be used or what they are supposed to do.  Dunno whether the behavior I'm
>  > seeing is bugged or the doc is wrong or I'm misunderstanding it.
> 
> Please state what you do not understand or can be improved in this
> text: [just a repeat of the existing doc]

See what I've said already.  I think it does not do what is
described, for multiple monitors. 

> In particular, it states that specifying floating point values is more
> suited for child frames than for normal frames although by design they
> should work for the latter too.

Yes, it says that.  And yes, I am using "decorated" frames.
But "they should work for the latter too" suggests that,
well, they should work for the latter too.

Don't get me wrong.  I appreciate the care with which you
wrote this doc (about floating-point values).  I think
perhaps it can be improved in two ways:

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.

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

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

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.

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.

If you try to state the same info in multiple, very simple
sentences, then I can try to make suggestions that might
make that text flow better.  But without that starting
point of very simple statements I wouldn't really know
where to start.  (And probably the simple sentences would
be fine as is, with no further suggestions needed.)

HTH, and thanks for your work on this.  I'm hoping that
someone who has multiple monitors can chime in helpfully,
as well.

In sum, in priority, I'd suggest:

1. Possible code changes, to get the behavior consistent
   and understandable.

2. Factual changes to the doc to reflect that corrected
   behavior.

3. Simple sentences, defining terms (and possibly using
   diagrams) as needed, so the spec here is at least a
   bit more self-contained.