Re: Multiline font lock questions

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

Re: Multiline font lock questions

[David Abrahams]

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

Re: Multiline font lock questions

[Stefan Monnier]

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

That was the subject of a neverending thread :-(

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

Which way to fix the doc depends on the end of the neverending thread, hence
the current state.


        Stefan