Re: master 2399541: Remove font-lock toggle from font-lock-update

[Stefan Monnier]

>> [ Tho maybe I'd prefer if it used `font-lock-flush` or
>> `font-lock-ensure`.  ]
>
> Yes, but alas that doesn't work e.g. when yanking a font-locked string into
> a text-mode buffer.

And that's part of the problem: as it is the code can't be changed to
use those functions because it would behave slightly differently.
With a proper definition of what the behavior should be (as opposed to
it being just the result of the current implementation), we could write
the code so that it can use `font-lock-flush` when that gives the right
behavior and something else in other cases).

>>>> I'd much prefer a longer `font-lock-fontify-diwm` which tries to
>>>> reproduce more or less the same behavior as your favorite, but by
>>>> explicitly testing the different circumstances you care about.
>>>
>>> Could you perhaps give an example of such a circumstance and its
>>> corresponding action?
>>
>> The main "circumstances" that matter are whether the font-lock machinery
>> is activated and whether font-lock-mode is nil or not.
> Are these two separate conditions?

Yes, there are three cases:
- font-lock-mode is nil
- font-lock-mode is t but the font-lock machinery is not activated
  (e.g. in text-mode with the default config).
- font-lock fully activated.

>>  ;; - Correct misfontification when fontification is highly context-dependent
>>  ;;  and has a bug (typically associated with multiline constructs).
>>  ;;  `font-lock-flush` should work as well in that case.
>>  ;; - Removing fontification, e.g. when yanking font-locked strings into
>>  ;;  a text-mode buffer.  Not sure if the intention would be to generalize
>>  ;;  this to all buffers with a nil `font-lock-keywords` or also to buffers
>>  ;;  where font-lock-mode is disabled.
>
> There is another use case I think, which is close to your first use case,
> and is perhaps the most common one: the fontification is not what you expect
> (say, you're inside a function and the fontification indicates you're inside
> a comment), and you are not sure whether it's because the fontification has
> not yet been updated, or because you indeed forgot to close a comment.
> A refontifcation is useful in that case, too.

Yes, tho I think it's the same case as far as Emacs is concerned:
The difference is only in what motivated the user to launch the command
and how the user uses the result.

> Another similar case is when you know that the fontification should change
> and do not want to wait for the refontification to take place (say, you
> open a comment, and want immediately see the effect).

Indeed, and I guess this one is slightly different.

> In those case font-lock-flush should work well, too.

That's right.

>> Maybe the docstring should describe just those behaviors, and the
>> implementation could then implement them explicitly, rather than have that
>> grow accidentally as a result of the implementation.
> Is a KISS approach not better?  Could it do something wrong?

I don't like a command which is only right because it is defined to do
what it happens to do.
[ And in the case of `font-lock-fontify-buffer` it also makes it
  hard/impossible to make it more efficient: in many cases what is
  needed is just `font-lock-flush`, and in many other cases what is
  needed is `font-lock-ensure`, both of which can be significantly more
  efficient than `font-lock-fontify-buffer`.  But the function itself
  can't know which was meant.  ]

> -(defun font-lock-update (&optional arg)
> +(defun font-lock-dwim (&optional arg)
>    "Updates the syntax highlighting in this buffer.

BTW, This should say "Update" without a final "s".

> +Enable Font Lock mode if it is disabled.

Is this behavior useful?

> +Otherwise, refontify the region
> +if it is active, or a large part of the accessible portion of the buffer.

I don't see any mention of what should happen in a case like `text-mode`.

> +Otherwise, with prefix ARG, toggle Font Lock mode."

Is this behavior useful?

>    (interactive "P")
>    (save-excursion
>      (if (and (not arg) font-lock-mode)
> -        (font-lock-fontify-region (point-min) (point-max))
> +        (if (use-region-p)
> +            (font-lock-fontify-region (region-beginning) (region-end))

When font-lock is active and the region is about the refreshed
(e.g. a comment was just opened or something), this will result in
double font-locking (first it will happen now in response to this
command, and then it will happen again because this command did not tell
jit-lock that it just refreshed the area, so the planned refresh will
take place anyway).  And to make things worse, the second refresh may
re-introduce problems which were fixed by the first.

> +          (font-lock-flush (point-min) (point-max))
> +          (font-lock-fontify-region (max (point-min) (min (- (point) 50000) 
> (window-start)))
> +                                    (min (point-max) (max (+ (point) 50000) 
> (window-end)))))

Why use `font-lock-flush` and `font-lock-fontify-region`?

>        (font-lock-unfontify-region (point-min) (point-max))
>        (font-lock-mode 'toggle))))

If font-lock-mode was already activated, then (font-lock-mode 'toggle)
will call `font-lock-unfontify-region`, and if it's not then there's
nothing to unfontify, I think.  Or am I missing something?


        Stefan