From 0974418f2a823eab679a4e8d773f3bab7a47aded Mon Sep 17 00:00:00 2001
From: Eli Zaretskii <eliz@gnu.org>
Date: Sat, 25 Oct 2025 16:57:08 +0300
Subject: [PATCH] Improve and correct documentation of
 'font-lock-keywords-only'

* lisp/font-lock.el (font-lock-keywords-only):
* doc/lispref/modes.texi (Syntactic Font Lock): Improve
documentation of 'font-lock-keywords-only'.  (Bug#79692)
---
 doc/lispref/modes.texi | 19 ++++++++++---------
 lisp/font-lock.el      |  8 ++++++--
 2 files changed, 16 insertions(+), 11 deletions(-)

diff --git a/doc/lispref/modes.texi b/doc/lispref/modes.texi
index 28941647487..566cca04e23 100644
--- a/doc/lispref/modes.texi
+++ b/doc/lispref/modes.texi
@@ -4089,16 +4089,17 @@ table in special cases.  @xref{Syntax Properties}.
 @defvar font-lock-keywords-only
 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}.  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.
+@code{font-lock-keywords}; this will usually have the effect of not
+fontifying comments and strings.  This variable is normally set by Font
+Lock mode based 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.
 
-To use only syntactic fontification, this variable should
-be non-@code{nil}, while @code{font-lock-keywords} should be set to
-@code{nil} (@pxref{Font Lock Basics}).
+To use only syntactic fontification, both this variable and
+@code{font-lock-keywords} should be set to @code{nil} (@pxref{Font Lock
+Basics}).
 @end defvar
 
 @defvar font-lock-syntax-table
diff --git a/lisp/font-lock.el b/lisp/font-lock.el
index 9fa048f4b04..22aca88417f 100644
--- a/lisp/font-lock.el
+++ b/lisp/font-lock.el
@@ -527,8 +527,12 @@ This is normally set via `font-lock-add-keywords' and
 `font-lock-remove-keywords'.")
 
 (defvar font-lock-keywords-only nil
-  "Non-nil means Font Lock should not fontify comments or strings.
-This is normally set via `font-lock-defaults'.")
+  "Non-nil means Font Lock should not use syntactic fontifications.
+This is normally set via `font-lock-defaults'.  Setting it to a
+non-nil value will usually cause comments and strings not to be
+fontified, unless `font-lock-keywords' are set so as to fontify them,
+or some other font-lock mechanism has the same effect even when this
+variable is non-nil.")
 
 (defvar-local font-lock-keywords-case-fold-search nil
   "Non-nil means the patterns in `font-lock-keywords' are case-insensitive.