Using Org Mode as a Calendar

Main article:

Orgmode has a useful time based agenda view.

Plain timestamps

For a simple calendar appointment/meeting you can use the plain vanilla Orgmode timestamp:

* Dentist appointment <2010-02-10 Wed 18:00>

This will put "Dentist appointment" in the corresponding agenda view. You can omit the time and the appointment won't show up on a time grid line.

Note that this does not provide anything in the way of reminders. If you want to see the appointment and it's not the right day, you have to expand your agenda view to include the appointment day, such as a week in advance. This is keeping in line with normal calendaring programs, which often offer a weekly view of your appointments.

Putting a TODO state in the item doesn't affect how it's displayed in the agenda, except that the TODO state will appear in the agenda. In particular, setting the state to DONE does not remove it from the agenda (NOTE: take a look at org-agenda-skip-scheduled-if-done).

You can also put a time range in the timestamp:

* Dentist appointment <2010-02-10 Wed 18:00-19:00>

This will make it take up the desired room in the timed grid lines, at least with some tweaking (more to come).

Deadline and Scheduling

The basic appointment functionality does not offer anything in the way of daily reminders of upcoming events. You can add a DEADLINE to the timestamp to get something approaching this:

* TODO Important assignment due 
DEADLINE: <2010-02-10 Wed 18:00>

Like a normal timestamp, the text will show up in the agenda on the date specified. But in addition, the agenda for today will show a reminder that the deadline is looming. You can specify how far in advance you want this by putting a warning period:

* TODO Important assignment due 
DEADLINE: <2010-02-10 Wed 18:00 -7d>

Note that DEADLINE entries really only make much sense for TODO items. This is because the warnings continue after the deadline has passed, until the item is marked DONE. Even if there's no TODO state associated with the item, the warnings will continue to show up unless you mark the item as DONE.

You can also add a SCHEDULED modifier to a timestamp:

* TODO Start important assignment
SCHEDULED: <2010-02-10 Wed 18:00>

The item shows up on the date specified. It also shows up every day after that, until the item is marked as DONE.


You can add a repeater to a timestamp:

* Church <2010-02-07 Sun 09:00 +1w>

You can put d (days), w (weeks), m (months, y (years).

In a regular, non-DEADLINE, non-SCHEDULED situation, a repeater just makes sure that the item shows up every week, or every day, etc. It behaves as you would expect.

Things are a little different for DEADLINE and SCHEDULED items. Say you have this in your org file:

* TODO Important weekly assignment due 
DEADLINE: <2010-02-10 Wed 18:00 +1w -2d>

In this case, you will get a warning two days in advance of your due date. Note that the warning period must come after the repeater interval.

But now what happens when you mark the entry as DONE? This poses a problem, because then the entry, set to DONE, would not appear in your agenda the following week. Orgmode solves this problem by doing the following: when you set the state to DONE, it will increment the date by whatever the repeater interval is, and then reset the state to TODO so it will continue to be processed for agenda purposes.

With +1w, the date shift will always be exactly one week from the date in the timestamp (+1m will be one month, etc.). If you miss 3 deadlines, then you will need to shift the date 3 times to catch up. This may or may not be the right thing to do. If there are three distinct actionable item that you have to handle associated with each deadline, then this may make sense. But there are cases where it doesn't:

Use Cases

Simple appointments

If you just want something to appear on your agenda, with no reminder required, for use in your weekly review or a day-at-a-glance view, just use a plain vanilla timestamp:

* Dentist appointment <2010-02-10 Wed 18:00>

No TODO state required.



There are a few of ways to do this:

Natural TODO deadlines

A natural deadline is a TODO item with, well, a natural deadline. It's a real TODO item, and you want it to appear on your TODO list, but you also want early warnings on your agenda. This is exactly what orgmode DEADLINE feature is for.

* TODO Important assignment due 
DEADLINE: <2010-02-10 Wed 18:00>

Holiday/Anniversary Reminders

This is a normal appointment or special date, without a timestamp, but we want an early reminder of its approach in our agenda so we can prepare. Use cases include birthdays, holidays, anniversaries, or simply a one time event you need to prepare for.

Surprisingly, I couldn't find a clean way to do this in orgmode. It's similar to the DEADLINE feature, but the problem is that the DEADLINE feature really requires a TODO state for it to work. This means that the appointment shows up on your TODO list, which may not be what you want. This can be mitigated by using a special TODO state - let's say CAL - and a special query to produce your TODO list which excludes CAL entries. This works, but you still have to manually set the state to DONE to stop it from appearing in your agenda once the deadline passes.

The DEADLINE feature is, from a philosophical standpoint, a bit weird when used with repeaters and, say, birthdays. The date of the DEADLINE changes whenever you change the state. This is counterintuitive for birthdays (or holidays, etc.) where it would be nice to just record the month and day, and possibly the year (NOT the year when the next birthday is coming).

One solution I've found for this problem is to integrate the diary with orgmode and use the diary-remind sexp, like this:

%%(diary-remind '(diary-date 12 10 t) -14) My birthday.

It's not ideal, but this seems to have the desired effect of generating agenda reminders of the upcoming date before the date arrives, without a TODO item whose state I have to manage myself.

Another idea is to use remind and integrate it somehow with orgmode.

Dated Appointment Reminders with Timestamps

Unfortunately, I don't know how to do this in emacs...diary doesn't deal with times. Orgmode doesn't do reminders very well. Maybe use remind?

Aside: Entering timestamps

Entering timestamps is complicated.

Press C-c . to insert a plain timestamp with date only.

Press C-c ! to insert an inactive timestamp with date only.

C-u before each of those to also insert a time along with the date.

You'll be prompted for a date. You can enter more or less anything and Orgmode will do its best to interpret this as a date. You can also select a date via the following keys (this is cribbed from the org manual):

> / <          Scroll calendar forward/backward by one month.
mouse-1        Select date by clicking on it.
S-<right>/<left>     One day forward/backward.
S-<down>/<up>     One week forward/backward.
M-S-<right>/<left>   One month forward/backward.
<RET>           Choose date in calendar.

You can enter a free form time and use these key to choose a date and you're set.

CategoryEmacs CategoryOrgmode

OrgModeTimestamps (last edited 2010-11-08 14:04:21 by DesmondRivet)