[Emacs-diffs] emacs-26 52fd400: Minor improvement of documentation of '(when CONDITION . SPEC)'

[Eli Zaretskii]

branch: emacs-26
commit 52fd40068e0f8b41bd29eaec1334299eb86d0bff
Author: Eli Zaretskii <address@hidden>
Commit: Eli Zaretskii <address@hidden>

    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.
---
 doc/lispref/display.texi | 10 ++++++++++
 1 file changed, 10 insertions(+)

diff --git a/doc/lispref/display.texi b/doc/lispref/display.texi
index 921d58a..7892c15 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