[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
emacs-27 18d1bc0: Improve documentation of 'jit-lock-contextually'
From: |
Eli Zaretskii |
Subject: |
emacs-27 18d1bc0: Improve documentation of 'jit-lock-contextually' |
Date: |
Wed, 8 Apr 2020 11:35:45 -0400 (EDT) |
branch: emacs-27
commit 18d1bc0a09db280cc1653706f7f8022786f77c94
Author: Eli Zaretskii <address@hidden>
Commit: Eli Zaretskii <address@hidden>
Improve documentation of 'jit-lock-contextually'
* lisp/jit-lock.el (jit-lock-contextually): Clarify the jit-lock
operation when 'jit-lock-contextually' is non-nil and non-t.
* doc/lispref/modes.texi (Syntactic Font Lock)
(Other Font Lock Variables): Document the relation between
'jit-lock-register', 'font-lock-keywords-only', and syntactic
refontification.
---
doc/lispref/modes.texi | 11 ++++++++++-
lisp/jit-lock.el | 22 ++++++++++++++--------
2 files changed, 24 insertions(+), 9 deletions(-)
diff --git a/doc/lispref/modes.texi b/doc/lispref/modes.texi
index a8ddd45..e685391 100644
--- a/doc/lispref/modes.texi
+++ b/doc/lispref/modes.texi
@@ -3214,6 +3214,11 @@ The optional argument @var{contextual}, if
non-@code{nil}, forces Font
Lock mode to always refontify a syntactically relevant part of the
buffer, and not just the modified lines. This argument can usually be
omitted.
+
+When Font Lock is activated in a buffer, it calls this function with a
+non-@code{nil} value of @var{contextual} if the value of
+@code{font-lock-keywords-only} (@pxref{Syntactic Font Lock}) is
+@code{nil}.
@end defun
@defun jit-lock-unregister function
@@ -3380,7 +3385,11 @@ table in special cases. @xref{Syntax Properties}.
If the value of this variable is non-@code{nil}, Font Lock does not do
syntactic fontification, only search-based fontification based on
@code{font-lock-keywords}. It is normally set by Font Lock mode based
-on the @var{keywords-only} element in @code{font-lock-defaults}.
+on the @var{keywords-only} element in @code{font-lock-defaults}. If
+the value is @code{nil}, Font Lock will call @code{jit-lock-register}
+(@pxref{Other Font Lock Variables}) to set up for automatic
+refontification of buffer text following a modified line to reflect
+the new syntactic context due to the change.
@end defvar
@defvar font-lock-syntax-table
diff --git a/lisp/jit-lock.el b/lisp/jit-lock.el
index d73cd74..95cc021 100644
--- a/lisp/jit-lock.el
+++ b/lisp/jit-lock.el
@@ -101,16 +101,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)
[Prev in Thread] |
Current Thread |
[Next in Thread] |
- emacs-27 18d1bc0: Improve documentation of 'jit-lock-contextually',
Eli Zaretskii <=