Multiline font lock questions

[David Abrahams]

A simplified view of what I'm trying to handle is to fontify
[...]-enclosed text that doesn't cross a paragraph boundary.

Quoting from the info documentation:

   There are three ways to ensure correct identification of multiline
   constructs:

   * Place a `font-lock-multiline' property on the construct when it is
     added to the buffer.

I don't understand how that can help.  If I start with

+------------+
|This [is    |
|paragraph 1 |
|            |
|This is     |
|paragraph] 2|
+------------+

then presumably nothing is marked with the `font-lock-multiline'
property, because there are no multiline constructs.  If I then kill
the blank line, how is it going to know to start identification at the
beginning of the newly-formed paragraph?

   * Use `font-lock-fontify-region-function' hook to extend the scan so
     that the scanned text never starts or ends in the middle of a
     multiline construct.

That's understandable; I suppose I can just change the region
boundaries to encompass any paragraphs that intersect the region and
then forward on to font-lock-default-fontify-region (?)

   * Add a function to `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.

This is presumably just a way to do the same thing as the above, only
more cooperatively (?)

   There are three ways to do rehighlighting of multiline constructs:

   * Place a `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.

In which cases?  Oh, I see that if I read the next info page it will
tell me.  I suggest a link or something here.

   * Use `jit-lock-contextually'....  

What does "Use" mean?  I suppose "set it to non-nil," but I had to
guess that jit-lock-contextually was a variable; I suggest a doc tweak.

     ...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.

That clearly wouldn't work for the example I showed above.

   * Place a `jit-lock-defer-multiline' property on the construct.
     This works only if `jit-lock-contextually' is used, but it can
     handle the case where highlighting depends on subsequent lines.

That seems like it could make it work.  What's the advantage of using
this method?  Doesn't slow down typing as much?

This very page links to another page describing
font-lock-extend-after-change-region-function, which seems like it
constitutes a fourth way to "do rehighlighting of multiline
constructs."  Am I misunderstanding that text?

Thanks in advance for your explanations,

-- 
Dave Abrahams
Boost Consulting
www.boost-consulting.com