procyberian/emacs
2
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

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
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

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)
(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)