GNU bug report logs - #79586
Documenation of `font-lock-defaults'

Previous Next

To reply to this bug, email your comments to 79586 AT debbugs.gnu.org.
There is no need to reopen the bug first.

Toggle the display of automated, internal messages from the tracker.

Message #5 received at submit <at> debbugs.gnu.org (full text, mbox):

From: Arash Esbati <arash <at> gnu.org>
To: "emacs-bugs" <bug-gnu-emacs <at> gnu.org>
Subject: Documenation of `font-lock-defaults'
Date: Mon, 06 Oct 2025 22:31:18 +0200

X-Debbugs-CC: monnier <at> iro.umontreal.ca

Hi all,

the documentation of `font-lock-defaults' in /doc/lispref/modes.texi
reads:

  If the fourth element, @var{syntax-alist}, is non-@code{nil}, it should
  be a list of cons cells of the form @code{(@var{char-or-string}
  . @var{string})}.  These are used to set up a syntax table for syntactic
  fontification; the resulting syntax table is stored in
  @code{font-lock-syntax-table}.  If @var{syntax-alist} is omitted or
  @code{nil}, syntactic fontification uses the syntax table returned by
  the @code{syntax-table} function.  @xref{Syntax Table Functions}.

So modes.texi talks only about syntactic fontification.  The docstring
of the variable reads:

  If SYNTAX-ALIST is non-nil, it should be a list of cons pairs of the form
  (CHAR-OR-STRING . STRING) used to set the local Font Lock syntax table, for
  keyword and syntactic fontification (see ‘modify-syntax-entry’).

So it is used for keyword and syntactic fontification.  I'm not familiar
enough with fontification to say which description is more accurate, but
maybe they can get in line.

Best, Arash

Message #8 received at 79586 <at> debbugs.gnu.org (full text, mbox):

From: Stefan Monnier <monnier <at> iro.umontreal.ca>
To: Arash Esbati <arash <at> gnu.org>
Cc: 79586 <at> debbugs.gnu.org
Subject: Re: bug#79586: Documenation of `font-lock-defaults'
Date: Wed, 08 Oct 2025 19:18:18 -0400

> the documentation of `font-lock-defaults' in /doc/lispref/modes.texi
> reads:
>
>   If the fourth element, @var{syntax-alist}, is non-@code{nil}, it should
>   be a list of cons cells of the form @code{(@var{char-or-string}
>   . @var{string})}.  These are used to set up a syntax table for syntactic
>   fontification; the resulting syntax table is stored in
>   @code{font-lock-syntax-table}.  If @var{syntax-alist} is omitted or
>   @code{nil}, syntactic fontification uses the syntax table returned by
>   the @code{syntax-table} function.  @xref{Syntax Table Functions}.
>
> So modes.texi talks only about syntactic fontification.  The docstring
> of the variable reads:
>
>   If SYNTAX-ALIST is non-nil, it should be a list of cons pairs of the form
>   (CHAR-OR-STRING . STRING) used to set the local Font Lock syntax table, for
>   keyword and syntactic fontification (see ‘modify-syntax-entry’).
>
> So it is used for keyword and syntactic fontification.  I'm not familiar
> enough with fontification to say which description is more accurate, but
> maybe they can get in line.

It is installed during the whole fontification process, so it affects
both `font-lock-keywords` and the syntactic fontification.  In practice,
it is used exclusively to affect the behavior of `font-lock-keywords`,
usually by changing a few chars from "symbol" to "word" syntax so as to
be able to use \<, \>, \B, \b to match symbol boundaries instead of
word boundaries.

Syntactic fontification usually relies on `syntax-ppss-table` instead.


        Stefan

Message #11 received at 79586 <at> debbugs.gnu.org (full text, mbox):

From: Eli Zaretskii <eliz <at> gnu.org>
To: Stefan Monnier <monnier <at> iro.umontreal.ca>
Cc: 79586 <at> debbugs.gnu.org, arash <at> gnu.org
Subject: Re: bug#79586: Documenation of `font-lock-defaults'
Date: Thu, 09 Oct 2025 10:04:12 +0300

> Cc: 79586 <at> debbugs.gnu.org
> Date: Wed, 08 Oct 2025 19:18:18 -0400
> From:  Stefan Monnier via "Bug reports for GNU Emacs,
>  the Swiss army knife of text editors" <bug-gnu-emacs <at> gnu.org>
> 
> > the documentation of `font-lock-defaults' in /doc/lispref/modes.texi
> > reads:
> >
> >   If the fourth element, @var{syntax-alist}, is non-@code{nil}, it should
> >   be a list of cons cells of the form @code{(@var{char-or-string}
> >   . @var{string})}.  These are used to set up a syntax table for syntactic
> >   fontification; the resulting syntax table is stored in
> >   @code{font-lock-syntax-table}.  If @var{syntax-alist} is omitted or
> >   @code{nil}, syntactic fontification uses the syntax table returned by
> >   the @code{syntax-table} function.  @xref{Syntax Table Functions}.
> >
> > So modes.texi talks only about syntactic fontification.  The docstring
> > of the variable reads:
> >
> >   If SYNTAX-ALIST is non-nil, it should be a list of cons pairs of the form
> >   (CHAR-OR-STRING . STRING) used to set the local Font Lock syntax table, for
> >   keyword and syntactic fontification (see ‘modify-syntax-entry’).
> >
> > So it is used for keyword and syntactic fontification.  I'm not familiar
> > enough with fontification to say which description is more accurate, but
> > maybe they can get in line.
> 
> It is installed during the whole fontification process, so it affects
> both `font-lock-keywords` and the syntactic fontification.  In practice,
> it is used exclusively to affect the behavior of `font-lock-keywords`,
> usually by changing a few chars from "symbol" to "word" syntax so as to
> be able to use \<, \>, \B, \b to match symbol boundaries instead of
> word boundaries.
> 
> Syntactic fontification usually relies on `syntax-ppss-table` instead.

Is some update of the manual in order, to clarify these subtleties?

Message #14 received at 79586 <at> debbugs.gnu.org (full text, mbox):

From: Arash Esbati <arash <at> gnu.org>
To: Stefan Monnier <monnier <at> iro.umontreal.ca>
Cc: 79586 <at> debbugs.gnu.org
Subject: Re: bug#79586: Documenation of `font-lock-defaults'
Date: Thu, 09 Oct 2025 09:48:35 +0200

Stefan Monnier <monnier <at> iro.umontreal.ca> writes:

> It is installed during the whole fontification process, so it affects
> both `font-lock-keywords` and the syntactic fontification.  In practice,
> it is used exclusively to affect the behavior of `font-lock-keywords`,
> usually by changing a few chars from "symbol" to "word" syntax so as to
> be able to use \<, \>, \B, \b to match symbol boundaries instead of
> word boundaries.
>
> Syntactic fontification usually relies on `syntax-ppss-table` instead.

Thanks for the clarification.  It was also my impression that
"syntax-alist" part is used during the whole fontification as I tried to
fix AUCTeX bug#79587[1].  I think this should be mentioned in the manual
as well.

Best, Arash

Footnotes:
[1]  https://lists.gnu.org/archive/html/bug-auctex/2025-10/msg00003.html

Message #17 received at 79586 <at> debbugs.gnu.org (full text, mbox):

From: Stefan Monnier <monnier <at> iro.umontreal.ca>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: 79586 <at> debbugs.gnu.org, arash <at> gnu.org
Subject: Re: bug#79586: Documenation of `font-lock-defaults'
Date: Tue, 14 Oct 2025 13:48:29 -0400

>> It is installed during the whole fontification process, so it affects
>> both `font-lock-keywords` and the syntactic fontification.  In practice,
>> it is used exclusively to affect the behavior of `font-lock-keywords`,
>> usually by changing a few chars from "symbol" to "word" syntax so as to
>> be able to use \<, \>, \B, \b to match symbol boundaries instead of
>> word boundaries.
>> 
>> Syntactic fontification usually relies on `syntax-ppss-table` instead.
>
> Is some update of the manual in order, to clarify these subtleties?

How 'bout


        Stefan


diff --git a/doc/lispref/modes.texi b/doc/lispref/modes.texi
index d98d8b21807..8c8cbf32b61 100644
--- a/doc/lispref/modes.texi
+++ b/doc/lispref/modes.texi
@@ -3322,12 +3322,22 @@ Font Lock Basics
 
 If the fourth element, @var{syntax-alist}, is non-@code{nil}, it should
 be a list of cons cells of the form @code{(@var{char-or-string}
-. @var{string})}.  These are used to set up a syntax table for syntactic
+. @var{string})}.  These are used to set up a syntax table during
 fontification; the resulting syntax table is stored in
 @code{font-lock-syntax-table}.  If @var{syntax-alist} is omitted or
-@code{nil}, syntactic fontification uses the syntax table returned by
+@code{nil}, fontification uses the syntax table returned by
 the @code{syntax-table} function.  @xref{Syntax Table Functions}.
 
+The most common uses of @var{syntax-alist} simply change the syntax of
+a few chars from symbol constituent to word constituent so that the
+fontification rules can use regexp operators based on word boundaries.
+When @var{syntax-alist} describes more intrusive changes that can change
+what is recognized as a string or a comment, this prevents an important
+optimization in syntactic fontification, so it's better to either
+refrain from using such settings or to additionally set
+@code{syntax-ppss-table} to a non-@code{nil} value, which takes
+precedence during syntactic fontification.
+
 All the remaining elements (if any) are collectively called
 @var{other-vars}.  Each of these elements should have the form
 @code{(@var{variable} . @var{value})}---which means, make
diff --git a/lisp/font-core.el b/lisp/font-core.el
index 04a2056d9f7..7c8230f54e7 100644
--- a/lisp/font-core.el
+++ b/lisp/font-core.el
@@ -44,8 +44,10 @@ font-lock-defaults
 If CASE-FOLD is non-nil, the case of the keywords is ignored when fontifying.
 
 If SYNTAX-ALIST is non-nil, it should be a list of cons pairs of the form
-\(CHAR-OR-STRING . STRING) used to set the local Font Lock syntax table, for
-keyword and syntactic fontification (see `modify-syntax-entry').
+\(CHAR-OR-STRING . STRING) used to modify the syntax table used during Font
+Lock  (see `modify-syntax-entry').
+For performance reasons, if `syntax-ppss-table' is not set, make sure the
+changes described by SYNTAX-ALIST cannot affect syntactic fontification.
 
 These item elements are used by Font Lock mode to set the variables
 `font-lock-keywords', `font-lock-keywords-only',

Message #20 received at 79586 <at> debbugs.gnu.org (full text, mbox):

From: Eli Zaretskii <eliz <at> gnu.org>
To: Stefan Monnier <monnier <at> iro.umontreal.ca>
Cc: 79586 <at> debbugs.gnu.org, arash <at> gnu.org
Subject: Re: bug#79586: Documenation of `font-lock-defaults'
Date: Tue, 14 Oct 2025 22:09:40 +0300

> From: Stefan Monnier <monnier <at> iro.umontreal.ca>
> Cc: arash <at> gnu.org,  79586 <at> debbugs.gnu.org
> Date: Tue, 14 Oct 2025 13:48:29 -0400
> 
> >> It is installed during the whole fontification process, so it affects
> >> both `font-lock-keywords` and the syntactic fontification.  In practice,
> >> it is used exclusively to affect the behavior of `font-lock-keywords`,
> >> usually by changing a few chars from "symbol" to "word" syntax so as to
> >> be able to use \<, \>, \B, \b to match symbol boundaries instead of
> >> word boundaries.
> >> 
> >> Syntactic fontification usually relies on `syntax-ppss-table` instead.
> >
> > Is some update of the manual in order, to clarify these subtleties?
> 
> How 'bout

LGTM, thanks.

Message #25 received at 79586-done <at> debbugs.gnu.org (full text, mbox):

From: Stefan Monnier <monnier <at> iro.umontreal.ca>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: 79586-done <at> debbugs.gnu.org, arash <at> gnu.org
Subject: Re: bug#79586: Documenation of `font-lock-defaults'
Date: Tue, 14 Oct 2025 21:51:39 -0400

> LGTM, thanks.

Pushed, closing,


        Stefan

Previous Next

GNU bug tracking system
Copyright (C) 1999 Darren O. Benham, 1997,2003 nCipher Corporation Ltd, 1994-97 Ian Jackson.