elisp: Font Lock Multiline
22.6.9.1 Font Lock Multiline
............................
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.
-- Variable: font-lock-multiline
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 the 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’.
Info Catalog
elisp: Multiline Font Lock
elisp: Region to Refontify