org-contrib/org-choose.org

   1 #+TITLE:     org-choose.el -- decision management for org-mode
   2 #+OPTIONS:   ^:{} author:nil
   3 #+STARTUP: odd
   4
   5 Org-choose supports decision management.
   6
   7 * General
   8
   9 org-choose operates on a group of sibling items in org-mode.  It
  10 treats them as potential choices in some decision.
  11
  12 The items have marks such as "CHOSEN", "MAYBE", or "REJECTED".  You
  13 can configure the set of marks.  The marks behave similarly to TODO
  14 marks.  org-choose keeps the marks in a consistent overall state.
  15
  16 A sibling item that has no mark is assumed to not represent an
  17 alternative; so is an item with a mark from another keyword set.
  18
  19
  20 * How to use it
  21
  22 *** Overview of use
  23
  24 org-choose contains no user commands.  You use it by:
  25
  26   * Loading it
  27
  28   * Setting up at least one set of TODO keywords with the
  29     interpretation "choose".
  30
  31   * Operating on single items with the TODO commands.
  32
  33 *** Loading it (No surprises here)
  34
  35 The easiest way is by
  36
  37         M-x customize-apropos org-modules
  38
  39 Check the line for org-choose.  This will cause it to be loaded every
  40 time you start org-mode.
  41
  42 You'll still have to load it manually the first time.
  43
  44 Of course, you can also just try it out by loading it manually.
  45
  46 *** Setting up a keyword set
  47
  48 To use org-choose, you need to set up at least one set of TODO
  49 keywords with the interpretation "choose".  There are two basic ways.
  50 Both are essentially the same as for other TODO marks.
  51
  52     * By using the file directive #+CHOOSE_TODO:
  53
  54     * By M-x customize-apropos org-todo-keywords
  55
  56 **** The markings
  57
  58 The format of marks is essentially that of ordinary TODO marks.  The
  59 marks can have parenthesized arguments that indicate key bindings and
  60 similar shortcuts.
  61
  62 In addition, they can optionally have a second argument.  The
  63 arguments are separated by a comma.  The second argument can have one
  64 of 3 values:
  65
  66  * 0 :: The mark with this argument is the default mark.  New items
  67         will have that mark, if they are from this TODO keyword set.
  68
  69  * - :: This mark with this argument is at the bottom of the "NOT
  70         CHOSEN" range (See [[id:3698439c-93d5-4242-b566-96e760f64108][About consistent state]]).  It should be
  71         lower than the default mark (0). If this is omitted,
  72         org-choose will not try to keep marks in consistent state.
  73
  74  * + :: This mark with this argument is at the top of the "CHOSEN"
  75         range.  It should be higher than the default mark (0). If this
  76         is omitted, org-choose will use the highest mark instead.
  77
  78 No value should be given twice.
  79
  80 This works even if there is no first argument; just give an empty
  81 string as the first argument.
  82
  83 ***** Examples of marks
  84
  85  * REJECTED :: Makes a mark whose text is "REJECTED".
  86  * MAYBE(,0) :: Makes a mark whose text is "MAYBE".  It is the default
  87                 mark.
  88  * CHOSEN(c,+) :: Makes a mark whose text is "CHOSEN".  It is the top
  89                   of the high range.  The key "c" will select it,
  90                   exactly as the usual TODO hotkey behavior.
  91
  92 **** Examples of mark specs
  93
  94  * #+CHOOSE_TODO: NO(,-) MAYBE(,0) YES
  95  * #+CHOOSE_TODO: REJECTED(r) NOT_CHOSEN(n,-) MAYBE(,0) LEANING_TOWARDS(l) CHOSEN(c,+)
  96
  97 *** Operating on items
  98
  99 You can operate on single items with the usual TODO commands.
 100
 101     * Use C-S-right to change the keyword set.  Use this to change to
 102       the "choose" keyword set that you just defined.
 103
 104     * Use S-right to advance the TODO mark to the next setting.
 105
 106       For "choose", that means you like this alternative more than
 107       before.  Other alternatives will be automatically demoted to
 108       keep your settings consistent.
 109
 110     * Use S-left to demote TODO to the previous setting.
 111
 112       For "choose", that means you don't like this alternative as much
 113       as before.  Other alternatives will be automatically promoted,
 114       if this item was all that was keeping them down.
 115
 116     * All the other TODO commands are available and behave essentially
 117       the normal way.
 118
 119
 120
 121 * About consistent state
 122    :PROPERTIES:
 123    :ID:       3698439c-93d5-4242-b566-96e760f64108
 124    :END:
 125
 126 org-choose tries to keep each group of items in a consistent state.
 127
 128 It knows about 2 ranges of marks that relate to each other in mirror
 129 image fashion.  We can call them the "CHOSEN" range and the "NOT
 130 CHOSEN" range.
 131
 132 If some item is marked in the "CHOSEN" range, other items can't be
 133 marked higher than the mirror-corresponding entry in the "NOT CHOSEN"
 134 range.
 135
 136 *** An example
 137
 138 For this example, assume we're using the marks from the second example
 139 spec,
 140
 141         "REJECTED(r) NOT_CHOSEN(n,-) MAYBE(,0) LEANING_TOWARDS(l)
 142         CHOSEN(c,+)"
 143
 144 Then org-choose enforces the following constraints:
 145
 146 | If any   |   | then the other |   |
 147 | item is: |   | items can't be |   |
 148 |          |   | higher than:   |   |
 149 |----------+---+----------------+---|
 150 | CHOSEN   | 1 | NOT CHOSEN     | 4 |
 151 | FAVORED  | 2 | MAYBE          | 3 |
 152 |----------+---+----------------+---|
 153
 154
 155 * Credits
 156
 157 org-choose was written by Tom Breton, with much-appreciated advice
 158 from Carsten Dominik.
 159
 160