Subject: bug#52418: 27.2; Regression in doc of `font-lock-defaults' since Emacs 25

From: Drew Adams <[email-masked]>
Date: Fri, 10 Dec 2021 22:39:31 +0000

Prior to Emacs 25, the doc (string and Elisp manual) for
`font-lock-defaults' correctly said this:

 Defaults should be of the form:

  (KEYWORDS [KEYWORDS-ONLY [CASE-FOLD [SYNTAX-ALIST
                                        [SYNTAX-BEGIN ...]]]])

And it specified that:

 If SYNTAX-BEGIN is non-nil, it should be a function with no args used
 to move backwards outside any enclosing syntactic block, for syntactic
 fontification.  Typical values are `beginning-of-line'...

This was replaced starting with Emacs 25 by just this:

 (KEYWORDS [KEYWORDS-ONLY [CASE-FOLD [SYNTAX-ALIST ...]]])

And a statement that the `...' is a possibly empty list of conses of
this form: (VARIABLE . VALUE).

It may be that such conses are acceptable now.  But the previous
description, which is now lacking, also still applies.  The value
for Dired mode, for example is this:

 (dired-font-lock-keywords t nil nil beginning-of-line)

That value fits ONLY the old description.  It does NOT fit the new
description, which is, at best, incomplete.

Please fix the doc for this, whatever the complete truth might be.
Clearly, the doc is wrong (or else values such as that for Dired are
wrong, and that value still works).

In GNU Emacs 27.2 (build 1, x86_64-w64-mingw32)
 of 2021-03-26 built on CIRROCUMULUS
Repository revision: deef5efafb70f4b171265b896505b92b6eef24e6
Repository branch: HEAD
Windowing system distributor 'Microsoft Corp.', version 10.0.19042
System Description: Microsoft Windows 10 Pro (v10.0.2009.19042.1348)