Normally, elements of font-lock-keywords
should not match
across multiple lines; that doesn’t work reliably, because Font Lock
usually scans just part of the buffer, and it can miss a multi-line
construct that crosses the line boundary where the scan starts. (The
scan normally starts at the beginning of a line.)
Making elements that match multiline constructs work properly has two aspects: correct identification and correct rehighlighting. The first means that Font Lock finds all multiline constructs. The second means that Font Lock will correctly rehighlight all the relevant text when a multiline construct is changed—for example, if some of the text that was previously part of a multiline construct ceases to be part of it. The two aspects are closely related, and often getting one of them to work will appear to make the other also work. However, for reliable results you must attend explicitly to both aspects.
There are three ways to ensure correct identification of multiline constructs:
font-lock-extend-region-functions
that does
the identification and extends the scan so that the scanned
text never starts or ends in the middle of a multiline construct.
font-lock-fontify-region-function
hook similarly to
extend the scan so that the scanned text never starts or ends in the
middle of a multiline construct.
font-lock-multiline
which will instruct font-lock not to start or end the scan in the
middle of the construct.
There are several ways to do rehighlighting of multiline constructs:
font-lock-multiline
property on the construct. This
will rehighlight the whole construct if any part of it is changed. In
some cases you can do this automatically by setting the
font-lock-multiline
variable, which see.
jit-lock-contextually
is set and rely on it doing its
job. This will only rehighlight the part of the construct that
follows the actual change, and will do it after a short delay.
This only works if the highlighting of the various parts of your
multiline construct never depends on text in subsequent lines.
Since jit-lock-contextually
is activated by default, this can
be an attractive solution.
jit-lock-defer-multiline
property on the construct.
This works only if jit-lock-contextually
is used, and with the
same delay before rehighlighting, but like font-lock-multiline
,
it also handles the case where highlighting depends on
subsequent lines.
syntax-multiline
text property
over the construct in question. The most common use for this is when
the syntax property to apply to ‘FOO’ depend on some later text
‘BAR’: By placing this text property over the whole of
‘FOO...BAR’, you make sure that any change of ‘BAR’ will
also cause the syntax property of ‘FOO’ to be recomputed.
Note: For this to work, the mode needs to add
syntax-propertize-multiline
to
syntax-propertize-extend-region-functions
.