* [PATCH 2/2] doc/org-manual.org: Document org-clock-{in,out}-switch-to-state
@ 2022-10-22 18:29 Samuel W. Flint
2022-10-24 9:13 ` Ihor Radchenko
0 siblings, 1 reply; 5+ messages in thread
From: Samuel W. Flint @ 2022-10-22 18:29 UTC (permalink / raw)
To: Org-Mode
* doc/org-manual.org (Clocking commands): Document operation of
org-clock-{in,out}-switch-to-state, org-clock-{in,out}-next-state, and
org-clock-{in,out}-next-state-function.
---
doc/org-manual.org | 22 ++++++++++++++++++++++
1 file changed, 22 insertions(+)
diff --git a/doc/org-manual.org b/doc/org-manual.org
index ad584d7a5..600690da2 100644
--- a/doc/org-manual.org
+++ b/doc/org-manual.org
@@ -6583,6 +6583,17 @@ about what to do with it.
C-u C-u)}}} prefixes, force continuous clocking by starting the
clock when the last clock stopped.
+ #+vindex: org-clock-in-switch-to-state
+ #+vindex: org-clock-in-next-state
+ #+findex: org-clock-in-next-state-function
+ The variable ~org-clock-in-switch-to-state~ controls if and how a
+ current task's TODO state is changed. No change (a ~nil~) is the
+ default. A specific state may be forced with a string value. The
+ ~org-clock-in-next-state~ alist may be utilized by setting it to
+ ~org-clock-in-next-state-function~, or a custom function may be
+ used. This custom function should take the current state, and
+ return either a new state or ~nil~ to keep the current state.
+
#+cindex: @samp{CLOCK_MODELINE_TOTAL}, property
#+cindex: @samp{LAST_REPEAT}, property
#+vindex: org-clock-mode-line-total
@@ -6618,6 +6629,17 @@ about what to do with it.
timestamp[fn:: The corresponding in-buffer setting is: =#+STARTUP:
lognoteclock-out=.].
+ #+vindex: org-clock-out-switch-to-state
+ #+vindex: org-clock-out-next-state
+ #+findex: org-clock-out-next-state-function
+ The variable ~org-clock-out-switch-to-state~ controls if and how a
+ current task's TODO state is changed. No change (a ~nil~) is the
+ default. A specific state may be forced with a string value. The
+ ~org-clock-out-next-state~ alist may be utilized by setting it to
+ ~org-clock-out-next-state-function~, or a custom function may be
+ used. This custom function should take the current state, and
+ return either a new state or ~nil~ to keep the current state.
+
- {{{kbd(C-c C-x C-x)}}} (~org-clock-in-last~) ::
#+kindex: C-c C-x C-x
--
2.37.3
--
Samuel W. Flint
4096R/FA13D704
(F50D 862B 4F65 5943 A8C2 EF0E 86C9 3E7A FA13 D704)
λs.(s s) λs.(s s)
O< ascii ribbon campaign - stop html mail - www.asciiribbon.org
^ permalink raw reply related [flat|nested] 5+ messages in thread
* Re: [PATCH 2/2] doc/org-manual.org: Document org-clock-{in,out}-switch-to-state
2022-10-22 18:29 [PATCH 2/2] doc/org-manual.org: Document org-clock-{in,out}-switch-to-state Samuel W. Flint
@ 2022-10-24 9:13 ` Ihor Radchenko
2022-10-24 14:14 ` Samuel W. Flint
0 siblings, 1 reply; 5+ messages in thread
From: Ihor Radchenko @ 2022-10-24 9:13 UTC (permalink / raw)
To: Samuel W. Flint; +Cc: Org-Mode
"Samuel W. Flint" <swflint+orgmode@flintfam.org> writes:
> + #+vindex: org-clock-in-switch-to-state
> + #+vindex: org-clock-in-next-state
> + #+findex: org-clock-in-next-state-function
> + The variable ~org-clock-in-switch-to-state~ controls if and how a
> + current task's TODO state is changed. No change (a ~nil~) is the
> + default. A specific state may be forced with a string value. The
> + ~org-clock-in-next-state~ alist may be utilized by setting it to
> + ~org-clock-in-next-state-function~, or a custom function may be
> + used. This custom function should take the current state, and
> + return either a new state or ~nil~ to keep the current state.
First of all, thanks for the patch!
However, it is not clear for me what is the purpose of this new feature
(even after reading the proposed patch to the manual).
Could you please explain in simple words when your new feature can be
useful?
--
Ihor Radchenko // yantar92,
Org mode contributor,
Learn more about Org mode at <https://orgmode.org/>.
Support Org development at <https://liberapay.com/org-mode>,
or support my work at <https://liberapay.com/yantar92>
^ permalink raw reply [flat|nested] 5+ messages in thread
* Re: [PATCH 2/2] doc/org-manual.org: Document org-clock-{in,out}-switch-to-state
2022-10-24 9:13 ` Ihor Radchenko
@ 2022-10-24 14:14 ` Samuel W. Flint
2022-10-25 7:27 ` Ihor Radchenko
0 siblings, 1 reply; 5+ messages in thread
From: Samuel W. Flint @ 2022-10-24 14:14 UTC (permalink / raw)
To: Ihor Radchenko; +Cc: Samuel W. Flint, Org-Mode
>>>>> Ihor Radchenko writes:
IR> "Samuel W. Flint" <swflint+orgmode@flintfam.org> writes:
>> + #+vindex: org-clock-in-switch-to-state
>> + #+vindex: org-clock-in-next-state
>> + #+findex: org-clock-in-next-state-function
>> + The variable ~org-clock-in-switch-to-state~ controls if and how a
>> + current task's TODO state is changed. No change (a ~nil~) is the
>> + default. A specific state may be forced with a string value. The
>> + ~org-clock-in-next-state~ alist may be utilized by setting it to
>> + ~org-clock-in-next-state-function~, or a custom function may be
>> + used. This custom function should take the current state, and
>> + return either a new state or ~nil~ to keep the current state.
IR> First of all, thanks for the patch!
IR> However, it is not clear for me what is the purpose of this new feature
IR> (even after reading the proposed patch to the manual).
IR> Could you please explain in simple words when your new feature can be
IR> useful?
The variable `org-clock-in-switch-to-state` can be really handy,
however, it wasn't documented in the manual which made discovery
somewhat difficult. The manual patch documents the variable, as well as
a new variable exposed through customize to describe how states should
change on clock-in/clock-out. This means that instead of having to
write a custom function to do this, it's provided and exposed through
customize and thus should be more discoverable and hopefully usable.
Patch 1/2 provides the implementation.
Consider, for example, the following settings:
(setf org-clock-in-switch-to-state 'org-clock-in-next-state-function
org-clock-in-next-state '(("TODO" . "WORKING")
("WAITING" . "WORKING")))
And the following heading:
* TODO Do a thing
When clocking in, it will become:
* WORKING Do a thing
On the next clock-in, it will stay at "WORKING". Consider instead:
* WAITING Waiting to do a thing
On clock-in to this heading, it becomes
* WORKING Waiting to do a thing
This can be applied similarly for org-clock-out, though I'm not sure how
useful that will be.
hth,
Sam
--
Samuel W. Flint
4096R/FA13D704
(F50D 862B 4F65 5943 A8C2 EF0E 86C9 3E7A FA13 D704)
λs.(s s) λs.(s s)
O< ascii ribbon campaign - stop html mail - www.asciiribbon.org
^ permalink raw reply [flat|nested] 5+ messages in thread
* Re: [PATCH 2/2] doc/org-manual.org: Document org-clock-{in,out}-switch-to-state
2022-10-24 14:14 ` Samuel W. Flint
@ 2022-10-25 7:27 ` Ihor Radchenko
2023-07-16 8:24 ` Ihor Radchenko
0 siblings, 1 reply; 5+ messages in thread
From: Ihor Radchenko @ 2022-10-25 7:27 UTC (permalink / raw)
To: Samuel W. Flint; +Cc: Samuel W. Flint, Org-Mode
"Samuel W. Flint" <swflint@flintfam.org> writes:
> IR> Could you please explain in simple words when your new feature can be
> IR> useful?
>
> The variable `org-clock-in-switch-to-state` can be really handy,
> however, it wasn't documented in the manual which made discovery
> somewhat difficult. The manual patch documents the variable, as well as
> a new variable exposed through customize to describe how states should
> change on clock-in/clock-out. This means that instead of having to
> write a custom function to do this, it's provided and exposed through
> customize and thus should be more discoverable and hopefully usable.
> Patch 1/2 provides the implementation.
>
> Consider, for example, the following settings:
>
> (setf org-clock-in-switch-to-state 'org-clock-in-next-state-function
> org-clock-in-next-state '(("TODO" . "WORKING")
> ("WAITING" . "WORKING")))
Such example would look nice in the patch to the manual.
Also, why not simply allow the alist to be another allowed value of
`org-clock-in-switch-to-state'? Using an extra function is cumbersome
and also confusing.
> This can be applied similarly for org-clock-out, though I'm not sure how
> useful that will be.
I really do not see much value in changing todo state on clock out.
Maybe others do.
--
Ihor Radchenko // yantar92,
Org mode contributor,
Learn more about Org mode at <https://orgmode.org/>.
Support Org development at <https://liberapay.com/org-mode>,
or support my work at <https://liberapay.com/yantar92>
^ permalink raw reply [flat|nested] 5+ messages in thread
* Re: [PATCH 2/2] doc/org-manual.org: Document org-clock-{in,out}-switch-to-state
2022-10-25 7:27 ` Ihor Radchenko
@ 2023-07-16 8:24 ` Ihor Radchenko
0 siblings, 0 replies; 5+ messages in thread
From: Ihor Radchenko @ 2023-07-16 8:24 UTC (permalink / raw)
To: Samuel W. Flint; +Cc: Samuel W. Flint, Org-Mode
Canceled.
See https://orgmode.org/list/875y6kjmfb.fsf@localhost
--
Ihor Radchenko // yantar92,
Org mode contributor,
Learn more about Org mode at <https://orgmode.org/>.
Support Org development at <https://liberapay.com/org-mode>,
or support my work at <https://liberapay.com/yantar92>
^ permalink raw reply [flat|nested] 5+ messages in thread
end of thread, other threads:[~2023-07-16 8:24 UTC | newest]
Thread overview: 5+ messages (download: mbox.gz follow: Atom feed
-- links below jump to the message on this page --
2022-10-22 18:29 [PATCH 2/2] doc/org-manual.org: Document org-clock-{in,out}-switch-to-state Samuel W. Flint
2022-10-24 9:13 ` Ihor Radchenko
2022-10-24 14:14 ` Samuel W. Flint
2022-10-25 7:27 ` Ihor Radchenko
2023-07-16 8:24 ` Ihor Radchenko
Code repositories for project(s) associated with this public inbox
https://git.savannah.gnu.org/cgit/emacs/org-mode.git
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).