org: Weekly/daily agenda
10.3.1 The 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.
‘C-c a 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(1) (like ‘C-u 2 1 C-c a 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’ (or the obsolete ‘org-agenda-ndays’). 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 as ‘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")’ will start 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 will happen automatically. All diary entries
including holidays, anniversaries, etc., will be 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 sexp 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 sexp
entries, and does it faster because there is no overhead for first
creating the diary display. Note that the sexp entries must start at
the left margin, no whitespace is allowed before them. For example, the
following segment of an Org file will be processed and entries will be
made in the agenda:
* Birthdays and similar stuff
#+CATEGORY: Holiday
%%(org-calendar-holiday) ; special function for holiday names
#+CATEGORY: Ann
%%(org-anniversary 1956 5 14)(2) 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 Big Brothers Database to store your contacts, you
will very likely prefer to store anniversaries in BBDB rather than in a
separate Org or diary file. Org supports this and will 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 to press ‘C-o anniversary <RET>’ with the cursor in
a BBDB record and then add the date in the format ‘YYYY-MM-DD’ or
‘MM-DD’, followed by a space and the class of the anniversary
(‘birthday’ or ‘wedding’, or a format string). If you omit the class,
it will default to ‘birthday’. Here are a few examples, the header for
the file ‘org-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 will suffer 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.
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 will then override the value of ‘appt-message-warning-time’ for
this appointment. See the docstring for details.
---------- Footnotes ----------
(1) For backward compatibility, the universal prefix ‘C-u’ causes all
TODO entries to be listed before the agenda. This feature is
deprecated, use the dedicated TODO list, or a block agenda instead
(Block agenda).
(2) ‘org-anniversary’ is just like ‘diary-anniversary’, but the
argument order is always according to ISO and therefore independent of
the value of ‘calendar-date-style’.