elisp: Font Lock Basics
22.6.1 Font Lock Basics
-----------------------
The Font Lock functionality is based on several basic functions. Each
of these calls the function specified by the corresponding variable.
This indirection allows major and minor modes to modify the way
fontification works in the buffers of that mode, and even use the Font
Lock mechanisms for features that have nothing to do with fontification.
(This is why the description below says “should” when it describes what
the functions do: the mode can customize the values of the corresponding
variables to do something entirely different.) The variables mentioned
below are described in 
Other Font Lock Variables.
‘font-lock-fontify-buffer’
This function should fontify the current buffer’s accessible
portion, by calling the function specified by
‘font-lock-fontify-buffer-function’.
‘font-lock-unfontify-buffer’
Used when turning Font Lock off to remove the fontification. Calls
the function specified by ‘font-lock-unfontify-buffer-function’.
‘font-lock-fontify-region beg end &optional loudly’
Should fontify the region between BEG and END. If LOUDLY is
non-‘nil’, should display status messages while fontifying. Calls
the function specified by ‘font-lock-fontify-region-function’.
‘font-lock-unfontify-region beg end’
Should remove fontification from the region between BEG and END.
Calls the function specified by
‘font-lock-unfontify-region-function’.
‘font-lock-flush &optional beg end’
This function should mark the fontification of the region between
BEG and END as outdated. If not specified or ‘nil’, BEG and END
default to the beginning and end of the buffer’s accessible
portion. Calls the function specified by
‘font-lock-flush-function’.
‘font-lock-ensure &optional beg end’
This function should make sure the region between BEG and END has
been fontified. The optional arguments BEG and END default to the
beginning and the end of the buffer’s accessible portion. Calls
the function specified by ‘font-lock-ensure-function’.
There are several variables that control how Font Lock mode
highlights text. But major modes should not set any of these variables
directly. Instead, they should set ‘font-lock-defaults’ as a
buffer-local variable. The value assigned to this variable is used, if
and when Font Lock mode is enabled, to set all the other variables.
-- Variable: font-lock-defaults
This variable is set by modes to specify how to fontify text in
that mode. It automatically becomes buffer-local when set. If its
value is ‘nil’, Font Lock mode does no highlighting, and you can
use the ‘Faces’ menu (under ‘Edit’ and then ‘Text Properties’ in
the menu bar) to assign faces explicitly to text in the buffer.
If non-‘nil’, the value should look like this:
(KEYWORDS [KEYWORDS-ONLY [CASE-FOLD
[SYNTAX-ALIST OTHER-VARS...]]])
The first element, KEYWORDS, indirectly specifies the value of
‘font-lock-keywords’ which directs search-based fontification. It
can be a symbol, a variable or a function whose value is the list
to use for ‘font-lock-keywords’. It can also be a list of several
such symbols, one for each possible level of fontification. The
first symbol specifies the ‘mode default’ level of fontification,
the next symbol level 1 fontification, the next level 2, and so on.
The ‘mode default’ level is normally the same as level 1. It is
used when ‘font-lock-maximum-decoration’ has a ‘nil’ value.
Levels of Font Lock.
The second element, KEYWORDS-ONLY, specifies the value of the
variable ‘font-lock-keywords-only’. If this is omitted or ‘nil’,
syntactic fontification (of strings and comments) is also
performed. If this is non-‘nil’, syntactic fontification is not
performed. Syntactic Font Lock.
The third element, CASE-FOLD, specifies the value of
‘font-lock-keywords-case-fold-search’. If it is non-‘nil’, Font
Lock mode ignores case during search-based fontification.
If the fourth element, SYNTAX-ALIST, is non-‘nil’, it should be a
list of cons cells of the form ‘(CHAR-OR-STRING . STRING)’. These
are used to set up a syntax table for syntactic fontification; the
resulting syntax table is stored in ‘font-lock-syntax-table’. If
SYNTAX-ALIST is omitted or ‘nil’, syntactic fontification uses the
syntax table returned by the ‘syntax-table’ function. Syntax
Table Functions.
All the remaining elements (if any) are collectively called
OTHER-VARS. Each of these elements should have the form ‘(VARIABLE
. VALUE)’—which means, make VARIABLE buffer-local and then set it
to VALUE. You can use these OTHER-VARS to set other variables that
affect fontification, aside from those you can control with the
first five elements. Other Font Lock Variables.
If your mode fontifies text explicitly by adding ‘font-lock-face’
properties, it can specify ‘(nil t)’ for ‘font-lock-defaults’ to turn
off all automatic fontification. However, this is not required; it is
possible to fontify some things using ‘font-lock-face’ properties and
set up automatic fontification for other parts of the text.
Info Catalog
elisp: Font Lock Mode
elisp: Search-based Fontification