An excellent tutorial on Date/Agenda management with emacs org-mode!

Using dates and times in Emacs org-mode

A tutorial on working with dates and times in org-mode
Table of Contents

1 Org-mode and personal productivity
2 Brief review of org-mode
2.1 User configurable tags
2.2 To do flags
2.3 Dates
3 Exploring Dates
3.1 Simple date format
3.2 Date and time format
3.3 Date Range
4 Agenda View
5 Timeline
6 Repeating events
7 Deadlines and Scheduled Dates
7.1 Deadline Dates
7.2 Repeating Deadlines
7.3 Sparse Tree of Deadlines
7.4 Scheduled Date
8 Editing Dates
8.1 Date Selector Tool
9 Examples
10 Command Summary
1 Org-mode and personal productivity

org-mode is an Emacs package for creating outlines with enhancements to make it a powerful tool for personal productivity, planning and simple project management. org-mode is an appointment book, calendar and to-do list manager.

This tutorial focuses on the date and time stamp functionality and how this works with the agenda view.

2 Brief review of org-mode

The basics of an org-mode file are lines beginning with one or more asterisks to indicate an outline entry (or heading), with the number of asterisks indicating the outline level. Text associated with an outline entry follows the line beginning with asterisks until the next outline entry.

The simplest outline looks like this:

* Things to do at work
** Weekly management meetings
*** Tuesday department meeting (10-11am)
*** Friday afternoon team meeting (3-4pm)
* Phone calls to make
** Susan - regarding contract
org-mode makes good use of color and font decorations to make this very simple text readable.



org-mode enhances the outline entries with the following features of user configurable tags, to-do flags and dates.

2.1 User configurable tags

These are useful for defining places where the work can be done, contexts, type of work, people involved , or special resources. For example: HOME, OFFICE, PHONE (identifying items requiring a phone call), BOSS (tagging items to discuss with your manager) and SUSAN (tagging items delegated to SUSAN).

Tags appear at the end of an entry with surrounding colons. Tags are assigned using the C-c C-c command where a window is displayed showing the tags configured in the line beginning #+TAGS. Each tag can be followed with a short-cut for fast selection.



Tags are used to generate lists of items containing one or more specified tags. For example, a list of phone calls that need to be made can be generated by searching for the PHONE tag. These lists by context are known as Next Actions in David Allen's Getting Things Done methodology.

2.2 To do flags

An outline entry can be marked as TODO using the C-c C-t command. This tag appears at the beginning of an entry in a different colour.



To-do flags are used to generate a "to-do list" sparse tree using the C-c C-v command, or in a agenda buffer described later in this tutorial.

2.3 Dates

An item can be marked with a date indicating when the activity should take place. In addition dates can be assigned to record scheduled start dates, deadlines and ranges of dates. This functionality allows org-mode to be used as a planner, appointment book and simple project management tool.

The user manual describes dates and times in section 8, titled "Timestamps". I think this name is confusing, because a timestamp is a combination of date and time recording when an event occurred. I will not use the word timestamp again in this tutorial!

Dates can appear anywhere in the headline or body of the outline entry. The following two entries are functionally equivalent:

* Win the lottery <2007-10-21 Sun>
* Win the lottery again
<2007-10-21 Sun>
Outline entries can be tagged with several combinations of dates, times and ranges for display in agendas, timelines, or a "sparse-tree" of items approaching a deadlines.

3 Exploring Dates

Now let's explore these various date and times.

3.1 Simple date format

A simple date is specified in a special format enclosed in angle or square brackets, for example, <2007-10-21 Sun> or [2007-10-21 Sun].

The angle bracket notation is for active dates which will appear in agendas and timelines. The square bracket notation is for inactive dates for recording when things happened, and will not appear in agendas or timelines.

The C-c . command is used to prompt for an active date whereas the C-c ! command prompts for an inactive date. The procedures for choosing a date are the same for both types of dates.

An Emacs Calendar frame is displayed above the mini-buffer.



The response to this prompt is combined with the date currently selected in the calendar prompt. Since the calendar is displayed with today's date being active, hitting Enter will choose today's date.

The date currently displayed in the calendar prompt is referred to as the default date and can be changed with the following navigation commands:

Shift-Right arrow to go forward a day. The new date can be seen in the calendar display.
Shift-Left arrow to go back a day. The new date can be seen in the calendar display.
Shift-Up arrow to go back a week. The new date can be seen in the calendar display.
Shift-Down arrow to go forward a week. The new date can be seen in the calendar display.
< scroll the calendar display back by one month - > scroll the calendar display forward by one month
. Go to today. Make sure the cursor is in the calendar frame for this to work.
Here are some of the many ways you can respond to the prompt and how it modifies the default date. Assume the default date is Sunday, 21st October 2007.

10 produces 10th October 2007. A single number is interpreted as the day of the default month.
Tue produces 23rd October. Interpreted as the date nearest the supplied day.
A relative date can be given as the first thing in the input by typing a plus (+) or minus (-) sign, a number and a letter (d, w, m, or y) indicating a change in days, weeks, months or years to today's date.

A double plus or double minus sign makes the input relative to the default date.

Here are the results of the insertion of inactive dates with various inputs:

No response to prompt: 2007-10-21 Sun (Today's date)
+1 2007-10-22 Mon
+1w 2007-10-28 Sun
+1m 2007-11-21 Wed
-1 2007-10-20 Sat
After you have answered the prompt, a date string is inserted into the buffer.



3.2 Date and time format

A time can be added to a date using the methods described in the previous section but adding the time in HH:MM format. For example, entering +1 11:00 gives 2007-10-22 Mon 11:00.

Events with a definite ending time can be recording using two times separated with a hyphen, for example 2007-10-22 Mon 11:00-12:00.

3.3 Date Range

A range of dates can be recorded using two dates separated by a hyphen. These can be entered by entering the first date with C-c ., then immediately running the C-c . command again.

4 Agenda View

The agenda gives an overview of date and time tagged headlines, sorted chronologically.



Let's see how the various dates and times from the buffer above are displayed in the agenda.



The headlines of the items are displayed in the appropriate day.

Items spanning several days appear on each day with a repetition count. For example, (1/3): James on Leave.
Items with times appear before non-timed events, for example, Tuesday.
Days with no events still show the date.
The file name is shown as a prefix, in this case sample2. This can be changed by include the #+CATEGORY: tag at the beginning of the buffer to give a meaningful name.
5 Timeline

A timeline is another view of the date and time-stamped items in the current file. The main purpose of a timeline is to give an overview over events in a project.

A timeline is generated from the Org > Special Views Current File > Timeline menu item or issuing the agenda command C-c a L.



6 Repeating events

Some tasks need to be repeated at regular intervals - daily, weekly, fortnightly, monthly, quarterly and annually. Items can be made to repeat in the agenda view by including a repeater directive at the end of the date. This has the format of a plus sign, a number and a letter indicating a unit of time: days (d), weeks (w), months (m) and years (y).

Therefore, the weekly meeting entries can look like:

*** Tuesday department meeting
<2007-10-23 Tue 10:00-11:00 +1w>
*** Friday afternoon team meeting
<2007-10-26 Fri 15:00-16:00 +1w>
Viewing the agenda and scrolling forward into future weeks will show the date entries.



7 Deadlines and Scheduled Dates

A time stamp can be preceded with a special keyword to facilitate planning your work.

7.1 Deadline Dates

A task, most likely flagged with TODO, is supposed to finish by a deadline date. Work on the task can begin as soon as practical, but must be finished by the deadline date.

A deadline date is entered with the C-c C-d command. The method of entering dates is the same as described previously, but the end result is the additional keyword DEADLINE: preceding the date:



The list above shows an item due today (Sunday report) and an overdue item (Weekly Report) due last Friday. Here is the agenda generated on Sunday 21st October.



An item with a deadline date is displayed in red on the deadline date with a prefix of "Deadline:".

If the deadline is within the number of days set by the ord-deadline-warning-days variable, the information is repeated on today's date with the number of days until the deadline, for example, "In 5 d".

When an item is overdue, the entry is shown in red with the number of days overdue, but shown as a negative number.

If you would to have a longer or shorter warning about an upcoming deadline, include the interval preceded with a minus sign at the end of the date string. The following entry will generate an item in the agenda with the number of days until the 31st January 2008.

* Product Sofware Release Date
DEADLINE: <2008-01-31 Thu -6m>
The agenda line generated today from the entry above is:

Planner: In 102 d.: Product Sofware Release Date
7.2 Repeating Deadlines

When a task with a deadline, such as a weekly or a monthly report, needs to be tracked, it can be set up with a TODO tag and a repeater interval. A weekly report due on midday each Monday could be set up as follows:

** Submit Weekly Report
DEADLINE: <2007-10-22 Mon 12:00 +1w>
This will display each Monday on the agenda. If the entry is changed to a TODO item, work on the report can be tracked.

** TODO Submit Weekly Report
DEADLINE: <2007-10-22 Mon 12:00 +1w>
When the TODO item is closed with C-c C-t a window is opened where you can record a note about closing the task. A date and time stamp is recorded. Note that the date has been increased by the repeater interval, the item is still in the TODO state, and the note is recorded under the item.



7.3 Sparse Tree of Deadlines

The deadlines in the current buffer can be checked with the C-c C-w command. This displays the items that are past due or will become past due within org-deadline-warning-days. Just enough of the buffer is displayed to give context to the items. This feature is not normally used, so the keybinding may be removed at a later date.



With a numeric prefix, check deadlines that fall within that number of days. For example, C-30 C-c C-w will display all deadlines that fall within 30 days. This can also be entered as Esc 30 C-c C-w.



7.4 Scheduled Date

A scheduled date is when you plan to start working on a task. The item will be listed in the agenda on the scheduled date. A reminder will also be given when a scheduled date is in the past, until the item is marked as done. A date is marked as scheduled using the C-c C-s command.

Do not confuse a scheduled date with an event marked with a specific date. Although you use the verb schedule to say "I have scheduled the weekly meeting", this usage of scheduled has a specific meeting.

For example, I can schedule an item to pay my credit card on the 21st of the month, because I get paid on the 20th of each month. An entry could be set up as:

** Pay credit card statement
SCHEDULED: <2007-10-21 Sun +1m>
This will be displayed as:



Scheduled dates and Deadlines can both be supplied for an entry. The earliest day of the month I can pay my credit card is the 21st of the month, however the payment is due by the last day of the month. Therefore I can enhance the entry with a deadline:

** TODO Pay credit card statement
SCHEDULED: <2007-10-21 Sun +1m>
DEADLINE: <2007-10-30 Tue +1m>
Once the item is marked DONE, both dates are advanced by the repeat interval to next month.



The agenda display above shows an event scheduled for last week and this is highlighted in red with how many days overdue.

8 Editing Dates

A date can be edited in several ways. The date can be scrolled forward or backwards by positioning the cursor anyway inside the date string and entering Shift-Right Arrow to go forward a day, or Shift-Left Arrow to go back a day.

Individual components of a date (Year, month and day) can be changed by positioning the cursor on the number to be changed and clicking Shift Up Arrow or Shift Down Arrow to adjust the value. The day of the week corresponding to the date will be adjusted accordingly.

A date can be chosen with the Emacs calendar by positioning the cursor anywhere in the date and entering the C-c . command. The date can be edited according to the methods described in the earlier Simple Date Format section.

8.1 Date Selector Tool

The C-c > command opens the Emacs calendar window displaying the date under the cursor. For example, if the cursor is over the date string <2007-01-01 Mon>, issuing the command will display a calendar with January 2007 in the middle. You can navigate using the commands described in the previous section then choose a date with a mouse-click or pressing Enter.

The date you have chosen is now remembered to be pasted with the C-c < command. Repeating the command will paste multiple copies of the date. This could be useful if you need to apply the same date to several headlines.

9 Examples

A lot of functionality can be gained using dates, repeater intervals, deadline warnings, scheduled and deadline dates. Some uses are: Birthdays, Insurance Policies due dates, Home Maintenance tasks of a repetitive nature.

10 Command Summary

Command Details
Inserting dates
C-c . Prompt for active date
C-c ! Prompt for inactive date
C-c C-d Enter a DEADLINE date
C-c C-s Enter a SCHEDULED date
Date repeater
2007-10-24 Wed +1w Repeat every Wednesday
2007-10-01 Mon +1m Repeat on 1st day every month
Date warning
2007-10-24 Wed -2m Start warning 2 months before
2007-10-24 Wed -20d Start warning 20 days before
Calendar Navigation
Shift-RIGHT Go forward a day
Shift-LEFT Go backward a day
Shift-UP Go to previous week
Shift-DOWN Go to next week
< Scroll calendar back 1 month
> Scroll calendar forward 1 month
. Go to Today
Prompt responses
15 (Number) Date of current month
Tue (Day name) Date of nearest day specified
HH:MM Enter a time
+2d ( or w, m, y) Two days (weeks, months, years)
after today's date
++2d (or w, m, y) Two days (weeks, months, years)
after the default date
+3tue Third Tuesday of the month
(new in 5.13c)
Author: Charles Cave Send Email

Date: 2007/10/24 (Tuesday) 10:39:49 PM

]