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 [[http://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 ,  The "third" TODO (see above) cannot become a TODO without this money.
 115
 116 ,  :PROPERTIES:
 117 ,    :ID: I-cannot-do-it-without-money
 118 ,  :END:
 119
 120 ,* Do this by doing a chain of TODOs
 121 ,** NEXT This is the first in this chain
 122 ,   :PROPERTIES:
 123 ,     :TRIGGER: chain-siblings(NEXT)
 124 ,   :END:
 125 ,
 126 ,** This is the second in this chain
 127
 128 ,** This is the third in this chain
 129 ,   :PROPERTIES:
 130 ,     :BLOCKER: I-cannot-do-it-without-money
 131 ,   :END:
 132
 133 ,** This is the forth in this chain
 134 ,   When this is DONE, we will also trigger entry XYZ-is-my-id
 135 ,   :PROPERTIES:
 136 ,     :TRIGGER: XYZ-is-my-id(TODO)
 137 ,   :END:
 138
 139 ,** This is the fifth in this chain
 140 ,
 141 ,* Start writing report
 142 ,   :PROPERTIES:
 143 ,     :ID: XYZ-is-my-id
 144 ,   :END:
 145 #+end_src
 146
 147 * Advanced Triggerring Example
 148
 149 In advanced example we will add a hook to automatically insert
 150 =chain-find-next= TRIGGER when entry is changed to NEXT and
 151 automatically remove it otherwise.
 152
 153 First evaluate the following lisp code:
 154
 155 #+begin_src emacs-lisp
 156 (defun mm/org-insert-trigger ()
 157   "Automatically insert chain-find-next trigger when entry becomes NEXT"
 158   (cond ((equal state "NEXT")
 159          (unless org-depend-doing-chain-find-next
 160            (org-set-property "TRIGGER" "chain-find-next(NEXT,from-current,priority-up,effort-down)")))
 161         ((not (member state org-done-keywords))
 162          (org-delete-property "TRIGGER"))))
 163
 164 (add-hook 'org-after-todo-state-change-hook 'mm/org-insert-trigger)
 165 #+end_src
 166
 167 Now in the following org file, try changing item TODO state to
 168 NEXT. You should see properties drawer appear with the TRIGGER
 169 property inside.
 170
 171 Try marking the NEXT item DONE. The next item should automatically
 172 become NEXT.
 173
 174 Change priority of one of the items to =[#A]=, then mark the NEXT item
 175 DONE. The highest priority item will automatically become NEXT.
 176
 177 #+begin_src org
 178 #+TYP_TODO: TODO NEXT | DONE
 179
 180 ,* Auto-NEXT example
 181 ,** TODO Make me NEXT, then mark me DONE
 182 ,** TODO Second item
 183 ,** TODO Third item
 184 ,** Plain item
 185 ,** TODO Change my priority
 186 #+end_src