mirrors/emacs
1
Fork 0
mirror of git://git.sv.gnu.org/emacs.git synced 2026-05-30 09:12:58 -07:00
Code Issues Projects Releases Wiki Activity

Improve documentation of 'jit-lock-contextually'

Browse source 
* 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.
This commit is contained in:
Eli Zaretskii 2020-04-08 18:33:52 +03:00
parent 08486f4cae
commit 18d1bc0a09
2 changed files with 24 additions and 9 deletions
Download patch file Download diff file Expand all files Collapse all files

11
doc/lispref/modes.texi
View file

@ -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 Lock mode to always refontify a syntactically relevant part of the
buffer, and not just the modified lines. This argument can usually be buffer, and not just the modified lines. This argument can usually be
omitted. 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 @end defun
@defun jit-lock-unregister function @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 If the value of this variable is non-@code{nil}, Font Lock does not do
syntactic fontification, only search-based fontification based on syntactic fontification, only search-based fontification based on
@code{font-lock-keywords}. It is normally set by Font Lock mode based @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 @end defvar
@defvar font-lock-syntax-table @defvar font-lock-syntax-table

22
lisp/jit-lock.el
View file

@ -101,16 +101,22 @@ See also `jit-lock-stealth-nice'."
(defvaralias 'jit-lock-defer-contextually 'jit-lock-contextually) (defvaralias 'jit-lock-defer-contextually 'jit-lock-contextually)
(defcustom jit-lock-contextually 'syntax-driven (defcustom jit-lock-contextually 'syntax-driven
"If non-nil, means fontification should be syntactically true. "If non-nil, fontification should be syntactically true.
If nil, means fontification occurs only on those lines modified. This If nil, refontification occurs only on lines that were modified. This
means where modification on a line causes syntactic change on subsequent lines, means where modification on a line causes syntactic change on subsequent lines,
those subsequent lines are not refontified to reflect their new context. those subsequent lines are not refontified to reflect their new context.
If t, means fontification occurs on those lines modified and all If t, fontification occurs on those lines modified and all subsequent lines.
subsequent lines. This means those subsequent lines are refontified to reflect This means those subsequent lines are refontified to reflect their new
their new syntactic context, after `jit-lock-context-time' seconds. syntactic context, after `jit-lock-context-time' seconds.
If any other value, e.g., `syntax-driven', means syntactically true If any other value, e.g., `syntax-driven', it means refontification of
fontification occurs only if syntactic fontification is performed using the subsequent lines to reflect their new syntactic context may or may not
buffer mode's syntax table, i.e., only if `font-lock-keywords-only' is nil. 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." The value of this variable is used when JIT Lock mode is turned on."
:type '(choice (const :tag "never" nil) :type '(choice (const :tag "never" nil)