bug#20180: Missing documentation about redisplay.

[Eli Zaretskii <eliz@gnu.org>]

> Date: Mon, 23 Mar 2015 20:17:52 +0000
> Cc: 20180@debbugs.gnu.org
> From: Alan Mackenzie <acm@muc.de>
> 
> > > There, if jit-lock suspects that properties at an
> > > earlier location in the buffer have been changed, it arranges that after
> > > the end of the current display cycle, some text properties at some of
> > > these locations get set, thus triggering another redisplay.
> 
> > > How?
> 
> > By changing the special text property 'fontified'.
> 
> > > Why does this trigger a redisplay when the setting of the
> > > properties during the previous redisplay cycle didn't?
> 
> > I don't understand the question.  What "setting of properties" during
> > which "previous redisplay cycle" do you have in mind?
> 
> 1. Redisplay cycle 1 starts.
> 2. First 500-byte chunk gets fontified through fontification-functions.
> 3. Second 500-byte chunk fontification starts.
> 4.   jit-lock-fontify-now applies face properties to a few characters of
>      the first 500-byte chunk at locations 496, 497, 498, 499.
> 5.   jit-lock-fontify-now arranges for 10. to happen at the expiry of a 0
>      second timeout.  (`run-with-timer')
> 6. Second 500-byte chunk is completely fontified.  It gets drawn on the
>    screen.
> 7. Redisplay cycle 1 is now complete.
> 
> 10. (At expiry of 0 second timeout), jit-lock-force-redisplay applies
>    text property (fontified t) to location 496, 497, 498, 499.  496..499
>    already had the property (fontified t).
> 11. Redisplay cycle 2 starts, having been triggered by 10.
> 12. ???? Redisplay draws 496, .., 499 on the screen, but no others.
> 13. Redisplay cycle 2 is now complete.
> 
> I think I meant to ask: why does setting text property 'fontified to t at
> stage 10 trigger redisplay cycle 2, whereas setting them at stage 4.5
> wouldn't have done?

Because stage 10 happens _after_ redisplay cycle 1 is complete.
Changing text properties after redisplay triggers another redisplay of
the buffer portion where the properties changed, because changes in
properties bump up the buffer-changed counter, and redisplay examines
that counter to determine whether anything changed since the previous
redisplay cycle.

IOW, if those properties weren't changed after redisplay finished, the
next redisplay would have decided that no changes happened, and do
nothing.

> In 10. above, the `fontified' text property is set to the value it
> already had.  This seems to be sufficient to trigger a redisplay.

Because it counts as a change regardless.