39.10 The Diary

The Emacs diary keeps track of appointments or other events on a daily basis, in conjunction with the calendar. To use the diary feature, you must first create a diary file containing a list of events and their dates. Then Emacs can automatically pick out and display the events for today, for the immediate future, or for any specified date.

The name of the diary file is specified by the variable diary-file; ~/diary is the default. A sample diary file is (note that the file format is essentially the same as that used by the external shell utility ‘calendar’):

     12/22/1988  Twentieth wedding anniversary!!
     &1/1.       Happy New Year!
     10/22       Ruth's birthday.
     * 21, *:    Payday
     Tuesday--weekly meeting with grad students at 10am
              Supowit, Shen, Bitner, and Kapoor to attend.
     1/13/89     Friday the thirteenth!!
     &thu 4pm    squash game with Lloyd.
     mar 16      Dad's birthday
     April 15, 1989 Income tax due.
     &* 15       time cards due.

This example uses extra spaces to align the event descriptions of most of the entries. Such formatting is purely a matter of taste.

Although you probably will start by creating a diary manually, Emacs provides a number of commands to let you view, add, and change diary entries.

• Displaying the Diary: Viewing diary entries and associated calendar dates.
• Format of Diary File: Entering events in your diary.
• Date Formats: Various ways you can specify dates.
• Adding to Diary: Commands to create diary entries.
• Special Diary Entries: Anniversaries, blocks of dates, cyclic entries, etc.