Added support for "habit tracking"

Added support for "habit tracking"

[John Wiegley]

[-- Attachment #1: Type: text/plain, Size: 1393 bytes --]

There are really two kinds of TODOs on people's lists:

   1. Those whose importance is that they get done.
   2. Those whose importance is that they are done consistently.

I think most married people will know what I mean.  If you wash the  
dishes once after not having done it all month, you're not likely to  
win much applause.  But if you mow the lawn every month like  
clockwork, it's the regularity that does it.

Tracking habits isn't suited to a regular task manager, however.  You  
can see that the task needs to be done in your agenda, but you don't  
know if it's a task that sorely needs attention because you've been  
neglecting it, or if you've really been on the ball and don't _have_  
to do it today.

In the commercial world there is an app to address this kind of task  
called Sciral Consistency (http://sciral.com/consistency/).  I've been  
using it for about a year, and it's fantastic for making sure I keep  
up on my everyday duties, both at work and at home.

Well, I've implemented the functionality of Sciral for Org.  It works  
just as described on the Sciral webpage, complete with colorful graphs  
that appear to the right of the task name in the agenda buffer.  The  
graph even follows the same coloring algorithm as Sciral.

To test out this new feature, apply the attached patches and read the  
new manual section on "Tracking your habits".

John


[-- Attachment #2: 0001-Improvement-to-org-repeat-re.patch --]
[-- Type: application/octet-stream, Size: 1466 bytes --]

From 49cbd5355a8d76fe64cbad8785807f1166097096 Mon Sep 17 00:00:00 2001
From: John Wiegley <johnw@newartisans.com>
Date: Mon, 19 Oct 2009 03:58:45 -0400
Subject: [PATCH 1/5] Improvement to `org-repeat-re'

(org-repeat-re): Improved regexp to include .+ and ++ leaders for repeat
strings.
---
 lisp/ChangeLog |    5 +++++
 lisp/org.el    |    2 +-
 2 files changed, 6 insertions(+), 1 deletions(-)

diff --git a/lisp/ChangeLog b/lisp/ChangeLog
index c437305..efb6466 100755
--- a/lisp/ChangeLog
+++ b/lisp/ChangeLog
@@ -1,5 +1,10 @@
 2009-10-19  John Wiegley  <johnw@newartisans.com>
 
+	* org.el (org-repeat-re): Improved regexp to include .+ and ++
+	leaders for repeat strings.
+
+2009-10-19  John Wiegley  <johnw@newartisans.com>
+
 	* org-agenda.el (org-agenda-auto-exclude-function): New
 	customization variable for allowing the user to create an "auto
 	exclusion" filter for doing context-aware auto tag filtering.
diff --git a/lisp/org.el b/lisp/org.el
index 5b254d1..182234e 100644
--- a/lisp/org.el
+++ b/lisp/org.el
@@ -474,7 +474,7 @@ An entry can be toggled between QUOTE and normal with
   :type 'string)
 
 (defconst org-repeat-re
-  "<[0-9]\\{4\\}-[0-9][0-9]-[0-9][0-9] [^>\n]*\\([.+]?\\+[0-9]+[dwmy]\\)"
+  "<[0-9]\\{4\\}-[0-9][0-9]-[0-9][0-9] [^>\n]*\\([.+]+?\\+[0-9]+[dwmy]\\)"
   "Regular expression for specifying repeated events.
 After a match, group 1 contains the repeat expression.")
 
-- 
1.6.5


[-- Attachment #3: 0002-Added-tagline-parameter-to-org-get-repeat.patch --]
[-- Type: application/octet-stream, Size: 1790 bytes --]

From f604a7ecec7295cfbe4dd38519d38e16b51d9080 Mon Sep 17 00:00:00 2001
From: John Wiegley <johnw@newartisans.com>
Date: Mon, 19 Oct 2009 03:59:42 -0400
Subject: [PATCH 2/5] Added tagline parameter to `org-get-repeat'

(org-get-repeat): Now takes a string parameter `tagline', so the caller
can obtain the SCHEDULED repeat, or the DEADLINE repeat.
---
 lisp/ChangeLog |    2 ++
 lisp/org.el    |   10 ++++++----
 2 files changed, 8 insertions(+), 4 deletions(-)

diff --git a/lisp/ChangeLog b/lisp/ChangeLog
index efb6466..a5f8b7f 100755
--- a/lisp/ChangeLog
+++ b/lisp/ChangeLog
@@ -2,6 +2,8 @@
 
 	* org.el (org-repeat-re): Improved regexp to include .+ and ++
 	leaders for repeat strings.
+	(org-get-repeat): Now takes a string parameter `tagline', so the
+	caller can obtain the SCHEDULED repeat, or the DEADLINE repeat.
 
 2009-10-19  John Wiegley  <johnw@newartisans.com>
 
diff --git a/lisp/org.el b/lisp/org.el
index 182234e..2b202d8 100644
--- a/lisp/org.el
+++ b/lisp/org.el
@@ -10047,14 +10047,16 @@ Returns the new TODO keyword, or nil if no state change should occur."
 	     (throw 'exit t)))
       nil)))
 
-(defun org-get-repeat ()
+(defun org-get-repeat (&optional tagline)
   "Check if there is a deadline/schedule with repeater in this entry."
   (save-match-data
     (save-excursion
       (org-back-to-heading t)
-      (if (re-search-forward
-	   org-repeat-re (save-excursion (outline-next-heading) (point)) t)
-	  (match-string 1)))))
+      (and (re-search-forward (if tagline
+				  (concat tagline ":[^:]+" org-repeat-re)
+				org-repeat-re)
+			      (org-entry-end-position) t)
+	   (match-string-no-properties 1)))))
 
 (defvar org-last-changed-timestamp)
 (defvar org-last-inserted-timestamp)
-- 
1.6.5


[-- Attachment #4: 0003-Set-day-of-week-in-result-from-org-parse-time-string.patch --]
[-- Type: application/octet-stream, Size: 1716 bytes --]

From be58bd294b741a50474c276e8d719f731973257b Mon Sep 17 00:00:00 2001
From: John Wiegley <johnw@newartisans.com>
Date: Mon, 19 Oct 2009 04:00:35 -0400
Subject: [PATCH 3/5] Set day-of-week in result from `org-parse-time-string'

(org-parse-time-string): Set the day-of-week field after parsing a time,
since this information is always in the time string.
---
 lisp/ChangeLog |    2 ++
 lisp/org.el    |    9 ++++++++-
 2 files changed, 10 insertions(+), 1 deletions(-)

diff --git a/lisp/ChangeLog b/lisp/ChangeLog
index a5f8b7f..6810f7e 100755
--- a/lisp/ChangeLog
+++ b/lisp/ChangeLog
@@ -4,6 +4,8 @@
 	leaders for repeat strings.
 	(org-get-repeat): Now takes a string parameter `tagline', so the
 	caller can obtain the SCHEDULED repeat, or the DEADLINE repeat.
+	(org-parse-time-string): Set the day-of-week field after parsing a
+	time, since this information is always in the time string.
 
 2009-10-19  John Wiegley  <johnw@newartisans.com>
 
diff --git a/lisp/org.el b/lisp/org.el
index 2b202d8..eb45eea 100644
--- a/lisp/org.el
+++ b/lisp/org.el
@@ -13457,7 +13457,14 @@ hour and minute fields will be nil if not given."
 	    (string-to-number (match-string 4 s))
 	    (string-to-number (match-string 3 s))
 	    (string-to-number (match-string 2 s))
-	    nil nil nil)
+	    (let ((dow (match-string 5 s)))
+	      (cond ((string= dow "Sun") 0)
+		    ((string= dow "Mon") 1)
+		    ((string= dow "Tue") 2)
+		    ((string= dow "Wed") 3)
+		    ((string= dow "Thu") 4)
+		    ((string= dow "Fri") 5)
+		    ((string= dow "Sat") 6))) nil nil)
     (error "Not a standard Org-mode time string: %s" s)))
 
 (defun org-timestamp-up (&optional arg)
-- 
1.6.5


[-- Attachment #5: 0004-Added-some-missing-text-to-the-manual.patch --]
[-- Type: application/octet-stream, Size: 890 bytes --]

From 3c0dfce39f4467b6fda19e1d3dfb9b675b214c37 Mon Sep 17 00:00:00 2001
From: John Wiegley <johnw@newartisans.com>
Date: Mon, 19 Oct 2009 04:04:07 -0400
Subject: [PATCH 4/5] Added some missing text to the manual

---
 doc/org.texi |    2 +-
 1 files changed, 1 insertions(+), 1 deletions(-)

diff --git a/doc/org.texi b/doc/org.texi
index 5ae6575..b8e4eed 100644
--- a/doc/org.texi
+++ b/doc/org.texi
@@ -231,7 +231,7 @@ Dates and Times
 * Creating timestamps::         Commands which insert timestamps
 * Deadlines and scheduling::    Planning your work
 * Clocking work time::          Tracking how long you spend on a task
-* Resolving idle time::         
+* Resolving idle time::         Resolving time if you've been idle
 * Effort estimates::            Planning work effort in advance
 * Relative timer::              Notes with a running timer
 
-- 
1.6.5


[-- Attachment #6: 0005-Added-support-for-habit-consistency-tracking.patch --]
[-- Type: application/octet-stream, Size: 21254 bytes --]

From 617ccd1c2afe267f464a8b692db41c23329b6326 Mon Sep 17 00:00:00 2001
From: John Wiegley <johnw@newartisans.com>
Date: Mon, 19 Oct 2009 04:17:49 -0400
Subject: [PATCH 5/5] Added support for habit consistency tracking

org-habit.el: New file, which implements code to build a "habit
consistency graph".

org-agenda.el (org-agenda-get-deadlines)
(org-agenda-get-scheduled): Display consistency graphs when outputting
habits into the agenda.  The graphs are always relative to the current
time.

(org-format-agenda-item): Added new parameter `habitp', which indicates
whether we are formatting a habit or not.  Do not display "extra"
leading information if habitp is true.
---
 doc/ChangeLog      |    5 +
 doc/org.texi       |   75 +++++++++++++++++-
 lisp/ChangeLog     |   11 +++
 lisp/org-agenda.el |   56 +++++++++++---
 lisp/org-habit.el  |  223 ++++++++++++++++++++++++++++++++++++++++++++++++++++
 5 files changed, 358 insertions(+), 12 deletions(-)
 create mode 100644 lisp/org-habit.el

diff --git a/doc/ChangeLog b/doc/ChangeLog
index 4ae3099..76fbd32 100644
--- a/doc/ChangeLog
+++ b/doc/ChangeLog
@@ -1,3 +1,8 @@
+2009-10-19  John Wiegley  <johnw@newartisans.com>
+
+	* org.texi (Tracking your habits): Added a new section in the
+	manual about how to track habits.
+
 2009-10-18  Carsten Dominik  <carsten.dominik@gmail.com>
 
 	* org.texi (Pushing to MobileOrg): Mention that `org-directory'
diff --git a/doc/org.texi b/doc/org.texi
index b8e4eed..79606dc 100644
--- a/doc/org.texi
+++ b/doc/org.texi
@@ -198,6 +198,7 @@ Progress logging
 
 * Closing items::               When was this entry marked DONE?
 * Tracking TODO state changes::  When did the status change?
+* Tracking your habits::        How consistent have you been?
 
 Tags
 
@@ -231,7 +232,7 @@ Dates and Times
 * Creating timestamps::         Commands which insert timestamps
 * Deadlines and scheduling::    Planning your work
 * Clocking work time::          Tracking how long you spend on a task
-* Resolving idle time::         Resolving time if you've been idle
+* Resolving idle time::         
 * Effort estimates::            Planning work effort in advance
 * Relative timer::              Notes with a running timer
 
@@ -3524,6 +3525,7 @@ work time}.
 @menu
 * Closing items::               When was this entry marked DONE?
 * Tracking TODO state changes::  When did the status change?
+* Tracking your habits::        
 @end menu
 
 @node Closing items, Tracking TODO state changes, Progress logging, Progress logging
@@ -3558,7 +3560,7 @@ In the timeline (@pxref{Timeline}) and in the agenda
 display the TODO items with a @samp{CLOSED} timestamp on each day,
 giving you an overview of what has been done.
 
-@node Tracking TODO state changes,  , Closing items, Progress logging
+@node Tracking TODO state changes, Tracking your habits, Closing items, Progress logging
 @subsection Tracking TODO state changes
 @cindex drawer, for state change recording
 
@@ -3635,6 +3637,75 @@ settings like @code{TODO(!)}.  For example
   :END:
 @end example
 
+@node Tracking your habits,  , Tracking TODO state changes, Progress logging
+@subsection Tracking your habits
+@cindex habits
+
+Org has the ability to track the consistency of a special category of TODOs,
+which are called ``habits''.  A habit has the followed properties:
+
+@enumerate
+@item
+The property @code{STYLE} is set to the value @code{habit}.
+@item
+The TODO has a scheduled date, with a @code{.+} style repeat interval.
+@item
+It may also have a deadline set, as long as it also has a @code{.+} style
+repeat interval, and it starts a number of days after the scheduled date
+equal to the difference between the repeat intervals.  If you get this wrong,
+Org will alert you to what you've set incorrectly in your habit.
+@item
+You must also have state logging on the @code{DONE} enabled, in order for
+historical data to be represented in the consistency graph.
+@end enumerate
+
+To give you an idea of what the above rules look like, here is an actual
+habit, with some history:
+
+@example
+** TODO Shave
+   SCHEDULED: <2009-10-17 Sat .+2d> DEADLINE: <2009-10-19 Mon .+4d>
+   - State "DONE"       from "TODO"       [2009-10-15 Thu]
+   - State "DONE"       from "TODO"       [2009-10-12 Mon]
+   - State "DONE"       from "TODO"       [2009-10-10 Sat]
+   - State "DONE"       from "TODO"       [2009-10-04 Sun]
+   - State "DONE"       from "TODO"       [2009-10-02 Fri]
+   - State "DONE"       from "TODO"       [2009-09-29 Tue]
+   - State "DONE"       from "TODO"       [2009-09-25 Fri]
+   - State "DONE"       from "TODO"       [2009-09-19 Sat]
+   - State "DONE"       from "TODO"       [2009-09-16 Wed]
+   - State "DONE"       from "TODO"       [2009-09-12 Sat]
+   :PROPERTIES:
+   :STYLE:    habit
+   :LAST_REPEAT: [2009-10-19 Mon 00:36]
+   :END:
+@end example
+
+What this habit says is: I want to shave at least every 4 days, and at most
+every 2 days.  Imagine today is the 15th, for the purposes of this example.
+This means the habit will first appear in the agenda on Oct 17, after the
+minimum of 2 days has elapsed, and will appear overdue on Oct 19, after four
+days have elapsed.  But what's really useful about habits is they are
+displayed along with a conistency graph, which shows how consistent you've
+been at getting task done in the past.  The graph shows every day that the
+task was done over the past five weeks, with colors for each day.  The colors
+used are:
+
+@table @code
+@item Blue
+If the task wasn't to be done yet on that day.
+@item Green
+If the task could have been done on that day.
+@item Yellow
+If the task was going to be overdue on the next day.
+@item Red
+If the task was overdue on that day.
+@end table
+
+In addition to coloring each day, the day is also marked with an asterix if
+the task was actually done that day, and an exclamation mark to show where
+the current day falls in the graph.
+
 @node Priorities, Breaking down tasks, Progress logging, TODO Items
 @section Priorities
 @cindex priorities
diff --git a/lisp/ChangeLog b/lisp/ChangeLog
index 6810f7e..23bb298 100755
--- a/lisp/ChangeLog
+++ b/lisp/ChangeLog
@@ -1,5 +1,16 @@
 2009-10-19  John Wiegley  <johnw@newartisans.com>
 
+	* org-habit.el: New file, which implements code to build a "habit
+	consistency graph".
+
+	* org-agenda.el (org-agenda-get-deadlines)
+	(org-agenda-get-scheduled): Display consistency graphs when
+	outputting habits into the agenda.  The graphs are always relative
+	to the current time.
+	(org-format-agenda-item): Added new parameter `habitp', which
+	indicates whether we are formatting a habit or not.  Do not
+	display "extra" leading information if habitp is true.
+
 	* org.el (org-repeat-re): Improved regexp to include .+ and ++
 	leaders for repeat strings.
 	(org-get-repeat): Now takes a string parameter `tagline', so the
diff --git a/lisp/org-agenda.el b/lisp/org-agenda.el
index 730250b..71353df 100644
--- a/lisp/org-agenda.el
+++ b/lisp/org-agenda.el
@@ -4215,7 +4215,7 @@ the documentation of `org-diary'."
 	 (todayp (org-agenda-todayp date)) ; DATE bound by calendar
 	 (d1 (calendar-absolute-from-gregorian date))  ; DATE bound by calendar
 	 d2 diff dfrac wdays pos pos1 category tags
-	 ee txt head face s todo-state upcomingp donep timestr)
+	 ee txt head face s todo-state upcomingp donep timestr habitp)
     (goto-char (point-min))
     (while (re-search-forward regexp nil t)
       (catch :skip
@@ -4239,6 +4239,7 @@ the documentation of `org-diary'."
 	    (save-excursion
 	      (setq todo-state (org-get-todo-state))
 	      (setq donep (member todo-state org-done-keywords))
+	      (setq habitp (org-is-habit-p))
 	      (if (and donep
 		       (or org-agenda-skip-deadline-if-done
 			   (not (= diff 0))))
@@ -4267,8 +4268,14 @@ the documentation of `org-diary'."
 				    diff date)
 				 (format (nth 1 org-agenda-deadline-leaders)
 					 diff)))
-			     head category tags
-			     (if (not (= diff 0)) nil timestr)))))
+			     (if habitp
+				 (if (> (length head) 20)
+				     (substring head 0 20)
+				   (format "%-20s" head))
+			       head)
+			     category tags
+			     (if (not (= diff 0)) nil timestr)
+			     nil nil habitp))))
 	      (when txt
 		(setq face (org-agenda-deadline-face dfrac wdays))
 		(org-add-props txt props
@@ -4282,6 +4289,17 @@ the documentation of `org-diary'."
 		  'date (if upcomingp date d2)
 		  'face (if donep 'org-agenda-done face)
 		  'undone-face face 'done-face 'org-agenda-done)
+		;; If this TODO is a habit, append the consistency graph to
+		;; the todo line.
+		(when habitp
+		  (setq txt (concat txt "  "
+				    (org-habit-build-graph
+				     (org-habit-parse-todo)
+				     (time-subtract (current-time)
+						    (days-to-time (* 5 7)))
+				     (current-time)
+				     (time-add (current-time)
+					       (days-to-time 7))))))
 		(push txt ee))))))
     (nreverse ee)))
 
@@ -4311,11 +4329,11 @@ FRACTION is what fraction of the head-warning time has passed."
 	 mm
 	 (deadline-position-alist
 	  (mapcar (lambda (a) (and (setq mm (get-text-property
-					     0 'org-hd-marker a))
-				   (cons (marker-position mm) a)))
+					0 'org-hd-marker a))
+			      (cons (marker-position mm) a)))
 		  deadline-results))
 	 d2 diff pos pos1 category tags donep
-	 ee txt head pastschedp todo-state face timestr s)
+	 ee txt head pastschedp todo-state face timestr s habitp)
     (goto-char (point-min))
     (while (re-search-forward regexp nil t)
       (catch :skip
@@ -4337,6 +4355,7 @@ FRACTION is what fraction of the head-warning time has passed."
 	    (save-excursion
 	      (setq todo-state (org-get-todo-state))
 	      (setq donep (member todo-state org-done-keywords))
+	      (setq habitp (org-is-habit-p))
 	      (if (and donep
 		       (or org-agenda-skip-scheduled-if-done
 			   (not (= diff 0))))
@@ -4365,8 +4384,14 @@ FRACTION is what fraction of the head-warning time has passed."
 				 (car org-agenda-scheduled-leaders)
 			       (format (nth 1 org-agenda-scheduled-leaders)
 				       (- 1 diff)))
-			     head category tags
-			     (if (not (= diff 0)) nil timestr)))))
+			     (if habitp
+				 (if (> (length head) 20)
+				     (substring head 0 20)
+				   (format "%-20s" head))
+			       head)
+			     category tags
+			     (if (not (= diff 0)) nil timestr)
+			     nil nil habitp))))
 	      (when txt
 		(setq face
 		      (cond
@@ -4383,6 +4408,17 @@ FRACTION is what fraction of the head-warning time has passed."
 		  'priority (+ 94 (- 5 diff) (org-get-priority txt))
 		  'org-category category
 		  'todo-state todo-state)
+		;; If this TODO is a habit, append the consistency graph to
+		;; the todo line.
+		(when habitp
+		  (setq txt (concat txt "  "
+				    (org-habit-build-graph
+				     (org-habit-parse-todo)
+				     (time-subtract (current-time)
+						    (days-to-time (* 5 7)))
+				     (current-time)
+				     (time-add (current-time)
+					       (days-to-time 7))))))
 		(push txt ee))))))
     (nreverse ee)))
 
@@ -4462,7 +4498,7 @@ The flag is set if the currently compiled format contains a `%e'.")
   "Used by `org-compile-prefix-format' to remember the category field widh.")
 
 (defun org-format-agenda-item (extra txt &optional category tags dotime
-				     noprefix remove-re)
+				     noprefix remove-re habitp)
   "Format TXT to be inserted into the agenda buffer.
 In particular, it adds the prefix and corresponding text properties.  EXTRA
 must be a string and replaces the `%s' specifier in the prefix format.
@@ -4575,7 +4611,7 @@ Any match of REMOVE-RE will be removed from TXT."
 	(setq time (cond (s2 (concat s1 "-" s2))
 			 (s1 (concat s1 "......"))
 			 (t ""))
-	      extra (or extra "")
+	      extra (or (and (not habitp) extra) "")
 	      category (if (symbolp category) (symbol-name category) category)
 	      thecategory (copy-sequence category))
 	(if (string-match org-bracket-link-regexp category)
diff --git a/lisp/org-habit.el b/lisp/org-habit.el
new file mode 100644
index 0000000..a3face5
--- /dev/null
+++ b/lisp/org-habit.el
@@ -0,0 +1,223 @@
+;;; org-habit.el --- The habit tracking code for Org-mode
+
+;; Copyright (C) 2009
+;;   Free Software Foundation, Inc.
+
+;; Author: John Wiegley <johnw at gnu dot org>
+;; Keywords: outlines, hypermedia, calendar, wp
+;; Homepage: http://orgmode.org
+;; Version: 6.31trans
+;;
+;; This file is part of GNU Emacs.
+;;
+;; GNU Emacs is free software: you can redistribute it and/or modify
+;; it under the terms of the GNU General Public License as published by
+;; the Free Software Foundation, either version 3 of the License, or
+;; (at your option) any later version.
+
+;; GNU Emacs is distributed in the hope that it will be useful,
+;; but WITHOUT ANY WARRANTY; without even the implied warranty of
+;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+;; GNU General Public License for more details.
+
+;; You should have received a copy of the GNU General Public License
+;; along with GNU Emacs.  If not, see <http://www.gnu.org/licenses/>.
+;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
+;;
+;;; Commentary:
+
+;; This file contains the habit tracking code for Org-mode
+
+(require 'org)
+(eval-when-compile
+  (require 'cl)
+  (require 'calendar))
+
+(defgroup org-habit nil
+  "Options concerning habit tracking in Org-mode."
+  :tag "Org Habit"
+  :group 'org-progress)
+
+(defvar org-habit-clear-color "slateblue")
+(defvar org-habit-clear-future-color "powderblue")
+
+(defvar org-habit-ready-color "green")
+(defvar org-habit-ready-future-color "palegreen")
+
+(defvar org-habit-warning-color "yellow")
+(defvar org-habit-warning-future-color "palegoldenrod")
+
+(defvar org-habit-alert-color "yellow")
+(defvar org-habit-alert-future-color "palegoldenrod")
+
+(defvar org-habit-overdue-color "red")
+(defvar org-habit-overdue-future-color "mistyrose")
+
+(defun org-habit-duration-to-days (ts)
+  (if (string-match "\\([0-9]+\\)\\([dwmy]\\)\\'" ts)
+      ;; lead time is specified.
+      (floor (* (string-to-number (match-string 1 ts))
+		(cdr (assoc (match-string 2 ts)
+			    '(("d" . 1)    ("w" . 7)
+			      ("m" . 30.4) ("y" . 365.25))))))
+    (error "Invalid duration string: %s" ts)))
+
+(defun org-is-habit-p (&optional pom)
+  (string= "habit" (org-entry-get (or pom (point)) "STYLE")))
+
+(defun org-habit-parse-todo (&optional pom)
+  "Parse the TODO surrounding point for its habit-related data.
+Returns a list with the following elements:
+
+  0: Scheduled date for the habit (may be in the past)
+  1: \".+\"-style repeater for the schedule, in days
+  2: Optional deadline (nil if not present)
+  3: If deadline, the repeater for the deadline, otherwise nil
+  4: A list of all the past dates this todo was mark closed
+
+This list represents a \"habit\" for the rest of this module."
+  (save-excursion
+    (if pom (goto-char pom))
+    (assert (org-is-habit-p (point)))
+    (let ((scheduled (org-get-scheduled-time (point)))
+	  (scheduled-repeat (org-get-repeat "SCHEDULED"))
+	  (deadline (org-get-deadline-time (point)))
+	  (deadline-repeat (org-get-repeat "DEADLINE")))
+      (unless scheduled
+	(error "Habit has no scheduled date"))
+      (unless scheduled-repeat
+	(error "Habit has no scheduled repeat period"))
+      (unless (string-match "\\`\\.\\+[0-9]+" scheduled-repeat)
+	(error "Habit's scheduled repeat period does not match `.+[0-9]*'"))
+      (if (and deadline (not deadline-repeat))
+	  (error "Habit has a deadline, but no deadline repeat period"))
+      (if (and deadline
+	       (not (string-match "\\`\\.\\+[0-9]+" scheduled-repeat))) 
+	  (error "Habit's deadline repeat period does not match `.+[0-9]*'"))
+      (let ((sr-days (org-habit-duration-to-days scheduled-repeat))
+	    (dr-days (org-habit-duration-to-days deadline-repeat)))
+	(when (and scheduled deadline)
+	  (cond
+	   ((time-less-p deadline scheduled)
+	    (error "Habit's deadline date is before the scheduled date"))
+	   ((< dr-days sr-days)
+	    (error "Habit's deadline repeat period is less than scheduled"))
+	   ((/= (- (time-to-days deadline)
+		   (time-to-days scheduled))
+		(- dr-days sr-days))
+	    (error "Habit's deadline and scheduled period lengths are off"))))
+	(let ((end (org-entry-end-position))
+	      closed-dates)
+	  (org-back-to-heading t)
+	  (while (re-search-forward "- State \"DONE\".*\\[\\([^]]+\\)\\]" end t)
+	    (push (org-time-string-to-time (match-string-no-properties 1))
+		  closed-dates))
+	  (list scheduled sr-days deadline dr-days closed-dates))))))
+
+(defsubst org-habit-scheduled (habit)
+  (nth 0 habit))
+(defsubst org-habit-scheduled-repeat (habit)
+  (nth 1 habit))
+(defsubst org-habit-deadline (habit)
+  (nth 2 habit))
+(defsubst org-habit-deadline-repeat (habit)
+  (nth 3 habit))
+(defsubst org-habit-done-dates (habit)
+  (nth 4 habit))
+
+(defun org-habit-get-colors (habit &optional moment scheduled-time)
+  "Return faces for HABIT relative to MOMENT and SCHEDULED-TIME.
+MOMENT defaults to the current time if it is nil.
+SCHEDULED-TIME defaults to the habit's actual scheduled time if nil.
+
+Habits are assigned colors on the following basis:
+  Blue      Task is before the scheduled date.
+  Green     Task is on or after scheduled date, but before the
+            end of the schedule's repeat period.
+  Yellow    If the task has a deadline, then it is after schedule's
+            repeat period, but before the deadline.
+  Orange    The task has reached the deadline day, or if there is
+            no deadline, the end of the schedule's repeat period.
+  Red       The task has gone beyond the deadline day or the
+            schedule's repeat period."
+  (unless moment (setq moment (current-time)))
+  (let* ((scheduled (or scheduled-time (org-habit-scheduled habit)))
+	 (s-repeat (org-habit-scheduled-repeat habit))
+	 (scheduled-end (time-add scheduled (days-to-time s-repeat)))
+	 (d-repeat (org-habit-deadline-repeat habit))
+	 (deadline (if scheduled-time
+		       (time-add scheduled-time
+				 (days-to-time (- d-repeat s-repeat)))
+		     (org-habit-deadline habit))))
+    (cond
+     ((time-less-p moment scheduled)
+      (cons org-habit-clear-color org-habit-clear-future-color))
+     ((time-less-p moment scheduled-end)
+      (cons org-habit-ready-color org-habit-ready-future-color))
+     ((and deadline
+	   (time-less-p moment deadline))
+      (cons org-habit-warning-color org-habit-warning-future-color))
+     ((= (time-to-days moment)
+	 (if deadline
+	     (time-to-days deadline)
+	   (time-to-days scheduled-end)))
+      (cons org-habit-alert-color org-habit-alert-future-color))
+     (t
+      (cons org-habit-overdue-color org-habit-overdue-future-color)))))
+
+(defun org-habit-build-graph (habit &optional starting current ending)
+  "Build a color graph for the given HABIT, from STARTING to ENDING."
+  (message "Build graph starting: %s" (format-time-string "%c" starting))
+  (message "Build graph current:  %s" (format-time-string "%c" current))
+  (message "Build graph ending:   %s" (format-time-string "%c" ending))
+  (let ((done-dates (sort (org-habit-done-dates habit) 'time-less-p))
+	(s-repeat (org-habit-scheduled-repeat habit))
+	(day starting)
+	(current-days (time-to-days current))
+	last-done-date
+	(graph (make-string (1+ (- (time-to-days ending)
+				   (time-to-days starting))) ?\ ))
+	(index 0))
+    (if done-dates
+	(while (time-less-p (car done-dates) starting)
+	  (setq done-dates (cdr done-dates))))
+    (while (time-less-p day ending)
+      (let* ((now-days (time-to-days day))
+	     (in-the-past-p (< now-days current-days))
+	     (today-p (= now-days current-days))
+	     (colors (if (and in-the-past-p (not last-done-date))
+			 (cons org-habit-clear-color
+			       org-habit-clear-future-color)
+		       (org-habit-get-colors
+			habit day
+			(and in-the-past-p
+			     (time-add last-done-date
+				       (days-to-time s-repeat))))))
+	     markedp color)
+	(if today-p
+	    (aset graph index ?!)
+	  (when (and done-dates
+		     (= now-days (time-to-days (car done-dates))))
+	    (aset graph index ?*)
+	    (setq last-done-date (car done-dates)
+		  done-dates (cdr done-dates)
+		  markedp t)))
+	(setq color (if (or in-the-past-p
+			    today-p)
+			(car colors)
+		      (cdr colors)))
+	(if (and in-the-past-p
+		 (not (string= color org-habit-overdue-color))
+		 (not markedp))
+	    (setq color (cdr colors)))
+	(put-text-property index (1+ index)
+			   'face (list :background color) graph))
+      (setq day (time-add day (days-to-time 1))
+	    index (1+ index)))
+    graph))
+
+(provide 'org-habit)
+
+;; arch-tag: 
+
+;;; org-habit.el ends here
-- 
1.6.5


[-- Attachment #7: Type: text/plain, Size: 204 bytes --]

_______________________________________________
Emacs-orgmode mailing list
Remember: use `Reply All' to send replies to the list.
Emacs-orgmode@gnu.org
http://lists.gnu.org/mailman/listinfo/emacs-orgmode

Re: Added support for "habit tracking"

[John Wiegley]

Forgot to mention: To get a feel for what the consistency graph looks  
like in the agenda view, see this screenshot (based on the example in  
the manual):

   http://newartisans.com/habitgraph.png

John

Re: Added support for "habit tracking"

[Matt Lundin]

[-- Attachment #1: Type: text/plain, Size: 2281 bytes --]

John Wiegley <jwiegley@gmail.com> writes:

> Tracking habits isn't suited to a regular task manager, however.  You
> can see that the task needs to be done in your agenda, but you don't
> know if it's a task that sorely needs attention because you've been
> neglecting it, or if you've really been on the ball and don't _have_
> to do it today.
>
> Well, I've implemented the functionality of Sciral for Org.  It works
> just as described on the Sciral webpage, complete with colorful graphs
> that appear to the right of the task name in the agenda buffer.  The
> graph even follows the same coloring algorithm as Sciral.
>
> To test out this new feature, apply the attached patches and read the
> new manual section on "Tracking your habits".

Thanks for this addition to org mode! I had written a tutorial on
tracking habits with org-mode on Worg:

http://orgmode.org/worg/org-tutorials/tracking-habits.php

I'll have to update that now. :)

A few constructive comments:

1. The syntax for defining habits seems fairly complex. One must add a
repeating scheduled timestamp, a repeating deadline timestamp and a
property. I was wondering if there could be anyway to automate creating
new habits---e.g., a dialog that asks for the appropriate time spans.
(My own preference would be to use a new timestamp notation to indicate
habits. I'm not sure what this would look like. Perhaps something like
this: SCHEDULED: <2009-10-17 Sat !+2+2> --- where the first number is
the repeating span and the second is the "grace period". Of course, I
have no idea whether this is possible.)

2. It is somewhat cumbersome to add two repeating timestamps to the same
entry. If one sets up the first repeating timestamp, then one cannot add
a second timestamp automatically. I.e., the following error message
appears:

"Cannot change deadline on task with repeater, please do that by hand" 

3. The faces for the graph are difficult to read against dark
backgrounds. (See attached image.)

4. I currently use the tag :HABIT: to track habits. This allows for easy
filtering in the agenda. I'm wondering whether there might be an option
to designate habits with a user-defined tag rather than the STYLE
property. The advantage would be much faster agenda searches for habits.

Thanks again!

Matt


[-- Attachment #2: habits-orgmode.png --]
[-- Type: image/png, Size: 10960 bytes --]

[-- Attachment #3: Type: text/plain, Size: 204 bytes --]

_______________________________________________
Emacs-orgmode mailing list
Remember: use `Reply All' to send replies to the list.
Emacs-orgmode@gnu.org
http://lists.gnu.org/mailman/listinfo/emacs-orgmode

Re: Re: Added support for "habit tracking"

[Carsten Dominik]

On Oct 20, 2009, at 4:02 PM, Matt Lundin wrote:

> John Wiegley <jwiegley@gmail.com> writes:
>
>> Tracking habits isn't suited to a regular task manager, however.  You
>> can see that the task needs to be done in your agenda, but you don't
>> know if it's a task that sorely needs attention because you've been
>> neglecting it, or if you've really been on the ball and don't _have_
>> to do it today.
>>
>> Well, I've implemented the functionality of Sciral for Org.  It works
>> just as described on the Sciral webpage, complete with colorful  
>> graphs
>> that appear to the right of the task name in the agenda buffer.  The
>> graph even follows the same coloring algorithm as Sciral.
>>
>> To test out this new feature, apply the attached patches and read the
>> new manual section on "Tracking your habits".
>
> Thanks for this addition to org mode! I had written a tutorial on
> tracking habits with org-mode on Worg:
>
> http://orgmode.org/worg/org-tutorials/tracking-habits.php
>
> I'll have to update that now. :)
>
> A few constructive comments:
>
> 1. The syntax for defining habits seems fairly complex. One must add a
> repeating scheduled timestamp, a repeating deadline timestamp and a
> property. I was wondering if there could be anyway to automate  
> creating
> new habits---e.g., a dialog that asks for the appropriate time spans.
> (My own preference would be to use a new timestamp notation to  
> indicate
> habits. I'm not sure what this would look like. Perhaps something like
> this: SCHEDULED: <2009-10-17 Sat !+2+2> --- where the first number is
> the repeating span and the second is the "grace period". Of course, I
> have no idea whether this is possible.)
>
> 2. It is somewhat cumbersome to add two repeating timestamps to the  
> same
> entry. If one sets up the first repeating timestamp, then one cannot  
> add
> a second timestamp automatically. I.e., the following error message
> appears:
>
> "Cannot change deadline on task with repeater, please do that by hand"

I don't seem to be able to reproduce this.  Can you please explain
in more detail?

>
> 3. The faces for the graph are difficult to read against dark
> backgrounds. (See attached image.)
>
> 4. I currently use the tag :HABIT: to track habits. This allows for  
> easy
> filtering in the agenda. I'm wondering whether there might be an  
> option
> to designate habits with a user-defined tag rather than the STYLE
> property. The advantage would be much faster agenda searches for  
> habits.

I like the idea to shift this functionality to being a tag, also
because this is immediately visible.

- Carsten


>
> Thanks again!
>
> Matt
>
> <habits-orgmode.png>_______________________________________________
> Emacs-orgmode mailing list
> Remember: use `Reply All' to send replies to the list.
> Emacs-orgmode@gnu.org
> http://lists.gnu.org/mailman/listinfo/emacs-orgmode

- Carsten

Re: Added support for "habit tracking"

[Matthew Lundin]

Hi Carsten,

Carsten Dominik <carsten.dominik@gmail.com> writes:

>> 2. It is somewhat cumbersome to add two repeating timestamps to the
>> same
>> entry. If one sets up the first repeating timestamp, then one cannot
>> add
>> a second timestamp automatically. I.e., the following error message
>> appears:
>>
>> "Cannot change deadline on task with repeater, please do that by hand"
>
> I don't seem to be able to reproduce this.  Can you please explain
> in more detail?

Here's an example:

Let's say I have a task, that is scheduled to repeat every two days:

--8<---------------cut here---------------start------------->8---
* Shave
  SCHEDULED: <2009-10-20 Tue .+2d>
--8<---------------cut here---------------end--------------->8---

When I try to add a deadline interactively with C-c C-d, I receive an
error message: "Cannot change deadline on task with repeater, please do
that by hand".

- Matt

Re: Added support for "habit tracking"

[John Wiegley]

On Oct 20, 2009, at 10:02 AM, Matt Lundin wrote:

> 1. The syntax for defining habits seems fairly complex. One must add a
> repeating scheduled timestamp, a repeating deadline timestamp and a
> property. I was wondering if there could be anyway to automate  
> creating
> new habits---e.g., a dialog that asks for the appropriate time spans.
> (My own preference would be to use a new timestamp notation to  
> indicate
> habits. I'm not sure what this would look like. Perhaps something like
> this: SCHEDULED: <2009-10-17 Sat !+2+2> --- where the first number is
> the repeating span and the second is the "grace period". Of course, I
> have no idea whether this is possible.)

I agree with you here, and think that a more comprehensive SCHEDULED  
syntax might be just the fix.  I'll look into this.  Perhaps using a  
syntax like "!+2/2".

> 3. The faces for the graph are difficult to read against dark
> backgrounds. (See attached image.)

I'll fix this too.

> 4. I currently use the tag :HABIT: to track habits. This allows for  
> easy
> filtering in the agenda. I'm wondering whether there might be an  
> option
> to designate habits with a user-defined tag rather than the STYLE
> property. The advantage would be much faster agenda searches for  
> habits.

You can search for STYLE="habit".  I myself use contextual tags on the  
habits, because some of them aren't appropriate in other location, and  
I wouldn't want to see ":HABIT:" in the right-hand column for every one.

Also, note that you can press K now to filter habits in and out of the  
agenda view.  They are also by default restricted to only appearing in  
todays' agenda view.

John

Re: Re: Added support for "habit tracking"

[John Wiegley]

On Oct 20, 2009, at 11:29 AM, Carsten Dominik wrote:

>> 4. I currently use the tag :HABIT: to track habits. This allows for  
>> easy
>> filtering in the agenda. I'm wondering whether there might be an  
>> option
>> to designate habits with a user-defined tag rather than the STYLE
>> property. The advantage would be much faster agenda searches for  
>> habits.
>
> I like the idea to shift this functionality to being a tag, also
> because this is immediately visible.

I will look at the idea of letting the user choose whether it will be  
a tag, what the name of that tag should be, or if it should use the  
STYLE property.  I, for one, don't want categorical tags related to  
Org, but only contextual tags related to me.

John

Re: Added support for "habit tracking"

[Matthew Lundin]

John Wiegley <jwiegley@gmail.com> writes:

> On Oct 20, 2009, at 10:02 AM, Matt Lundin wrote:
>
>> 1. The syntax for defining habits seems fairly complex. One must add a
>> repeating scheduled timestamp, a repeating deadline timestamp and a
>> property. I was wondering if there could be anyway to automate
>> creating
>> new habits---e.g., a dialog that asks for the appropriate time spans.
>> (My own preference would be to use a new timestamp notation to
>> indicate
>> habits. I'm not sure what this would look like. Perhaps something like
>> this: SCHEDULED: <2009-10-17 Sat !+2+2> --- where the first number is
>> the repeating span and the second is the "grace period". Of course, I
>> have no idea whether this is possible.)
>
> I agree with you here, and think that a more comprehensive SCHEDULED
> syntax might be just the fix.  I'll look into this.  Perhaps using a
> syntax like "!+2/2".

Thanks. And, of course, if a new timestamp syntax proves too
complicated, I'm more than happy to use the current implementation. :)

>
>> 3. The faces for the graph are difficult to read against dark
>> backgrounds. (See attached image.)
>
> I'll fix this too.
>
>> 4. I currently use the tag :HABIT: to track habits. This allows for
>> easy
>> filtering in the agenda. I'm wondering whether there might be an
>> option
>> to designate habits with a user-defined tag rather than the STYLE
>> property. The advantage would be much faster agenda searches for
>> habits.
>
> You can search for STYLE="habit".  I myself use contextual tags on the
> habits, because some of them aren't appropriate in other location, and
> I wouldn't want to see ":HABIT:" in the right-hand column for every
> one.
>
> Also, note that you can press K now to filter habits in and out of the
> agenda view.  They are also by default restricted to only appearing in
> todays' agenda view.

I see. That works very nicely. Sorry I missed it the first time through
the documentation. This eliminates one of the main reason I had for
switching to a tag-based implementation.

Thanks again! I look forward to playing with this some more.

Matt

Re: Re: Added support for "habit tracking"

[Marcelo de Moraes Serpa]

This is very exciting, thanks a lot, I was looking on how to track my
"recurrent tasks", and you just came with a full-fledged solution plus
some new concepts I did not know. Thanks!

However, how do I apply these patches? I tried with patch, like this:

patch -p0 < name_of_the_patch_file.patch (in the org-mode root
directory, relatively to the lisp subdir) but it did not seem to work.

Marcelo.

On 10/20/09, John Wiegley <jwiegley@gmail.com> wrote:
> On Oct 20, 2009, at 11:29 AM, Carsten Dominik wrote:
>
>>> 4. I currently use the tag :HABIT: to track habits. This allows for
>>> easy
>>> filtering in the agenda. I'm wondering whether there might be an
>>> option
>>> to designate habits with a user-defined tag rather than the STYLE
>>> property. The advantage would be much faster agenda searches for
>>> habits.
>>
>> I like the idea to shift this functionality to being a tag, also
>> because this is immediately visible.
>
> I will look at the idea of letting the user choose whether it will be
> a tag, what the name of that tag should be, or if it should use the
> STYLE property.  I, for one, don't want categorical tags related to
> Org, but only contextual tags related to me.
>
> John
>
>
> _______________________________________________
> Emacs-orgmode mailing list
> Remember: use `Reply All' to send replies to the list.
> Emacs-orgmode@gnu.org
> http://lists.gnu.org/mailman/listinfo/emacs-orgmode
>

Re: Re: Added support for "habit tracking"

[John Wiegley]

On Oct 20, 2009, at 1:13 PM, Marcelo de Moraes Serpa wrote:

> However, how do I apply these patches? I tried with patch, like this:
>
> patch -p0 < name_of_the_patch_file.patch (in the org-mode root
> directory, relatively to the lisp subdir) but it did not seem to work.

Hi Marcelo,

The habits code is now in org-mode's 'master' Git branch.  You no  
longer need the patches, just pull the code from there:

     git clone git://repo.or.cz/org-mode.git

John

Re: Re: Added support for "habit tracking"

[Marcelo de Moraes Serpa]

[-- Attachment #1.1: Type: text/plain, Size: 755 bytes --]

Oh, cool, thanks for the info John.

Another stupid question: I did not find any references to habit-mode
anywhere in the online org manual. Am I looking in the wrong place?

Thanks,

Marcelo.

On Tue, Oct 20, 2009 at 12:19 PM, John Wiegley <jwiegley@gmail.com> wrote:

> On Oct 20, 2009, at 1:13 PM, Marcelo de Moraes Serpa wrote:
>
>  However, how do I apply these patches? I tried with patch, like this:
>>
>> patch -p0 < name_of_the_patch_file.patch (in the org-mode root
>> directory, relatively to the lisp subdir) but it did not seem to work.
>>
>
> Hi Marcelo,
>
> The habits code is now in org-mode's 'master' Git branch.  You no longer
> need the patches, just pull the code from there:
>
>    git clone git://repo.or.cz/org-mode.git
>
> John
>

[-- Attachment #1.2: Type: text/html, Size: 1344 bytes --]

[-- Attachment #2: Type: text/plain, Size: 204 bytes --]

_______________________________________________
Emacs-orgmode mailing list
Remember: use `Reply All' to send replies to the list.
Emacs-orgmode@gnu.org
http://lists.gnu.org/mailman/listinfo/emacs-orgmode

Re: Re: Added support for "habit tracking"

[Samuel Wales]

On Tue, Oct 20, 2009 at 09:48, John Wiegley <jwiegley@gmail.com> wrote:
> I agree with you here, and think that a more comprehensive SCHEDULED syntax
> might be just the fix.  I'll look into this.  Perhaps using a syntax like
> "!+2/2".

I wonder if we can switch to something a little more like extensible
syntax.  This would use keywords instead of symbols, for ease of
remembering, looking up, etc.

Re: Re: Added support for "habit tracking"

[Marcelo de Moraes Serpa]

[-- Attachment #1.1: Type: text/plain, Size: 844 bytes --]

Hmm, I had to put (require 'org-habit) in my .emacs, was that implicitly
required or is org supposed to load it automatically?

On Tue, Oct 20, 2009 at 1:30 PM, Samuel Wales <samologist@gmail.com> wrote:

> On Tue, Oct 20, 2009 at 09:48, John Wiegley <jwiegley@gmail.com> wrote:
> > I agree with you here, and think that a more comprehensive SCHEDULED
> syntax
> > might be just the fix.  I'll look into this.  Perhaps using a syntax like
> > "!+2/2".
>
> I wonder if we can switch to something a little more like extensible
> syntax.  This would use keywords instead of symbols, for ease of
> remembering, looking up, etc.
>
>
> _______________________________________________
> Emacs-orgmode mailing list
> Remember: use `Reply All' to send replies to the list.
> Emacs-orgmode@gnu.org
> http://lists.gnu.org/mailman/listinfo/emacs-orgmode
>

[-- Attachment #1.2: Type: text/html, Size: 1418 bytes --]

[-- Attachment #2: Type: text/plain, Size: 204 bytes --]

_______________________________________________
Emacs-orgmode mailing list
Remember: use `Reply All' to send replies to the list.
Emacs-orgmode@gnu.org
http://lists.gnu.org/mailman/listinfo/emacs-orgmode

Re: Re: Added support for "habit tracking"

[John Wiegley]

On Oct 20, 2009, at 2:38 PM, Marcelo de Moraes Serpa wrote:

> Hmm, I had to put (require 'org-habit) in my .emacs, was that  
> implicitly required or is org supposed to load it automatically?

The habit support is optional, and should not incur any runtime or  
load-time costs for those who don't use it.  Therefore, you have to  
enable it by customizing `org-modules', or by loading it into  
your .emacs file.

John

Re: Re: Added support for "habit tracking"

[John Wiegley]

On Oct 20, 2009, at 2:30 PM, Samuel Wales wrote:

> I wonder if we can switch to something a little more like extensible
> syntax.  This would use keywords instead of symbols, for ease of
> remembering, looking up, etc.

I've implemented ".+1d/3d" type syntax.  What do you propose?

John

Re: Added support for "habit tracking"

[Sven Bretfeld]

Hi John and all others

John Wiegley <jwiegley@gmail.com> writes:

> To test out this new feature, apply the attached patches and read the
> new manual section on "Tracking your habits".

Just tested this feature. No graph to be seen! What's wrong?

I cloned and installed the git-version (M-x org-version gives: Org-mode
version 6.31trans (release_6.31.133.g6138.dirty). Then I just copied
your example from the manual with all DONE statements, dates and
properties into my main org-file.

The agenda-buffer displays the "NEXT Shave" lines just as normal, no
graph. (Using NEXT instead of TODO can't be the problem, can it?) "K" is
not working at all (buffer is read-only), "k" asks for an agenda action.
Something wrong with the implementation? I use Emacs-Snapshot on Ubuntu
Jaunty (Emacs version 23.0.91.1). Or did I understand anything wrong?
Anything else to configure?

Anyway, thanks a lot for the new feature.

Sven

Re: Added support for "habit tracking"

[Sven Bretfeld]

"Sven Bretfeld" <sven.bretfeld@gmx.ch> writes:

> Hi John and all others
>
> John Wiegley <jwiegley@gmail.com> writes:
>
>> To test out this new feature, apply the attached patches and read the
>> new manual section on "Tracking your habits".
>
> Just tested this feature. No graph to be seen! What's wrong?

Ok. (require 'org-habit) did it. Thanks, Marcelo. This should be
mentioned in the manual.

Greetings

Sven

Re: Added support for "habit tracking"

[Carsten Dominik]

On Oct 20, 2009, at 8:56 PM, Sven Bretfeld wrote:

> "Sven Bretfeld" <sven.bretfeld@gmx.ch> writes:
>
>> Hi John and all others
>>
>> John Wiegley <jwiegley@gmail.com> writes:
>>
>>> To test out this new feature, apply the attached patches and read  
>>> the
>>> new manual section on "Tracking your habits".
>>
>> Just tested this feature. No graph to be seen! What's wrong?
>
> Ok. (require 'org-habit) did it. Thanks, Marcelo. This should be
> mentioned in the manual.

What you really should do is set the corresponding tick in `org- 
modules'.
John did not turn this on by default because I was worried what
on the speed of agenda creation...

- Carsten

Re: Added support for "habit tracking"

[John Wiegley]

Ok, the following changes today have been submitted for inclusion:

  - "Habit" appears in mode-line when Habits are being displayed

  - Habits no longer use a DEADLINE, but .+1d/3d, to indicate a range.
    Use .+1d if the min and max are the same.

  - org-habit uses faces for all its colors, and appropriate colors have
    been chosen for dark backgrounds.

  - The consistency graph starts from the scheduled date, if that date  
precedes
    today and the first completed date.

  - Habits are now sorted according to a habit-specific priority  
scheme, based
    on Sciral's "priority" sorting method.  This means that habits  
which demand
    more attention will shift to the top.  Use 'P' in the agenda to  
see what the
    relative priorities are.

John

Re: Added support for "habit tracking"

[Marcelo de Moraes Serpa]

[-- Attachment #1.1: Type: text/plain, Size: 1524 bytes --]

Hey, I learned a new thing, the org-modules thing...

Anyway, I don't have much time to play with it now, but I can say this is a
feature I've been looking/trying to implement with current org
functionalities for a long time, I will get at home tonight, brainstorm
about my recurring tasks/habits and put this beauty to work for me :D

@John: Now, onto implementing Flying Logic for org!

Thanks a lot for this amazing contribution,

Marcelo.

On Tue, Oct 20, 2009 at 2:36 PM, John Wiegley <jwiegley@gmail.com> wrote:

> Ok, the following changes today have been submitted for inclusion:
>
>  - "Habit" appears in mode-line when Habits are being displayed
>
>  - Habits no longer use a DEADLINE, but .+1d/3d, to indicate a range.
>   Use .+1d if the min and max are the same.
>
>  - org-habit uses faces for all its colors, and appropriate colors have
>   been chosen for dark backgrounds.
>
>  - The consistency graph starts from the scheduled date, if that date
> precedes
>   today and the first completed date.
>
>  - Habits are now sorted according to a habit-specific priority scheme,
> based
>   on Sciral's "priority" sorting method.  This means that habits which
> demand
>   more attention will shift to the top.  Use 'P' in the agenda to see what
> the
>   relative priorities are.
>
> John
>
>
>
> _______________________________________________
> Emacs-orgmode mailing list
> Remember: use `Reply All' to send replies to the list.
> Emacs-orgmode@gnu.org
> http://lists.gnu.org/mailman/listinfo/emacs-orgmode
>

[-- Attachment #1.2: Type: text/html, Size: 2147 bytes --]

[-- Attachment #2: Type: text/plain, Size: 204 bytes --]

_______________________________________________
Emacs-orgmode mailing list
Remember: use `Reply All' to send replies to the list.
Emacs-orgmode@gnu.org
http://lists.gnu.org/mailman/listinfo/emacs-orgmode

Re: Added support for "habit tracking"

[Carsten Dominik]

Applied, thanks.

- Carsten

On Oct 20, 2009, at 9:36 PM, John Wiegley wrote:

> Ok, the following changes today have been submitted for inclusion:
>
> - "Habit" appears in mode-line when Habits are being displayed
>
> - Habits no longer use a DEADLINE, but .+1d/3d, to indicate a range.
>   Use .+1d if the min and max are the same.
>
> - org-habit uses faces for all its colors, and appropriate colors have
>   been chosen for dark backgrounds.
>
> - The consistency graph starts from the scheduled date, if that date  
> precedes
>   today and the first completed date.
>
> - Habits are now sorted according to a habit-specific priority  
> scheme, based
>   on Sciral's "priority" sorting method.  This means that habits  
> which demand
>   more attention will shift to the top.  Use 'P' in the agenda to  
> see what the
>   relative priorities are.
>
> John
>
>
> _______________________________________________
> Emacs-orgmode mailing list
> Remember: use `Reply All' to send replies to the list.
> Emacs-orgmode@gnu.org
> http://lists.gnu.org/mailman/listinfo/emacs-orgmode

- Carsten

Re: Added support for "habit tracking"

[Matt Lundin]

[-- Attachment #1: Type: text/plain, Size: 2252 bytes --]

Hi John, 

John Wiegley <jwiegley@gmail.com> writes:

> Ok, the following changes today have been submitted for inclusion:
>
>  - "Habit" appears in mode-line when Habits are being displayed
>
>  - Habits no longer use a DEADLINE, but .+1d/3d, to indicate a range.
>    Use .+1d if the min and max are the same.

Thanks again for the excellent addition to org-mode. I have a couple of
questions about the graph output.

Let's say I have a habit that I would like to do every day, e.g.,

,----
| * TODO Shave
|   SCHEDULED: <2009-10-21 Wed .+1d>
|   :LOGBOOK:
|   - State "DONE"       from "TODO"       [2009-10-19 Mon 14:06]
|   - State "DONE"       from "TODO"       [2009-10-18 Sun 14:06]
|   - State "DONE"       from "TODO"       [2009-10-17 Sat 14:06]
|   - State "DONE"       from "TODO"       [2009-10-15 Thu 14:06]
|   - State "DONE"       from "TODO"       [2009-10-11 Sun 14:06]
|   :END:
|   :PROPERTIES:
|   :STYLE:    habit
|   :END:
`----

As you can see from the above example, I missed few days (10-12, 10-13,
etc.).

In the consistency graph, the first day the task was skipped (10-12)
appears in green (org-habit-ready-face) on the graph. The second day
(10-13), when the task was overdue, appears in yellow
(org-habit-alert-face). If I am reading the manual correctly, I would
expect this second day to be red, since the task is overdue on the day.
(See the attachment "graph-1.png").

I believe I've found another issue with the graphs. If a task is
completed twice on the same day, it prevents all subsequent days from
appearing on the consistency graph.

Here's the example:

,----
| * TODO Shave
|   SCHEDULED: <2009-10-21 Wed .+1d>
|   :LOGBOOK:
|   - State "DONE"       from "TODO"       [2009-10-19 Mon 14:06]
|   - State "DONE"       from "TODO"       [2009-10-17 Sat 14:06]
|   - State "DONE"       from "TODO"       [2009-10-15 Thu 14:06]
|   - State "DONE"       from "TODO"       [2009-10-11 Sun 14:06]
|   - State "DONE"       from "TODO"       [2009-10-10 Sat 14:06]
|   - State "DONE"       from "TODO"       [2009-10-10 Sat 12:00]
|   :END:
|   :PROPERTIES:
|   :STYLE:    habit
|   :LAST_REPEAT: [2009-10-21 Wed 14:06]
|   :END:
`----

See the second attached screenshot (graph-2.png) for the output.

Thanks,
Matt


[-- Attachment #2: graph-1.png --]
[-- Type: image/png, Size: 15256 bytes --]

[-- Attachment #3: graph-2.png --]
[-- Type: image/png, Size: 14678 bytes --]

[-- Attachment #4: Type: text/plain, Size: 204 bytes --]

_______________________________________________
Emacs-orgmode mailing list
Remember: use `Reply All' to send replies to the list.
Emacs-orgmode@gnu.org
http://lists.gnu.org/mailman/listinfo/emacs-orgmode

Re: Added support for "habit tracking"

[John Wiegley]

On Oct 21, 2009, at 2:36 PM, Matt Lundin wrote:

> In the consistency graph, the first day the task was skipped (10-12)
> appears in green (org-habit-ready-face) on the graph. The second day
> (10-13), when the task was overdue, appears in yellow
> (org-habit-alert-face). If I am reading the manual correctly, I would
> expect this second day to be red, since the task is overdue on the  
> day.
> (See the attachment "graph-1.png").
>
> I believe I've found another issue with the graphs. If a task is
> completed twice on the same day, it prevents all subsequent days from
> appearing on the consistency graph.

Thanks for the bug reports!  I'll get these fixed for you.

John

Re: Re: Added support for "habit tracking"

[Marcelo de Moraes Serpa]

[-- Attachment #1.1: Type: text/plain, Size: 1915 bytes --]

Hi John,

I have a doubt regarding a specific habit definition I'd like to create - A
GTD Weekly review. I want this habit to "happen" every friday, weekly. But
if this friday passes, then, I want org-habit to consider it overdue. I've
tried the following def:

** TODO GTD Weekly Review
   SCHEDULED: <2009-10-23 Fri .+1w>
   :PROPERTIES:
   :STYLE: habit
   :END:

The graph says (considering today is friday which indeed, is):

... | b | b | b | !g | g | g | g | g | g | g | y | r |

(b = blue, g = green, y = yellow, r = red, ! = current day)

So, org-habit assumes I could do the task any day of the week, starting
every friday? Or am I interpreting something wrongly?

My expected graph would be, considering today is a friday:

| !g | y | y | ...

How could I define it so I can have a habit that happens weekly but that has
a hard deadline of that very same weekday it has been specified to?

Thanks,

Marcelo.

On Wed, Oct 21, 2009 at 5:40 PM, John Wiegley <jwiegley@gmail.com> wrote:

> On Oct 21, 2009, at 2:36 PM, Matt Lundin wrote:
>
>  In the consistency graph, the first day the task was skipped (10-12)
>> appears in green (org-habit-ready-face) on the graph. The second day
>> (10-13), when the task was overdue, appears in yellow
>> (org-habit-alert-face). If I am reading the manual correctly, I would
>> expect this second day to be red, since the task is overdue on the day.
>> (See the attachment "graph-1.png").
>>
>> I believe I've found another issue with the graphs. If a task is
>> completed twice on the same day, it prevents all subsequent days from
>> appearing on the consistency graph.
>>
>
> Thanks for the bug reports!  I'll get these fixed for you.
>
>
> John
>
>
> _______________________________________________
> Emacs-orgmode mailing list
> Remember: use `Reply All' to send replies to the list.
> Emacs-orgmode@gnu.org
> http://lists.gnu.org/mailman/listinfo/emacs-orgmode
>

[-- Attachment #1.2: Type: text/html, Size: 2716 bytes --]

[-- Attachment #2: Type: text/plain, Size: 204 bytes --]

_______________________________________________
Emacs-orgmode mailing list
Remember: use `Reply All' to send replies to the list.
Emacs-orgmode@gnu.org
http://lists.gnu.org/mailman/listinfo/emacs-orgmode

Re: Re: Added support for "habit tracking"

[John Wiegley]

On Oct 23, 2009, at 2:10 AM, Marcelo de Moraes Serpa wrote:

> How could I define it so I can have a habit that happens weekly but  
> that has a hard deadline of that very same weekday it has been  
> specified to?

In this case you would use an ordinary task with a ++1w repeater.  Are  
you wanting to use habits just for the graph?

Habits are different from tasks.  It is "suggested" that you do them  
within a range of time, but it's not completion which is important,  
rather consistency over the long-run.  Hence the graph to indicate  
your overall progress on the goal of being consistent.

A weekly review, on the other hand, is something that you really  
should do every week, and if you miss it doesn't matter how well  
you've been doing in the past, a single missed week could throw you  
off considerably.

John

Re: Re: Added support for "habit tracking"

[Marcelo de Moraes Serpa]

[-- Attachment #1.1: Type: text/plain, Size: 1660 bytes --]

>
> Habits are different from tasks.  It is "suggested" that you do them within
> a range of time, but it's not completion which is important, rather
> consistency over the long-run.  Hence the graph to indicate your overall
> progress on the goal of being consistent.
>

But isn't consistency in the long-run the fact that you have actually
*completed* them?

So, the thing here is the concept of habit. So, from what I could
understand, a habit has to happen during a period of time and have a
deadline.

In this case, IMO, a weekly review is a habit, even though it does not
happen daily, it still has consistent period to be respected (1 day, every
seven days), and a deadline (the very same day). Or habits need to be daily?

Thanks!

On Fri, Oct 23, 2009 at 5:34 AM, John Wiegley <jwiegley@gmail.com> wrote:

> On Oct 23, 2009, at 2:10 AM, Marcelo de Moraes Serpa wrote:
>
>  How could I define it so I can have a habit that happens weekly but that
>> has a hard deadline of that very same weekday it has been specified to?
>>
>
> In this case you would use an ordinary task with a ++1w repeater.  Are you
> wanting to use habits just for the graph?
>
> Habits are different from tasks.  It is "suggested" that you do them within
> a range of time, but it's not completion which is important, rather
> consistency over the long-run.  Hence the graph to indicate your overall
> progress on the goal of being consistent.
>
> A weekly review, on the other hand, is something that you really should do
> every week, and if you miss it doesn't matter how well you've been doing in
> the past, a single missed week could throw you off considerably.
>
> John
>

[-- Attachment #1.2: Type: text/html, Size: 2350 bytes --]

[-- Attachment #2: Type: text/plain, Size: 204 bytes --]

_______________________________________________
Emacs-orgmode mailing list
Remember: use `Reply All' to send replies to the list.
Emacs-orgmode@gnu.org
http://lists.gnu.org/mailman/listinfo/emacs-orgmode

Re: Re: Added support for "habit tracking"

[John Wiegley]

On Oct 23, 2009, at 11:24 AM, Marcelo de Moraes Serpa wrote:

> But isn't consistency in the long-run the fact that you have  
> actually *completed* them?

Yes and no.  I don't need to always complete them, and yet I could  
still be consistent.  It's optimal to be perfectly consistent, but  
that's no what's expected.

Missing a deadline is something else entirely, as one imagines there  
are consequences.  Missing a habit is, well, just harder to pin down.

> In this case, IMO, a weekly review is a habit, even though it does  
> not happen daily, it still has consistent period to be respected (1  
> day, every seven days), and a deadline (the very same day). Or  
> habits need to be daily?

I guess it all comes down to whether you just want the graph or not.   
A weekly review is really something you need to do every week, so it's  
just a repeating task.  I have too have regular repeating tasks for  
things like downloading bank statements, paying the rent, visiting the  
dentist, etc.  These are tasks which are _each important in  
themselves_.  A habit, on the other hand, is never important in  
itself.  It doesn't matter so much if I miss washing the dishes  
today.  It's the _habit overall which is important_.  As long as I  
wash them more often than not, I'm doing better than if I'd never used  
Org at all.

The only difference between regular repeating tasks and habits is this:

  1. Habits appear at the bottom of the agenda (by default)
  2. Habits can be removed by hitting K
  3. Habits have a little graph, since you need to see consistency  
over a
     period of time.

Another difference between habits and tasks is this: If I get to the  
end of my day and there are tasks yet undone, it means I need to  
schedule them for another day.  But if there are habits undone, *I  
never reschedule them*.  Once I reach a point during the day when I  
know I no longer have time or opportunity to work on my habits, I just  
hit K and exclude them from the view.  What it means is that I'll try  
again to do them tomorrow.

But since tasks are, in a way, much more self-important, they need to  
be allocated to a certain day, or given a specific deadline -- whether  
or not that deadline repeats itself.

John

Re: Added support for "habit tracking"

[Matthew Lundin]

John Wiegley <jwiegley@gmail.com> writes:

> The only difference between regular repeating tasks and habits is this:
>
>  1. Habits appear at the bottom of the agenda (by default)

Out of curiosity, might I ask what org-agenda-sorting-strategy setting
produces the default behavior? My agenda shows habits intermingled with
SCHEDULED todos. Here's my org-agenda-sorting-strategy setting.

--8<---------------cut here---------------start------------->8---
((agenda time-up priority-down effort-down)
 (todo todo-state-up priority-down)
 (tags priority-down))
--8<---------------cut here---------------end--------------->8---
 
>  2. Habits can be removed by hitting K
>  3. Habits have a little graph, since you need to see consistency over
> a
>     period of time.
>
> Another difference between habits and tasks is this: If I get to the
> end of my day and there are tasks yet undone, it means I need to
> schedule them for another day.  But if there are habits undone, *I
> never reschedule them*.  Once I reach a point during the day when I
> know I no longer have time or opportunity to work on my habits, I just
> hit K and exclude them from the view.  What it means is that I'll try
> again to do them tomorrow.

I very much appreciate this feature!

- Matt

Re: Added support for "habit tracking"

[Matthew Lundin]

Matthew Lundin <mdl@imapmail.org> writes:

> John Wiegley <jwiegley@gmail.com> writes:
>
>> The only difference between regular repeating tasks and habits is this:
>>
>>  1. Habits appear at the bottom of the agenda (by default)
>
> Out of curiosity, might I ask what org-agenda-sorting-strategy setting
> produces the default behavior? My agenda shows habits intermingled with
> SCHEDULED todos. Here's my org-agenda-sorting-strategy setting.
>
> ((agenda time-up priority-down effort-down)
>  (todo todo-state-up priority-down)
>  (tags priority-down))

Sorry for the false alarm. I found the new habit-up and habit-down
options by checking the docstring of org-agenda-sorting-strategy.

- Matt

Re: Added support for "habit tracking"

[Paul Mead]

John Wiegley <jwiegley@gmail.com> writes:

>
> To test out this new feature, apply the attached patches and read the new manual
> section on "Tracking your habits".
>

John

I've been searching on the word "habits" in the manual and I can't find
it anywhere. Can you give me a clue about where it might be hiding? I'm
looking at the 6.31a manual at http://orgmode.org/manual/index.html

Thanks
Paul

Re: Re: Added support for "habit tracking"

[Carsten Dominik]

On Oct 25, 2009, at 1:26 PM, Paul Mead wrote:

> John Wiegley <jwiegley@gmail.com> writes:
>
>>
>> To test out this new feature, apply the attached patches and read  
>> the new manual
>> section on "Tracking your habits".
>>
>
> John
>
> I've been searching on the word "habits" in the manual and I can't  
> find
> it anywhere. Can you give me a clue about where it might be hiding?  
> I'm
> looking at the 6.31a manual at http://orgmode.org/manual/index.html

Hi Paul,

you need to use the manual in the git repo, until the next official  
release.  The manual on the website is only updated when a new release  
gets pushed there.

6.32 is due in a day or two.

- Carsten

>
> Thanks
> Paul
>
>
> _______________________________________________
> Emacs-orgmode mailing list
> Remember: use `Reply All' to send replies to the list.
> Emacs-orgmode@gnu.org
> http://lists.gnu.org/mailman/listinfo/emacs-orgmode

- Carsten

Re: Added support for "habit tracking"

[Paul Mead]

Sorry for the noise, I've just found the reference in my local copy of
the manual, which is up to date!

Paul

Re: Added support for "habit tracking"

[Paul Mead]

Thanks Carsten, I figured it out straight after posting - I must learn
to check one last time before posting!

Paul