[BUG] org-clock-auto-clockout does not actually use x11idle on X11 [9.6.8 (release_9.6.8-3-g21171d @ /usr/share/emacs/30.0.50/lisp/org/)]

[Vladimir Nikishkin <lockywolf@gmail.com>]

For some time I have been wondering why auto-clockout does not use
x11idle on my machine. Today I finally got to studying this issue.

Here is `org-clock-auto-clockout-insinuate'

#+begin_src elisp
(defun org-clock-auto-clockout-insinuate ()
  "Set up hook for auto clocking out when Emacs is idle.
See `org-clock-auto-clockout-timer'.

This function is meant to be added to the user configuration."
  (require 'org-clock)
  (add-hook 'org-clock-in-hook #'org-clock-auto-clockout t))
#+end_src

Okay, the only thing it does is it adds a hook.
What does the hook do?

#+begin_src elisp
(defun org-clock-auto-clockout ()
  "Clock out the currently clocked in task if Emacs is idle.
See `org-clock-auto-clockout-timer' to set the idle time span.
This is only effective when `org-clock-auto-clockout-insinuate'
is present in the user configuration."
  (when (and (numberp org-clock-auto-clockout-timer)
	     org-clock-current-task)
    (run-with-idle-timer
     org-clock-auto-clockout-timer nil #'org-clock-out)))
#+end_src

just runs auto clockout on an emacs idle timer, which does not care
about X11 idleness either. It also runs only once, since the seconds
argument is nil.

#'org-clock-out does not use x11idle either.

So, at least in Org 9.6.8, the Manual's claim that
#+begin_quote
   (1) On computers using macOS, idleness is based on actual user
idleness, not just Emacs’ idle time.  For X11, you can install a utility
program ‘x11idle.c’, available in the ‘org-contrib/’ repository, or
install the xprintidle package and set it to the variable
‘org-clock-x11idle-program-name’ if you are running Debian, to get the
same general treatment of idleness.  On other systems, idle time refers
to Emacs idle time only.
#+end_quote

is false.

I suggest rewriting that timer expression like this:

#+begin_src elisp
(run-with-timer 60 60
                (lambda ()
                  (if (< org-clock-auto-clockout-timer (if org-x11idle-exists-p
                                                          (org-x11-idle-seconds)
                                                        (current-idle-time))))
                      (org-clock-out)
                    nil)))
#+end_src

or, even better:

#+begin_src elisp
(defun org-clock-auto-clockout-maybe ()
   (if (< org-clock-auto-clockout-timer (if org-x11idle-exists-p
                                           (org-x11-idle-seconds)
                                         (current-idle-time)))))
(defun org-clock-auto-clockout-insinuate ()
  "Set up hook for auto clocking out when Emacs is idle.
See `org-clock-auto-clockout-timer'.

This function is meant to be added to the user configuration."
  (require 'org-clock)
  (add-hook 'org-clock-in-hook #'org-clock-auto-clockout-maybe t)
  (add-hook 'org-clock-out-hook (lambda ()
       (cancel-function-timers 'org-clock-auto-clockout-maybe))))
#+end_src

Emacs  : GNU Emacs 30.0.50 (build 1, x86_64-slackware-linux-gnu, GTK+ Version 3.24.31, cairo version 1.16.0)
 of 2023-09-22
Package: Org mode version 9.6.8 (release_9.6.8-3-g21171d @ /usr/share/emacs/30.0.50/lisp/org/)
-- 
Your sincerely,
Vladimir Nikishkin (MiEr, lockywolf)
(Laptop)