From: Eli Zaretskii <eliz@gnu.org>
Date: Mon, 4 Mar 2019 17:49:47 +0000 (+0200)
Subject: Minor improvement of documentation of '(when CONDITION . SPEC)'
X-Git-Tag: emacs-26.2~46
X-Git-Url: http://git.eshelyaron.com/gitweb/?a=commitdiff_plain;h=52fd40068e0f8b41bd29eaec1334299eb86d0bff;p=emacs.git

Minor improvement of documentation of '(when CONDITION . SPEC)'

* doc/lispref/display.texi (Other Display Specs): Add a caveat
to using the '(when CONDITION . SPEC)' display specs.
---

diff --git a/doc/lispref/display.texi b/doc/lispref/display.texi
index 921d58a1f3a..7892c15b462 100644
--- a/doc/lispref/display.texi
+++ b/doc/lispref/display.texi
@@ -4853,6 +4853,16 @@ and the buffer position where the @code{display} property was found,
 respectively.  Both positions can be different when @code{object} is a
 string.
 
+Note that @var{condition} will only be evaluated when redisplay
+examines the text where this display spec is located, so this feature
+is best suited for conditions that are relatively stable, i.e.@:
+yield, for each particular buffer position, the same results on every
+evaluation.  If the results change for the same text location, e.g.,
+if the result depends on the position of point, then the conditional
+specification might not do what you want, because redisplay examines
+only those parts of buffer text where it has reasons to assume that
+something changed since the last display cycle.
+
 @node Display Margins
 @subsection Displaying in the Margins
 @cindex display margins