RE: Revamping sit-for

["Drew Adams" <drew.adams@oracle.com>]

    > Excuse me if I'm misunderstanding, but how can you change the
    > signature of
    > sit-for in a way that breaks existing code? IIUC, it is changing from
    >
    >   (sit-for seconds)
    >   (sit-for seconds milliseconds)
    >   (sit-for seconds milliseconds nodisp)
    >
    > to
    >
    >   (sit-for seconds)
    >   (sit-for seconds nodisp)
    >   (sit-for seconds nodisp obsolete)
    >
    > That means that existing calls that use the milliseconds arg
    > will be newly interpreted to consider that arg as a
    > no-display arg, no?

    No.  If the third argument is non-nil, it uses the old behavior.  But
    this is considered an obsolete behavior, so it is only briefly
    explained in the docstring; all this is identical to the current
    behavior.

If everything is identical to the current behavior, then the doc string
seems very wrong.

The doc string says, to me, that an existing call of (sit-for 3 200), which
previously simply waited 3.2 sec, with no inhibition of display, will now be
interpreted as a wait of 3.0 sec, with inhibition of display. That's a
serious change in behavior.

I don't see how else to read the doc string: (sit-for 3 200) fits the
pattern (sit-for seconds nodisp), and it says that nodisp non-nil means no
redisplay.

You mention the third arg being non-nil, saying that in that case it uses
the old behavior. Even it that is the case (and it should be so stated, if
so), what about when the third arg is nil?

Sorry, but I just don't get this. What's the magic or the missing
ingredient?