One way to ensure reliable rehighlighting of multiline Font Lock
constructs is to put on them the text property font-lock-multiline.
It should be present and non-nil for text that is part of a
multiline construct.
When Font Lock is about to highlight a range of text, it first
extends the boundaries of the range as necessary so that they do not
fall within text marked with the font-lock-multiline property.
Then it removes any font-lock-multiline properties from the
range, and highlights it. The highlighting specification (mostly
font-lock-keywords) must reinstall this property each time,
whenever it is appropriate.
Warning: don’t use the font-lock-multiline property
on large ranges of text, because that will make rehighlighting slow.
If the font-lock-multiline variable is set to t, Font
Lock will try to add the font-lock-multiline property
automatically on multiline constructs. This is not a universal
solution, however, since it slows down Font Lock somewhat. It can
miss some multiline constructs, or make the property larger or smaller
than necessary.
For elements whose matcher is a function, the function should
ensure that submatch 0 covers the whole relevant multiline construct,
even if only a small subpart will be highlighted. It is often just as
easy to add the font-lock-multiline property by hand.
The font-lock-multiline property is meant to ensure proper
refontification; it does not automatically identify new multiline
constructs. Identifying them requires that Font Lock mode operate on
large enough chunks at a time. This will happen by accident on many
cases, which may give the impression that multiline constructs magically
work. If you set the font-lock-multiline variable
non-nil, this impression will be even stronger, since the
highlighting of those constructs which are found will be properly
updated from then on. But that does not work reliably.
To find multiline constructs reliably, you must either manually place
the font-lock-multiline property on the text before Font Lock
mode looks at it, or use font-lock-fontify-region-function.