bug#25348: `display` property faces are prioritized above overlays

[Eli Zaretskii <eliz@gnu.org>]

> From: Travis Foster <tsfoster@mtu.edu>
> Date: Wed, 4 Jan 2017 11:25:54 -0800
> Cc: Drew Adams <drew.adams@oracle.com>
> 
> I just figured that the overlay applies to a range of text, and the replacement text is within that range ... so it
> seems like it should be affected.

The replacement text comes from a string, not from the buffer, so it
is NOT within the range of buffer text to which the overlay is applied.

> So what you're saying is, since the replacement text is
> not technically part of the buffer text, it doesn't count as being within the range of the overlay, and it isn't
> affected by the overlay at all?

Yes.

> But that's not the case either, because as you also stated, face attributes from
> the overlay are applied to the display string, as long as the display string doesn't already specify those
> attributes.

If the face of the display string doesn't specify the background
color, the only sensible thing to do is to use the background of the
"underlying" buffer text.  (Note that in this case the issue of
priority doesn't arise either, because only one of the sources
specifies the background color.)

> So, it seems that the overlay is applied to the display string, but it just takes a lower priority than the
> display string's text properties.

That's your interpretation, but it is incorrect.  As a matter of fact,
the priority is not applicable in this case, because the two faces are
applied to two different objects: one is buffer text, the other is the
text of the display string.

> it does conflict with the documentation stating that overlays always
> take priority over text properties.

Not in my view and interpretation, no.

> I haven't looked at the code for this, so I might be wrong, but what appears to be happening is this:
> 1. The overlay is applied to the buffer text, and the overlay face takes priority over the buffer text's faces
> 2. If the overlay had a display property, that would take priority over the buffer text's display property, but since
> the overlay has no such property, this doesn't happen
> 3. After the overlay is applied, the display property is applied, and its faces take priority over the existing faces,
> including those supplied by the overlay

That's not how the code works, if you want to talk about the
implementation.  What actually happens is this:

  . The display engine displays the buffer text with the overlay face
    applied, one character at a time, until it bumps into the display
    string.
  . The display engine then stops displaying buffer text, pushes its
    internal state onto a stack, then starts displaying the display
    string, using the face of that string.  If the face doesn't
    specify all the face attributes, it is merged with the face of the
    "underlying" buffer text, in this case the face of the hl-line
    overlay.
  . When the text of the display string is exhausted, the display
    engine pops the previous state from the stack, jumps to buffer
    position beyond the text replaced by the display string, and
    continues displaying buffer text using the overlay face.

> So the priority goes: display property faces > overlay faces > buffer faces. Am I on the right track?

No, because the priority is not being considered in this situation.
The priority is only considered when the same text has both text
properties that specify a face and one or more overlays that also
specify a face.