; Document what happens when 'display' and 'invisible' props clash

* doc/lispref/display.texi (Replacing Specs, Overlay Properties)
(Invisible Text): Document that 'invisible' is ignored when
'display' property covers the same text.  (Bug#76658)

(cherry picked from commit bd1d6761f4cd6548731dcb80e0ee8e1a53d929cc)

diff --git a/doc/lispref/display.texi b/doc/lispref/display.texi
index c65aceed8e9d099b524754331d062dfabfdf3478..19a414fa4f1c01ce2e8afa43e3fad22b935cb5fc 100644 (file)
--- a/doc/lispref/display.texi
+++ b/doc/lispref/display.texi
@@ -1210,6 +1210,12 @@ The function is called with two arguments: the first is the overlay, and
 the second is @code{nil} to make the overlay visible, or @code{t} to
 make it invisible again.
 
+@cindex invisible text, and display properties
+  The @code{invisible} property is ignored in text that is covered by a
+@dfn{replacing} @code{display} property, because such @code{display}
+properties skip the text without processing its properties.
+@xref{Replacing Specs}.
+
 @node Selective Display
 @section Selective Display
 @c @cindex selective display   Duplicates selective-display
@@ -1918,7 +1924,9 @@ same as in the unhighlighted text.
 This property activates various features that change the
 way text is displayed.  For example, it can make text appear taller
 or shorter, higher or lower, wider or narrower, or replaced with an image.
-@xref{Display Property}.
+@xref{Display Property}.  Note that, if the @code{display} property is a
+@dfn{replacing} one (@pxref{Replacing Specs}), the @code{invisible}
+property of the same overlay will be ignored.
 
 @kindex help-echo @r{(overlay property)}
 @item help-echo
@@ -1981,8 +1989,11 @@ conventions are the same as for the @code{modification-hooks} functions.
 @kindex invisible @r{(overlay property)}
 @item invisible
 The @code{invisible} property can make the text in the overlay
-invisible, which means that it does not appear on the screen.
-@xref{Invisible Text}, for details.
+invisible, which means that it does not appear on the screen.  However,
+if the text covered by the overlay has a @dfn{replacing} @code{display}
+property, the @code{invisible} property will be ignored, because a
+replacing @code{display} property skips the text without examining its
+properties.  @xref{Invisible Text}, for details.
 
 @kindex intangible @r{(overlay property)}
 @item intangible
@@ -5335,10 +5346,15 @@ instead of the text that has the property.  These are called
 to interactively move point into the middle of buffer text that is
 replaced in this way.
 
+@cindex display properties, and invisible text
+@cindex composition property, and replacing display specs
   If a list of display specifications includes more than one replacing
 display specification, the first overrides the rest.  Replacing
 display specifications make most other display specifications
-irrelevant, since those don't apply to the replacement.
+irrelevant, since those don't apply to the replacement.  In addition,
+any @code{invisible} and @code{composition} properties of the text that
+is replaced are ignored, because the replaced text is skipped and its
+properties are not processed.
 
   For replacing display specifications, @dfn{the text that has the
 property} means all the consecutive characters that have the same