Re: Multiline font lock questions

[David Abrahams <dave@boost-consulting.com>]

Stefan Monnier <monnier@iro.umontreal.ca> writes:

Stefan, thanks for your reply.

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

Saying something explicit like

       Ensure that jit-lock-contextually is set (as it is by default)
       and rely on it doing its job.

would be more useful

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

Any other methods you mention in this piece of doc.

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

It would be great if the doc would give me the information I need in
order to make an informed choice about which method to use.

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

Why does he like it, and why do you dislike it?

Can we make the doc consistent, please?  If there are really four ways
documented, there shouldn't be a page saying there are three ways.
You can always add disparaging words about the fourth way if you
like.  As it stands it's hard to tell whether the information even
makes sense.

Thanks,

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