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.

1 files changed, 10 insertions, 1 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