bug#20180: Missing documentation about redisplay.

[Alan Mackenzie]

Hi, Eli.

On Mon, Mar 23, 2015 at 06:49:08PM +0200, Eli Zaretskii wrote:
> > Date: Mon, 23 Mar 2015 16:08:50 +0000
> > From: Alan Mackenzie <acm@muc.de>

> > The elisp manual doesn't contain adequate documentation about
> > (re)display.

> > The topics not covered include

> They include much more.  Describing the display engine to any depth is
> a research project, not a bug report.

:-)

> Maybe if you had more specific questions, they could be answered.

What triggered my documentation search was looking at
jit-lock-fontify-now.  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?  Why does this trigger a redisplay when the setting of the
properties during the previous redisplay cycle didn't?  In the new
redisplay, does the whole frame/window/minibuffer get redrawn (for
whatever value of "redraw") or just the bits where text properties were
set?

If I were to execute the command `ignore' via a key sequence, would that
trigger redisplay?  If so, how much would get redrawn?

> The closest thing to what you are asking for is in the large
> commentary at the beginning of xdisp.c.

> > 1. What triggers redisplay.

> See below: this is already covered.

> > 2. What portions of the frame/all frames get redisplayed when a
> >   redisplay occurs, and how does this relate to the answer to 1..

> > There is a partial answer to 1. on the page "Forcing Redisplay" which
> > states that "Emacs normally tries to redisplay the screen whenever it
> > waits for input.", but this is clearly incomplete - redisplay also
> > happens in the absence of input (e.g. by context fontification).

> I don't understand what you are saying here: "waiting for input" and
> "there's no input" is not a contradiction, on the contrary: you wait
> for input when there's none.  And what is "context fontification"?

I read the "whenever" as meaning "when it's waiting for input, it tries
_once_ to redisplay".  Having tried once, and 0.5s
(jit-lock-context-time) have passed, then jit-lock-context-fontify kicks
in to fontify screen lines below where a buffer change happened.  Another
redisplay then happens.  What triggers this second redisplay, given there
hasn't been any more "input"?  Or does the expiry of the timer count as
"input" here?  Or is something other than input (?a buffer change)
triggering this second redisplay?

> > One clearly needs an answer to 2. if one ever wants to cause the
> > redisplay of a particular part of a window or frame.

> To do that, you need to change the text of that part or the text
> properties/overlays that affect how that part looks on display.  But
> you most probably already know that, so I'm again not sure what the
> question is.

In jit-lock-fontify-now, the top half of a screen window has just been
redisplayed, and j-l-fontify-now is busily applying faces for the next
500-byte chunk.  In so doing, it sets faces in the part of the window
that have already been redisplayed.  This is apparently insufficient in
itself to trigger another redisplay of those already displayed window
parts.  I would like to understand why.

-- 
Alan Mackenzie (Nuremberg, Germany).