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.

1 files changed, 10 insertions, 0 deletions

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