11.3.1 Weekly/daily agenda

The purpose of the weekly/daily agenda is to act like a page of a paper agenda, showing all the tasks for the current week or day.

M-x org-agenda a (org-agenda-list)

Compile an agenda for the current week from a list of Org files. The agenda shows the entries for each day. With a numeric prefix argument⁹⁵—like C-u 2 1 M-x org-agenda a—you may set the number of days to be displayed.

The default number of days displayed in the agenda is set by the variable org-agenda-span. This variable can be set to any number of days you want to see by default in the agenda, or to a span name, such a day, week, month or year. For weekly agendas, the default is to start on the previous Monday (see org-agenda-start-on-weekday). You can also set the start date using a date shift: ‘(setq org-agenda-start-day "+10d")’ starts the agenda ten days from today in the future.

Remote editing from the agenda buffer means, for example, that you can change the dates of deadlines and appointments from the agenda buffer. The commands available in the Agenda buffer are listed in Agenda Commands.

Calendar/Diary integration

Emacs contains the calendar and diary by Edward M. Reingold. The calendar displays a three-month calendar with holidays from different countries and cultures. The diary allows you to keep track of anniversaries, lunar phases, sunrise/set, recurrent appointments (weekly, monthly) and more. In this way, it is quite complementary to Org. It can be very useful to combine output from Org with the diary.

In order to include entries from the Emacs diary into Org mode’s agenda, you only need to customize the variable

(setq org-agenda-include-diary t)

After that, everything happens automatically. All diary entries including holidays, anniversaries, etc., are included in the agenda buffer created by Org mode. SPC, TAB, and RET can be used from the agenda buffer to jump to the diary file in order to edit existing diary entries. The i command to insert new entries for the current date works in the agenda buffer, as well as the commands S, M, and C to display Sunrise/Sunset times, show lunar phases and to convert to other calendars, respectively. c can be used to switch back and forth between calendar and agenda.

If you are using the diary only for expression entries and holidays, it is faster to not use the above setting, but instead to copy or even move the entries into an Org file. Org mode evaluates diary-style expression entries, and does it faster because there is no overhead for first creating the diary display. Note that the expression entries must start at the left margin, no whitespace is allowed before them, as seen in the following segment of an Org file:⁹⁶

* Holidays
  :PROPERTIES:
  :CATEGORY: Holiday
  :END:
%%(org-calendar-holiday)   ; special function for holiday names

* Birthdays
  :PROPERTIES:
  :CATEGORY: Ann
  :END:
%%(org-anniversary 1956  5 14) Arthur Dent is %d years old
%%(org-anniversary 1869 10  2) Mahatma Gandhi would be %d years old

Anniversaries from BBDB

If you are using the Insidious Big Brother Database to store your contacts, you very likely prefer to store anniversaries in BBDB rather than in a separate Org or diary file. Org supports this and can show BBDB anniversaries as part of the agenda. All you need to do is to add the following to one of your agenda files:

* Anniversaries
  :PROPERTIES:
  :CATEGORY: Anniv
  :END:
%%(org-bbdb-anniversaries)

You can then go ahead and define anniversaries for a BBDB record. Basically, you need a field named ‘anniversary’ for the BBDB record which contains the date in the format ‘YYYY-MM-DD’ or ‘MM-DD’, followed by a space and the class of the anniversary (‘birthday’, ‘wedding’, or a format string). If you omit the class, it defaults to ‘birthday’. Here are a few examples, the header for the file ‘ol-bbdb.el’ contains more detailed information.

1973-06-22
06-22
1955-08-02 wedding
2008-04-14 %s released version 6.01 of Org mode, %d years ago

After a change to BBDB, or for the first agenda display during an Emacs session, the agenda display suffers a short delay as Org updates its hash with anniversaries. However, from then on things will be very fast, much faster in fact than a long list of ‘%%(diary-anniversary)’ entries in an Org or Diary file.

If you would like to see upcoming anniversaries with a bit of forewarning, you can use the following instead:

* Anniversaries
  :PROPERTIES:
  :CATEGORY: Anniv
  :END:
%%(org-bbdb-anniversaries-future 3)

That will give you three days’ warning: on the anniversary date itself and the two days prior. The argument is optional: if omitted, it defaults to 7.

Appointment reminders

Org can interact with Emacs appointments notification facility. To add the appointments of your agenda files, use the command org-agenda-to-appt. This command lets you filter through the list of your appointments and add only those belonging to a specific category or matching a regular expression. It also reads a ‘APPT_WARNTIME’ property which overrides the value of appt-message-warning-time for this appointment. See the docstring for details.