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

[Stefan Monnier]

> 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.

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).


        Stefan