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

[Stephen Berman <stephen.berman@gmx.net>]

On Sat, 24 Oct 2015 23:22:36 +0300 Eli Zaretskii <eliz@gnu.org> wrote:

>> Date: Sat, 24 Oct 2015 23:07:03 +0300
>> From: Eli Zaretskii <eliz@gnu.org>
>> Cc: 21750@debbugs.gnu.org
>> 
>> 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.  (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.)

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

Steve Berman