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

Previous Next

Full log

View this message in rfc822 format

From: help-debbugs <at> gnu.org (GNU bug Tracking System)
To: Alan Mackenzie <acm <at> muc.de>
Subject: bug#19381: closed (Re: bug#19381: The doc string for `sit-for' is
 wrong; redisplay isn't unconditionally done.)
Date: Mon, 15 Dec 2014 18:51:02 +0000

[Message part 1 (text/plain, inline)]

Your bug report

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

which was filed against the emacs package, has been closed.

The explanation is attached below, along with your original report.
If you require more details, please reply to 19381 <at> debbugs.gnu.org.

-- 
19381: http://debbugs.gnu.org/cgi/bugreport.cgi?bug=19381
GNU Bug Tracking System
Contact help-debbugs <at> gnu.org with problems

[Message part 2 (message/rfc822, inline)]

From: Stefan Monnier <monnier <at> iro.umontreal.ca>
To: Alan Mackenzie <acm <at> muc.de>
Cc: 19381-done <at> debbugs.gnu.org
Subject: Re: bug#19381: The doc string for `sit-for' is wrong;
 redisplay isn't unconditionally done.
Date: Mon, 15 Dec 2014 13:50:25 -0500

> 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

[Message part 3 (message/rfc822, inline)]

From: Alan Mackenzie <acm <at> muc.de>
To: bug-gnu-emacs <at> gnu.org
Subject: The doc string for `sit-for' is wrong; redisplay isn't
 unconditionally done.
Date: Sun, 14 Dec 2014 17:13:50 +0000

Hello, Emacs.

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.
A sentence lower down in the doc string contradicts its first line
("Redisplay does not happen if input is available before it starts.").

There is thus a clash between the doc-string and the code.  (The info
page agrees with the code).

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.

However it's done, though, the clash between the doc string and
everything else should be resolved.

-- 
Alan Mackenzie (Nuremberg, Germany).

Previous Next

GNU bug tracking system
Copyright (C) 1999 Darren O. Benham, 1997,2003 nCipher Corporation Ltd, 1994-97 Ian Jackson.