From 18d1bc0a09db280cc1653706f7f8022786f77c94 Mon Sep 17 00:00:00 2001 From: Eli Zaretskii Date: Wed, 8 Apr 2020 18:33:52 +0300 Subject: [PATCH] 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 a8ddd45f891..e685391c955 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 d73cd74da0b..95cc02197c1 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) -- 2.39.5