comparison lispref/modes.texi @ 61678:3c8535295b32

(Search-based Fontification): Explain that facespec is an expression to be evaluated.

61677:5d556f24030d

If you use @code{regexp-opt} to produce the regular expression
@var{matcher}, then you can use @code{regexp-opt-depth} (@pxref{Regexp
Functions}) to calculate the value for @var{subexp}.

@item (@var{matcher} . @var{facespec})
In this kind of element, @var{facespec} is an object which specifies
the face variable to use for highlighting.  In the simplest case, it
is a Lisp variable (a symbol), whose value should be a face name.

@example
;; @r{Highlight occurrences of @samp{fubar},}
;; @r{using the face which is the value of @code{fubar-face}.}
("fubar" . fubar-face)
@end example

However, @var{facespec} can also be a list of the form:

@example
(face @var{face} @var{prop1} @var{val1} @var{prop2} @var{val2}@dots{})
@end example

to specify the face @var{face} and various additional text properties
to put on the text that matches.  If you do this, be sure to add the
other text property names that you set in this way to the value of
@code{font-lock-extra-managed-props} so that the properties will also
be cleared out when they are no longer appropriate.  Alternatively,

(@var{subexp} @var{facespec} [[@var{override} [@var{laxmatch}]])
@end example

The @sc{car}, @var{subexp}, is an integer specifying which subexpression
of the match to fontify (0 means the entire matching text).  The second
subelement, @var{facespec}, specifies the face, as described above.

The last two values in @var{subexp-highlighter}, @var{override} and
@var{laxmatch}, are optional flags.  If @var{override} is @code{t},
this element can override existing fontification made by previous
elements of @code{font-lock-keywords}.  If it is @code{keep}, then

61678:3c8535295b32

If you use @code{regexp-opt} to produce the regular expression
@var{matcher}, then you can use @code{regexp-opt-depth} (@pxref{Regexp
Functions}) to calculate the value for @var{subexp}.

@item (@var{matcher} . @var{facespec})
In this kind of element, @var{facespec} is an expression whose value
specifies the face to use for highlighting.  In the simplest case,
@var{facespec} is a Lisp variable (a symbol) whose value is a face
name.

@example
;; @r{Highlight occurrences of @samp{fubar},}
;; @r{using the face which is the value of @code{fubar-face}.}
("fubar" . fubar-face)
@end example

However, @var{facespec} can also evaluate to a list of this form:

@example
(face @var{face} @var{prop1} @var{val1} @var{prop2} @var{val2}@dots{})
@end example

@noindent
to specify the face @var{face} and various additional text properties
to put on the text that matches.  If you do this, be sure to add the
other text property names that you set in this way to the value of
@code{font-lock-extra-managed-props} so that the properties will also
be cleared out when they are no longer appropriate.  Alternatively,

(@var{subexp} @var{facespec} [[@var{override} [@var{laxmatch}]])
@end example

The @sc{car}, @var{subexp}, is an integer specifying which subexpression
of the match to fontify (0 means the entire matching text).  The second
subelement, @var{facespec}, is an expression whose value specifies the
face, as described above.

The last two values in @var{subexp-highlighter}, @var{override} and
@var{laxmatch}, are optional flags.  If @var{override} is @code{t},
this element can override existing fontification made by previous
elements of @code{font-lock-keywords}.  If it is @code{keep}, then