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

["Samuel W. Flint" <swflint@flintfam.org>]

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