Hi,
I would like to propose simplifying the text shown by `org-clock-resolve'.
The current splash buffer starts with:
Select a Clock Resolution Command:
and the expert/minibuffer prompt only shows a raw list of accepted keys:
[jkKtTgGSscCiq]?
This is quite hard to understand without already knowing the implementation.
It exposes the set of accepted characters, but not what those choices mean.
The user is not really choosing a "resolution command"; they are deciding how
Org should treat idle time for an open clock.
I think the prompt would be clearer if it was organized around that question.
For example, the splash buffer could say:
Resolve Idle Clock
Org detected 37 minutes away from the keyboard.
Choose what should count as clocked time:
i/q Count all 37 minutes
s/S Count none of it
k/K Count only the first N minutes
t/T Count until a time you enter
g/G You returned N minutes ago
Other actions:
C Cancel this clock
j/J Jump to the clock for manual edits
Lowercase keeps the clock running. Uppercase stops the clock.
The expert/minibuffer prompt could also avoid showing only the cryptic key
set. For example:
Clocked in & idle for 37 mins [i/q all, s/S none, k/K first N,
t/T until time, g/G returned N min ago, C cancel, j/J jump]?
This keeps the existing one-key interaction and the existing key bindings,
but presents the choices in terms of what will happen to the clocked time.
In particular, it makes the difference between 'k' and 'g' easier to
understand.
I found a few related earlier discussions. In 2010, Bernt Hansen noted
that the resolver prompt felt geared towards idle time even when resolving
a dangling clock during clock-in, and suggested simplifying the choices in
that case:
https://lists.gnu.org/archive/html/emacs-orgmode/2010-05/msg00485.html
More recently, in 2024, a similar confusion came up around the
lowercase/uppercase wording for dangling clocks. Ihor confirmed that the
menu had been designed for automatic idle resolution and "does not make
much sense when clocking in":
https://lists.gnu.org/r/emacs-orgmode/2024-07/msg00328.html
There was also a 2022 change from `read-char' to `read-char-exclusive' to
make the prompt more robust against accidental clicks, but the prompt text
itself stayed essentially the same:
https://orgmode.org/list/[email protected]
So I think there are two separable issues here: the prompt is cryptic in
expert mode, and the splash text is framed around the implementation rather
than the user's decision. Clarifying the wording could improve both
without changing the one-key interaction.
While looking at this, I also noticed that the minibuffer prompt advertises
lowercase 'c', but the resolver only accepts uppercase 'C'. A small patch
could fix that at the same time.
What do you think about this direction? Do you have suggestions for better
wording or for a clearer way to present these choices?
Best,
--
Slawomir Grochowski
