Merge from origin/emacs-27

fd27685c1e (origin/emacs-27) ; * doc/lispref/keymaps.texi (Extended M...
6057d79a4e * doc/lispref/keymaps.texi (Extended Menu Items): Tweak :k...
17a1bb5a03 Fix redisplay when scrolling under redisplay-dont-pause
90321f595c Fix face extension in pulse.el
36c42d2a30 * doc/misc/tramp.texi (Bug Reports): Avoid line breaks in ...
d5750af151 Avoid assertion violation in intervals.c
18d1bc0a09 Improve documentation of 'jit-lock-contextually'
08486f4cae Speed up 'resize-mode' child frames a little
f451ef9308 ; * etc/NEWS: Mention 'executing-macro' in removed vars.
c49d379f17 Fix some problems with moving and resizing child frames

# Conflicts:
#	etc/NEWS

1 files changed, 14 insertions, 8 deletions

diff --git a/lisp/jit-lock.el b/lisp/jit-lock.el
index 9cdb108be03..c0c9cac23e7 100644
--- a/lisp/jit-lock.el
+++ b/lisp/jit-lock.el
@@ -96,16 +96,22 @@ See also `jit-lock-stealth-nice'."
 
 (defvaralias 'jit-lock-defer-contextually 'jit-lock-contextually)
 (defcustom jit-lock-contextually 'syntax-driven
-  "If non-nil, means fontification should be syntactically true.
-If nil, means fontification occurs only on those lines modified.  This
+  "If non-nil, fontification should be syntactically true.
+If nil, refontification occurs only on lines that were modified.  This
 means where modification on a line causes syntactic change on subsequent lines,
 those subsequent lines are not refontified to reflect their new context.
-If t, means fontification occurs on those lines modified and all
-subsequent lines.  This means those subsequent lines are refontified to reflect
-their new syntactic context, after `jit-lock-context-time' seconds.
-If any other value, e.g., `syntax-driven', means syntactically true
-fontification occurs only if syntactic fontification is performed using the
-buffer mode's syntax table, i.e., only if `font-lock-keywords-only' is nil.
+If t, fontification occurs on those lines modified and all subsequent lines.
+This means those subsequent lines are refontified to reflect their new
+syntactic context, after `jit-lock-context-time' seconds.
+If any other value, e.g., `syntax-driven', it means refontification of
+subsequent lines to reflect their new syntactic context may or may not
+occur after `jit-lock-context-time', depending on the the font-lock
+definitions of the buffer.  Specifically, if `font-lock-keywords-only'
+is nil in a buffer, which generally means the syntactic fontification
+is done using the buffer mode's syntax table, the syntactic
+refontification will be triggered (because in that case font-lock
+calls `jit-lock-register' to set up for syntactic refontification,
+and sets the buffer-local value of `jit-lock-contextually' to t).
 
 The value of this variable is used when JIT Lock mode is turned on."
   :type '(choice (const :tag "never" nil)