Document :box attribute caveats when used on display strings

* doc/lispref/display.texi (Replacing Specs, Face Attributes):
Mention special considerations when a display string has a
':box' face attribute identical to the surrounding buffer text.
Suggested by JD Smith <jdtsmith@gmail.com>.  (Bug#70637)

1 files changed, 33 insertions, 0 deletions

diff --git a/doc/lispref/display.texi b/doc/lispref/display.texi
index f20064519fc..869bf15a40a 100644
--- a/doc/lispref/display.texi
+++ b/doc/lispref/display.texi
@@ -2747,6 +2747,11 @@ being pressed.  If it is @code{pressed-button}, the box looks like a
 @code{flat-button} or omitted, a plain 2D box is used.
 @end table
 
+If you use the @code{:box} face attribute on strings displayed instead
+of buffer text via the @code{display} text property, special
+considerations might apply if the surrounding buffer text also has the
+@code{:box} face attribute.  @xref{Replacing Specs}.
+
 @item :inverse-video
 Whether or not characters should be displayed in inverse video.  The
 value should be @code{t} (yes) or @code{nil} (no).
@@ -5266,6 +5271,34 @@ characters get a second string (@code{concat} creates a new string
 object), so they are replaced with one @samp{A}; and so on.  Thus, the
 ten characters appear as five A's.
 
+@cindex box face attribute, and @code{display} properties
+Note: Using @code{:box} face attribute (@pxref{Face Attributes}) on a
+replacing @code{display} string that is adjacent to normal text with
+the same @code{:box} style can lead to display artifacts when moving
+the cursor across the text with this face attribute.  These can be
+avoided by applying the @code{:box} attribute directly to the text
+being replaced, rather than (or in addition to) the @code{display}
+string itself.  Here's an example:
+
+@smallexample
+@group
+;; Causes display artifacts when moving the cursor across text
+(progn
+  (put-text-property 1 2 'display (propertize "  [" 'face '(:box t)))
+  (put-text-property 2 3 'face '(:box t))
+  (put-text-property 3 4 'display (propertize "]  " 'face '(:box t))))
+@end group
+
+@group
+;; No display artifacts due to `:box'
+(progn
+  (add-text-properties 1 2 '(face (:box t) display "  ["))
+  (put-text-property 2 3 'face '(:box t))
+  (add-text-properties 3 4 '(face (:box t) display "]  ")))
+@end group
+@end smallexample
+
+
 @node Specified Space
 @subsection Specified Spaces
 @cindex spaces, specified height or width