Re: cannot enable org-habit

From: Joseph Buchignani <joseph.buchignani@gmail.com>
To: Julien Fantin <julien.fantin@gmail.com>
Cc: "Emacs-orgmode@gnu.org" <Emacs-orgmode@gnu.org>,
	Noorul Islam <noorul@noorul.com>,
	Bastien <bastien.guerry@wikimedia.fr>
Subject: Re: cannot enable org-habit
Date: Sat, 4 Sep 2010 01:09:46 +0800	[thread overview]
Message-ID: <AANLkTin6H+WNd_yAR6a7MZuVW4QRz=gc8Jvcz76T5q6V@mail.gmail.com> (raw)
In-Reply-To: <AANLkTimhDVJESWpdN8pvTzDVxt+9xA-y_3nfxK2s6FqW@mail.gmail.com>

[-- Attachment #1.1.1: Type: text/plain, Size: 5242 bytes --]

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:

[image: org-habit-agenda.png]

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:
BlueIf the task wasn't to be done yet on that day.
GreenIf the task could have been done on that day.
YellowIf the task was going to be overdue the next day.
RedIf 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-columnThe 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-daysThe amount of history, in days before today, to
appear in consistency graphs.
org-habit-following-daysThe number of days after today that will appear in
consistency graphs.
org-habit-show-habits-only-for-todayIf 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.

[-- Attachment #1.1.2: Type: text/html, Size: 6450 bytes --]

[-- Attachment #1.2: org-habit-agenda.png --]
[-- Type: image/png, Size: 33796 bytes --]

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

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