bug#21750: show-paren-mode erroneously highlights the left margin

[Eli Zaretskii <eliz@gnu.org>]

> From: Stephen Berman <stephen.berman@gmx.net>
> Cc: hinrik.sig@gmail.com,  21750@debbugs.gnu.org
> Date: Sat, 24 Oct 2015 23:54:02 +0200
> 
> >> I think this is a side effect of the general feature whereby an
> >> overlay string "inherits" the face of the surrounding buffer text.
> >> It doesn't matter whether the overlay string is displayed in the
> >> window's display margin or in the text area.
> 
> Is this clearly documented in the Emacs Lisp manual?  If not, I think it
> should be.

Which part(s) of what I said you think should be clearly documented?
The part about display/overlay strings using the face of the
"underlying" text, or the fact that this applies to strings displayed
on the display margins?

> (The only places I found that mention overlays and faces
> together are 37.9.2 Overlay Properties and 37.12.4 Displaying Faces, but
> in neither is this effect of face inheritance clearly stated, AFAICS.)

"Displaying Faces" is the place that should make it clear.  It
describes the order in which Emacs determines a face appropriate for
displaying a given character, using the various possible sources.  If
something there is unclear or missing, please elaborate.  (It is clear
to me, but I'm not the typical reader of those parts, obviously ;-)

> > You can work around this in this case if you modify your face
> > customization as follows:
> >
> >     (custom-set-faces
> >       '(linum ((t (:foreground "black" :background "white" :weight bold)))))
> >
> > IOW, don't let the 'linum' face inherit the background color from the
> > surrounding text.
> 
> It would also be very helpful to document this workaround.

Once again, the above section says that specifying the face takes the
specified attributes from that face, and merges them with faces from
lower-priority sources in order to determine unspecified attributes.
In this case, the background color is not specified by the customized
'linum' face, so Emacs takes it from the buffer text.  I'm open to
suggestions for how to make this more evident.

In any case, I take it that you agree that what Emacs does is the only
reasonable thing in this case, right?