RE: redisplay-dont-pause is not mentioned in the Emacs manual

[Drew Adams]

    I don't see any inaccuracies or unclear statements in these excerpts.
    Perhaps I know too much ;-)  Feel free to point out in more words
    which ones are confusing, and why.

As I said, none are incorrect. Nowhere is the "eagerness" of redisplay
conveyed, however: the fact that it occurs immediately after input (as
opposed to occurring on some schedule or after some determination is
made...). I was taking it to be lazier than it is.

    > None of these contradicts what Kim wrote, but they don't come
    > right out and
    > say that redisplay happens immediately after input either.

    Well, this one does, at least:

      a full redisplay does happen eventually--after all the input has
      been processed." (node Refresh Screen)

"After" doesn't mean "immediately after", to me. I'm not trying to quibble;
I really understood the meaning to be that during input redisplay wouldn't
occur, and it would "eventually" occur sometime after input.

Because I didn't guess that it happened right after input, I couldn't
imagine that `redisplay-dont-pause' = t could speed things up in some cases
(e.g. repeated cursor movement). To me, more redisplay could only slow
things down. See Kim's email for an explanation. I don't think this is
obvious.

I'm not suggesting any of the quoted texts need to be changed. But perhaps
the doc for `redisplay-dont-pause' could be more explicit about this.

    Perhaps what is missing is the understanding of the structure of the
    Emacs top-level code's flow control.

Yes, I think so. And if provided, then the doc for `redisplay-dont-pause'
could reference it.

    The top level is basically an idle loop, where Emacs sits waiting for
    user input.  Whenever some input comes in, it is processed, and Emacs
    then returns to the idle loop.

    That idle loop is where redisplay happens.  (Timers also fire there,
    btw.)  That is, redisplay is entered only when Emacs is idle.

"only" _and_ "as soon as", apparently.

    This is why redisplay normally doesn't happen if Emacs is busy
    processing something,

OK.

    and this is why redisplay will happen immediately when
    Emacs becomes idle (a.k.a. ``pauses''),

That doesn't follow, unless you add "as soon as" to "only", above.

    unless new input arrives in
    the short window of opportunity between start of idleness and the call
    to redisplay.

    Maybe we should add something like this (sans any blatant inaccuracies
    I might have let in) to the "Command Loop" node.

That would help, IMO.

Thx.