org-contrib/org-depend.org

   1 #+TITLE:     org-depend.el -- TODO dependencies for Org-mode
   2 #+OPTIONS:   ^:{} author:nil
   3 #+STARTUP: odd
   4
   5 * General
   6
   7 /org-depend.el/ demonstrates a mechanism for creating TODO
   8 dependencies.  Note that Org-mode does already have [[https://orgmode.org/manual/TODO-dependencies.html#TODO-dependencies][built-in local
   9 dependencies]] which are simpler and cover most of what one usually
  10 wants to do.  However, the built-in implementation covers only the
  11 following two concepts:
  12
  13 - blocking an entry from changing its state to DONE while it still has
  14   children that are not done, or checkboxes that are unchecked
  15 - blocking an entry from changing its state to DONE while it still has
  16   un-done siblings above it, in this way enforcing sequential work on
  17   the siblings
  18
  19 /org-depend.el/ was originally a proof-of-concept implementation of
  20 TODO dependencies, using two special hooks, =org-blocker-hook= and
  21 =org-trigger-hook=.  It remains in the distribution as an example on
  22 how more complex dependencies between entries can be implemented.  In
  23 particular it shows how to implement the following:
  24
  25 - Dependencies on remote entries identified by ID.  These entries do
  26   not have to be near-by and may even be located in a different file.
  27 - The possibility to /trigger/ actions in other entries.
  28
  29 * What is implemented?
  30
  31 ** Triggering
  32
  33 1) If an entry contains a TRIGGER property that contains the string
  34    =chain-siblings(KEYWORD)=, then switching that entry to DONE does
  35    do the following:
  36    - The sibling following this entry switched to todo-state KEYWORD.
  37    - The sibling also gets a TRIGGER property =chain-sibling(KEYWORD)=,
  38      property, to make sure that, when *it* is DONE, the chain will
  39      continue.
  40
  41 2) If an entry contains a TRIGGER property that contains the string
  42    =chain-siblings-scheduled=, then switching that entry to DONE does
  43    the following actions, similarly to =chain-siblings(KEYWORD)=:
  44    - The sibling receives the same scheduled time as the entry
  45      marked as DONE (or, in the case, in which there is no scheduled
  46      time, the sibling does not get any either).
  47    - The sibling also gets the same TRIGGER property
  48      =chain-siblings-scheduled=, so the chain can continue.
  49
  50 3) If the TRIGGER property contains the string
  51    =chain-find-next(KEYWORD[,OPTIONS])=, then switching that entry
  52    to DONE do the following:
  53    - All siblings are of the entry are collected into a temporary
  54      list and then filtered and sorted according to =OPTIONS=
  55    - The first sibling on the list is changed into =KEYWORD= state
  56    - The sibling also gets the same TRIGGER property
  57      =chain-find-next=, so the chain can continue.
  58
  59    OPTIONS should be a comma separated string without spaces, and can
  60    contain following options:
  61
  62    - =from-top= the candidate list is all of the siblings in the
  63      current subtree
  64    - =from-bottom= candidate list are all siblings from bottom up
  65    - =from-current= candidate list are all siblings from current item
  66      until end of subtree, then wrapped around from first sibling
  67    - =no-wrap= candidate list are siblings from current one down
  68    - =todo-only= Only consider siblings that have a todo keyword
  69    - =todo-and-done-only= Same as above but also include done items.
  70    - =priority-up=   sort by highest priority
  71    - =priority-down= sort by lowest priority
  72    - =effort-up=     sort by highest effort
  73    - =effort-down=   sort by lowest effort
  74
  75    There is also customizable variable =org-depend-find-next-options=
  76    that contains default options if none are specified. Its default
  77    value is =from-current,todo-only,priority-up=
  78
  79 4) If the TRIGGER property contains any other words like
  80    =XYZ(KEYWORD)=, these are treated as entry IDs with keywords.
  81    That means, Org-mode will search for an entry with the ID property
  82    XYZ and switch that entry to KEYWORD as well.
  83
  84 ** Blocking
  85
  86 1) If an entry contains a BLOCKER property that contains the word
  87    =previous-sibling=, the sibling above the current entry is
  88    checked when you try to mark it DONE.  If it is still in a TODO
  89    state, the current state change is blocked.
  90
  91 2) If the BLOCKER property contains any other words, these are
  92    treated as entry IDs.  That means, Org-mode will search for an
  93    entry with the ID property exactly equal to this word.  If any
  94    of these entries is not yet marked DONE, the current state change
  95    will be blocked.
  96
  97 3) Whenever a state change is blocked, an org-mark is pushed, so that
  98    you can find the offending entry with =C-c &=.
  99
 100 * Example
 101
 102 When trying this example, make sure that the settings for TODO keywords
 103 have been activated, i.e. include the following line and press C-c C-c
 104 on the line before working with the example:
 105
 106 #+begin_example
 107   #+TYP_TODO: TODO NEXT | DONE
 108 #+end_example
 109
 110 OK, here is the example.
 111
 112 #+begin_src org
 113   ,* TODO Win a million in Las Vegas
 114     :PROPERTIES:
 115       :ID: I-cannot-do-it-without-money
 116     :END:
 117
 118     The "third" TODO (see above) cannot become a TODO without this money.
 119
 120
 121   ,* Do this by doing a chain of TODOs
 122   ,** NEXT This is the first in this chain
 123      :PROPERTIES:
 124        :TRIGGER: chain-siblings(NEXT)
 125      :END:
 126
 127   ,** This is the second in this chain
 128
 129   ,** This is the third in this chain
 130      :PROPERTIES:
 131        :BLOCKER: I-cannot-do-it-without-money
 132      :END:
 133
 134   ,** This is the forth in this chain
 135      :PROPERTIES:
 136        :TRIGGER: XYZ-is-my-id(TODO)
 137      :END:
 138
 139      When this is DONE, we will also trigger entry XYZ-is-my-id
 140
 141   ,** This is the fifth in this chain
 142
 143   ,* Start writing report
 144      :PROPERTIES:
 145        :ID: XYZ-is-my-id
 146      :END:
 147 #+end_src
 148
 149 * Advanced Triggerring Example
 150
 151 In advanced example we will add a hook to automatically insert
 152 =chain-find-next= TRIGGER when entry is changed to NEXT and
 153 automatically remove it otherwise.
 154
 155 First evaluate the following lisp code:
 156
 157 #+begin_src emacs-lisp
 158 (defun mm/org-insert-trigger ()
 159   "Automatically insert chain-find-next trigger when entry becomes NEXT"
 160   (cond ((equal org-state "NEXT")
 161          (unless org-depend-doing-chain-find-next
 162            (org-set-property "TRIGGER" "chain-find-next(NEXT,from-current,priority-up,effort-down)")))
 163         ((not (member org-state org-done-keywords))
 164          (org-delete-property "TRIGGER"))))
 165
 166 (add-hook 'org-after-todo-state-change-hook 'mm/org-insert-trigger)
 167 #+end_src
 168
 169 Now in the following org file, try changing item TODO state to
 170 NEXT. You should see properties drawer appear with the TRIGGER
 171 property inside.
 172
 173 Try marking the NEXT item DONE. The next item should automatically
 174 become NEXT.
 175
 176 Change priority of one of the items to =[#A]=, then mark the NEXT item
 177 DONE. The highest priority item will automatically become NEXT.
 178
 179 #+begin_src org
 180 #+TYP_TODO: TODO NEXT | DONE
 181
 182 ,* Auto-NEXT example
 183 ,** TODO Make me NEXT, then mark me DONE
 184 ,** TODO Second item
 185 ,** TODO Third item
 186 ,** Plain item
 187 ,** TODO Change my priority
 188 #+end_src
 189
 190 * Usage Examples
 191
 192 [[http://karl-voit.at/2016/12/18/org-depend/][Here is a blog article]] that shows the usage of org-depend in
 193 combination with [[https://github.com/joaotavora/yasnippet][yasnipet]] or [[https://github.com/Kungsgeten/yankpad][yankpad]].
 194
 195 An advanced workflow with dependencies is auto-generated from a
 196 template snippet using the =BLOCKER= and =TRIGGER= keywords.
 197
 198 Some of those things were demonstrated in [[http://karl-voit.at/2014/12/03/emacs-chat/][an Emacs Chat by Sacha Chua
 199 with Karl Voit]].
 200
 201 [[http://karl-voit.at/2016/12/18/org-depend/][The blog article]] further discusses some ideas on how to improve the
 202 =org-depend= functionality with an ID picker, a mnemonic ID
 203 auto-generator, a workflow assistent, advanced =TRIGGER= commands to
 204 add scheduled dates, and inheritance of todo-cancelation.