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 any other words like
  51    =XYZ(KEYWORD)=, these are treated as entry IDs with keywords.
  52    That means, Org-mode will search for an entry with the ID property
  53    XYZ and switch that entry to KEYWORD as well.
  54
  55 ** Blocking
  56
  57 1) If an entry contains a BLOCKER property that contains the word
  58    =previous-sibling=, the sibling above the current entry is
  59    checked when you try to mark it DONE.  If it is still in a TODO
  60    state, the current state change is blocked.
  61
  62 2) If the BLOCKER property contains any other words, these are
  63    treated as entry IDs.  That means, Org-mode will search for an
  64    entry with the ID property exactly equal to this word.  If any
  65    of these entries is not yet marked DONE, the current state change
  66    will be blocked.
  67
  68 3) Whenever a state change is blocked, an org-mark is pushed, so that
  69    you can find the offending entry with =C-c &=.
  70
  71 * Example
  72
  73 When trying this example, make sure that the settings for TODO keywords
  74 have been activated, i.e. include the following line and press C-c C-c
  75 on the line before working with the example:
  76
  77 #+begin_src
  78 #+TYP_TODO: TODO NEXT | DONE
  79 #+end_src
  80
  81 OK, here is the example.
  82
  83 #+begin_src org
  84 ,* TODO Win a million in Las Vegas
  85 ,  The "third" TODO (see above) cannot become a TODO without this money.
  86
  87 ,  :PROPERTIES:
  88 ,    :ID: I-cannot-do-it-without-money
  89 ,  :END:
  90
  91 ,* Do this by doing a chain of TODOs
  92 ,** NEXT This is the first in this chain
  93 ,   :PROPERTIES:
  94 ,     :TRIGGER: chain-siblings(NEXT)
  95 ,   :END:
  96 ,
  97 ,** This is the second in this chain
  98
  99 ,** This is the third in this chain
 100 ,   :PROPERTIES:
 101 ,     :BLOCKER: I-cannot-do-it-without-money
 102 ,   :END:
 103
 104 ,** This is the forth in this chain
 105 ,   When this is DONE, we will also trigger entry XYZ-is-my-id
 106 ,   :PROPERTIES:
 107 ,     :TRIGGER: XYZ-is-my-id(TODO)
 108 ,   :END:
 109
 110 ,** This is the fifth in this chain
 111 ,
 112 ,* Start writing report
 113 ,   :PROPERTIES:
 114 ,     :ID: XYZ-is-my-id
 115 ,   :END:
 116 #+end_src