bug#54371: 29.0.50; read-char does not reset idle timer in some cases

[Ignacio Casso]

> IOW, code which does that is splitting hair.

I agree. And I have already proposed a patch for the org-clock bug that
changes the logic of org-resolve-clocks-if-idle to avoid this issue to
begin with instead of trying to work around it.

>> However, I still think that if not a bug, this is at least inconsistent
>> and probably deserving a footnote in the relevant section of the Emacs
>> Lisp manual
>> (https://www.gnu.org/software/emacs/manual/html_node/elisp/Idle-Timers.html).
>
> I think accessing current-idle-time from an idle time is inherently
> problematic: when the idle timer runs and receives input, whether or
> not Emacs is idle is ambiguous in principle.

However, I still think this should be documented somewhere. The only
thing I found was a comment in keyboard.c, and that was only after you
pointed me to the right email thread.

And this is not only about the use of read-event inside timer
functions. Currently the Idle Timers section of the manual would make
any reader think that these two forms would produce the output "A\nB" if
the user takes a few seconds to input a character, but only the first
one would.

(progn
  (run-with-idle-timer 1 nil (lambda () (message "A")))
  (read-char "Please wait for 2 seconds" nil nil)
  (message "B"))

(progn
  (run-with-idle-timer 1 nil (lambda () (message "A")))
  (read-char "Please wait for 2 seconds" nil 20)
  (message "B"))

So as I see it, the manual is incorrect right now, or at best incomplete
or ambiguous, and a footnote could not hurt. What do you think?