[PATCH 2/2] doc/org-manual.org: Document org-clock-{in,out}-switch-to-state

[PATCH 2/2] doc/org-manual.org: Document org-clock-{in,out}-switch-to-state

[Samuel W. Flint]

* 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

Re: [PATCH 2/2] doc/org-manual.org: Document org-clock-{in,out}-switch-to-state

[Ihor Radchenko]

"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>

Re: [PATCH 2/2] doc/org-manual.org: Document org-clock-{in,out}-switch-to-state

[Samuel W. Flint]

>>>>> 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

Re: [PATCH 2/2] doc/org-manual.org: Document org-clock-{in,out}-switch-to-state

[Ihor Radchenko]

"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>

Re: [PATCH 2/2] doc/org-manual.org: Document org-clock-{in,out}-switch-to-state

[Ihor Radchenko]

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>