about summary refs log tree commit diff
diff options
context:
space:
mode:
authorGriffin Smith <root@gws.fyi>2019-09-05T20·41-0400
committerGriffin Smith <root@gws.fyi>2019-09-05T20·42-0400
commitfe52639a3a4e6f97c0a6283e08cf200f97b9831a (patch)
tree4e941e88891646b4f5c8e7281038d6384a9e5cb9
parent6b701daaa5e49b53065556dc441914718f518c18 (diff)
Expand documentation for org-clubhouse-mode
Expand the documentation for the automatic updating of story statuses to
include explicit documentation for org-clubhouse-state-alist.

Ref #18
-rw-r--r--README.org34
1 files changed, 26 insertions, 8 deletions
diff --git a/README.org b/README.org
index be3423598e93..0300381ba02c 100644
--- a/README.org
+++ b/README.org
@@ -50,14 +50,6 @@ Once installed, you'll need to set three global config vars:
 You can generate a new personal API token by going to the "API Tokens" tab on
 the "Settings" page in the clubhouse UI.
 
-Org-clubhouse can be configured to update the status of stories as you update
-their todo-keyword in org-mode. To opt-into this behavior, set the
-~org-clubhouse-mode~ minor-mode:
-
-#+BEGIN_SRC emacs-lisp
-(add-hook 'org-mode-hook #'org-clubhouse-mode nil nil)
-#+END_SRC
-
 * Usage
 
 ** Reading from clubhouse
@@ -97,6 +89,32 @@ their todo-keyword in org-mode. To opt-into this behavior, set the
   Adds the user configured in ~org-clubhouse-username~ as the owner of the
   clubhouse story associated with the headline at point
 
+*** Automatically updating Clubhouse story statuses
+
+Org-clubhouse can be configured to update the status of stories as you update
+their todo-keyword in org-mode. To opt-into this behavior, set the
+~org-clubhouse-mode~ minor-mode:
+
+#+BEGIN_SRC emacs-lisp
+(add-hook 'org-mode-hook #'org-clubhouse-mode nil nil)
+#+END_SRC
+
+The mapping from org-mode todo-keywords is configured via the
+~org-clubhouse-state-alist~ variable, which should be an [[https://www.gnu.org/software/emacs/manual/html_node/elisp/Association-Lists.html][alist]] mapping (string)
+[[https://orgmode.org/manual/Workflow-states.html][org-mode todo-keywords]] to the (string) names of their corresponding workflow
+state. You can have todo-keywords that don't map to a workflow state (I use this
+in my workflow extensively) and org-clubhouse will just preserve the previous
+state of the story when moving to that state.
+
+An example config:
+
+#+BEGIN_SRC emacs-lisp
+(setq org-clubhouse-state-alist
+      '(("TODO"   . "To Do")
+        ("ACTIVE" . "In Progress")
+        ("DONE"   . "Done")))
+#+END_SRC
+
 * Philosophy
 
 I use org-mode every single day to manage tasks, notes, literate programming,