Yes, the text in the buffer is replaced by its display text, with the face.
Then, I would expect the overlay to apply to all the text on the line,
including the replacement text. Since the properties in overlays are
supposed to take priority over the properties in the buffer itself, I don't
think it makes sense for the replacement to take priority over the
overlay. Is that wrong? It seems that the replacement should occur, and
then the resulting text should be modified further by the overlay.

On Tue, Jan 3, 2017 at 2:29 PM, Drew Adams <drew.adams@oracle.com> wrote:

> > When I do the following (for example):
> > (put-text-property (point) (1+ (point))
> >                    'display (propertize "." 'face 'header-line))
> ...
> > But it seems like in this case, the display text property
> > is taking priority over the the overlay.
>
> You are using a "replacing" `display'-property spec.
> See (elisp) `Replacing Specs'.
> http://www.gnu.org/software/emacs/manual/html_node/elisp/
> Replacing-Specs.html
>
> Your text that has the property is entirely replaced (for display)
> by what is specified for property `display'.
>