Improve documentation of how faces are applied to display stings

* doc/lispref/display.texi (Displaying Faces): Describe how the
faces of the "underlying" text affect overlay and display strings.
(Display Margins): Add a cross-reference to "Displaying Faces".

diff --git a/doc/lispref/display.texi b/doc/lispref/display.texi
index 17126ce72b97e40d0317b9297c79e285dbe97ea9..3253549f3b019909ba37b8465900a745d21caf8d 100644 (file)
--- a/doc/lispref/display.texi
+++ b/doc/lispref/display.texi
@@ -2886,6 +2886,16 @@ applies the @code{mode-line} face.  For the mode line of a
 non-selected window, Emacs applies the @code{mode-line-inactive} face.
 For a header line, Emacs applies the @code{header-line} face.
 
+@item
+If the text comes from an overlay string via @code{before-string} or
+@code{after-string} properties (@pxref{Overlay Properties}), or from a
+display string (@pxref{Other Display Specs}), and the string doesn't
+contain a @code{face} or @code{mouse-face} property, but the buffer
+text affected by the overlay/display property does define a face,
+Emacs applies the face attributes of the ``underlying'' buffer text.
+Note that this is so even if the overlay or display string is
+displayed in the display margins (@pxref{Display Margins}).
+
 @item
 If any given attribute has not been specified during the preceding
 steps, Emacs applies the attribute of the @code{default} face.
@@ -4853,6 +4863,13 @@ certain buffer text, without altering or preventing the display of
 that text, put a @code{before-string} property on the text and put the
 margin display specification on the contents of the before-string.
 
+  Note that if the string to be displayed in the margin doesn't
+specify a face, its face is determined using the same rules and
+priorities as it is for strings displayed in the text area
+(@pxref{Displaying Faces}).  If this results in undesirable
+``leaking'' of faces into the margin, make sure the string has an
+explicit face specified for it.
+
   Before the display margins can display anything, you must give
 them a nonzero width.  The usual way to do that is to set these
 variables: