[Orgmode] Re: cannot enable org-habit

[Joseph Buchignani]

Thanks Julien. Bastien, here is my update to this section of the org-mode manual. I'm not sure how one goes about submitting an update, hope this will do.


Thanks,
JB

5.3.3 Tracking your habits

Org has the ability to track the consistency of a special category of TODOs, called “habits”. In order for habits to work, you must meet the following requirements:

1. You have enabled the habits module by customizing the variable org-modules. Earlier versions of Org-Mode require two lines added to your .emacs: "(add-to-list 'org-modules 'org-habit)" and "(require 'org-habit)". Org-mode version 7.01h and later only require the second line, "(require 'org-habit)".
2. The habit is a TODO, with a TODO keyword representing an open state.
3. The property STYLE is set to the value habit.
4. The TODO has a scheduled date, with a .+ style repeat interval.
5. The TODO may also have minimum and maximum ranges specified by using the syntax ‘.+2d/3d’, which says that you want to do the task at least every three days, but at most every two days.
6. You must also have state logging for the DONE state enabled, in order for historical data to be represented in the consistency graph. If it's not enabled it's not an error, but the consistency graphs will be largely meaningless.

How can you tell that a habit is configured correctly? There are two tests. First, make sure that org-habit is activated. Within org-mode, type "C-a a a" to bring up your agenda. Then press uppercase "K". You should see a message in the minibuffer saying "Habits disabled/enabled". If you don't see this message, it means org-habit is not loaded. The problem may be that you haven't restarted, that your .emacs file isn't configured correctly, or that you have the wrong version of org-mode or a bad installation.

Once you've confirmed that org-habit is loaded, you can test whether your habit entry is working. Create a habit that looks like the entry below, and schedule it for the current day. Open your agenda with C-a a a. The habit should display on your agenda as a TODO item with a colored bar after it. The colored bar is the frequency graph. If you see this, then you've configured the habit entry correctly.

To give you an idea of what the above rules look like in action, here's an actual habit with some history, and how it would look on your agenda:

     ** TODO Shave
        SCHEDULED: <2009-10-17 Sat .+2d/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:

What this habit says is: I want to shave at most every 2 days (given by the SCHEDULED date and repeat interval) and at least every 4 days. If today is the 15th, then the habit first appears 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.

What's really useful about habits is that they are displayed along with a consistency graph, to show how consistent you've been at getting that task done in the past. This graph shows every day that the task was done over the past three weeks, with colors for each day. The colors used are:

Blue

If the task wasn't to be done yet on that day.

Green

If the task could have been done on that day.

Yellow

If the task was going to be overdue the next day.

Red

If the task was overdue on that day.

In addition to coloring each day, the day is also marked with an asterisk if the task was actually done that day, and an exclamation mark to show where the current day falls in the graph.

There are several configuration variables that can be used to change the way habits are displayed in the agenda.

org-habit-graph-column

The buffer column at which the consistency graph should be drawn. This will overwrite any text in that column, so it's a good idea to keep your habits' titles brief and to the point.

org-habit-preceding-days

The amount of history, in days before today, to appear in consistency graphs.

org-habit-following-days

The number of days after today that will appear in consistency graphs.

org-habit-show-habits-only-for-today

If non-nil, only show habits in today's agenda view. This is set to true by default.

Lastly, pressing K in the agenda buffer will cause habits to temporarily be disabled and they won't appear at all. Press K again to bring them back. They are also subject to tag filtering, if you have habits which should only be done in certain contexts, for example.