bug#19381: The doc string for `sit-for' is wrong; redisplay isn't unconditionally done.

[Alan Mackenzie]

Hello, Stefan.

On Mon, Dec 15, 2014 at 01:50:25PM -0500, Stefan Monnier wrote:
> > The doc string for `sit-for', in its first (and most important) line
> > states unequivocally that redisplay is performed.  (That line is "Perform
> > redisplay, then wait for SECONDS seconds or until input is available.")
> > That's not what the function currently does - it doesn't perform
> > redisplay if input is already available when it is called.

> I've changed it to say:

>   "Redisplay, then wait for SECONDS seconds.  Stop when input is available.

Thanks, that's better.  It's an awkward thing to have to squeeze into
one line.

> So that the "when input is available" part is not so closely tied to
> the "wait" part but can also apply to the "redisplay" part.

> > It would seem at first sight that the obvious thing to do is correct the
> > first line of the doc string.  However there are lots (125) of instances
> > of "(sit-for 0)" in Emacs, and a lot of these are probably intended to
> > mean "perform redisplay NOW".  So it might be better to make `sit-for'
> > always do a redisplay.

> While fixing the docstring, I also saw that the code of sit-for hints
> at the solution to the above problem: if you just want to redisplay,
> don't call (sit-for 0), but call `redisplay' instead (where the `force'
> argument can be used to decide whether pending input should prevent
> redisplay or not).

Yes.  There are 17 calls to `redisplay' in Emacs.  Of the 125 "(sit-for
0)"s, a lot of them will be wanting redisplay, but are being called in
the context of a user typing individual keys.  (This is certainly the
case in edebug.el, for example.)  So, it doesn't matter too much.

>         Stefan

-- 
Alan Mackenzie (Nuremberg, Germany).