Re: Multiline font lock questions

[Stefan Monnier]

[ Since this refers to doc and vars that are specific to Emacs-22, it might
  be better to discuss it on emacs-devel. ]

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

Indeed, it's a bit awkwardly placed and written.  This is basically saying
"you can do it yourself manually somehow".

>    * 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 (?)

Right.

>    * 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 (?)

Indeed.  But this new var only exists in Emacs-22, so if you want your code
to work with Emacs-21, you should use
font-lock-fontify-region-function instead.

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

Thanks.

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

Problem is: in 99% of the cases, it's already set, so there's nothing to do
really, other than rely on it doing its job.  That's why I set "use".

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

Indeed.

>    * 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?

Over what?  `font-lock-multiline'?

> Doesn't slow down typing as much?

Yes: the re-highlighting is delayed a little bit (see
jit-lock-context-time), so it doesn't happen after every keystroke.
For small multiline elements, it's not a big change, but for larger ones, it
can be significant.

Another difference is that it only works if font-lock uses jit-lock.

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

Indeed.  Alan McKenzie likes this, but I would rather discourage
its use.


        Stefan