From a849b5641044c19ee3d8a4206c7c827e2620c325 Mon Sep 17 00:00:00 2001 From: Eli Zaretskii Date: Mon, 23 Aug 2021 23:14:00 +0300 Subject: [PATCH] Document 'jit-lock-bounds' * doc/lispref/modes.texi (Other Font Lock Variables): * lisp/jit-lock.el (jit-lock-functions, jit-lock-register): Document the return value of the fontification functions. --- doc/lispref/modes.texi | 5 +++++ lisp/jit-lock.el | 10 ++++++++-- 2 files changed, 13 insertions(+), 2 deletions(-) diff --git a/doc/lispref/modes.texi b/doc/lispref/modes.texi index 951f30fc6ff..ee55f982d02 100644 --- a/doc/lispref/modes.texi +++ b/doc/lispref/modes.texi @@ -3315,6 +3315,11 @@ This function tells Font Lock mode to run the Lisp function current buffer. It calls @var{function} before calling the default fontification functions, and gives it two arguments, @var{start} and @var{end}, which specify the region to be fontified or refontified. +If @var{function} performs fontifications, it can return a list of the +form @w{@code{(jit-lock-bounds @var{beg} . @var{end})}}, to indicate +the bounds of the region it actually fontified; JIT font-lock will use +this information to optimize subsequent redisplay cycles and regions +of buffer text it will pass to future calls to @var{function}. The optional argument @var{contextual}, if non-@code{nil}, forces Font Lock mode to always refontify a syntactically relevant part of the diff --git a/lisp/jit-lock.el b/lisp/jit-lock.el index a1287926eb9..a905936b6b9 100644 --- a/lisp/jit-lock.el +++ b/lisp/jit-lock.el @@ -150,7 +150,10 @@ If 0, then fontification is only deferred while there is input pending." (defvar jit-lock-functions nil "Special hook run to do the actual fontification. The functions are called with two arguments: -the START and END of the region to fontify.") +the START and END of the region to fontify. +Each function can return a list of the form (jit-lock-bounds BEG . END), +to indicate the bounds of the region it actually fontified; +JIT font-lock will use this information to optimize redisplay cycles.") (defvar-local jit-lock-context-unfontify-pos nil "Consider text after this position as contextually unfontified. @@ -332,7 +335,10 @@ like `debug-on-error' and Edebug can be used." "Register FUN as a fontification function to be called in this buffer. FUN will be called with two arguments START and END indicating the region that needs to be (re)fontified. -If non-nil, CONTEXTUAL means that a contextual fontification would be useful." +If non-nil, CONTEXTUAL means that a contextual fontification would be useful. +FUN can return a list of the form (jit-lock-bounds BEG . END), +to indicate the bounds of the region it actually fontified; JIT +font-lock will use this information to optimize redisplay cycles." (add-hook 'jit-lock-functions fun nil t) (when (and contextual jit-lock-contextually) (setq-local jit-lock-contextually t)) -- 2.39.5