39.10.5 Special Diary Entries
In addition to entries based on calendar dates, the diary file can
contain sexp entries for regular events such as anniversaries.
These entries are based on Lisp expressions (sexps) that Emacs evaluates
as it scans the diary file. Instead of a date, a sexp entry contains
‘%%’ followed by a Lisp expression which must begin and end with
parentheses. The Lisp expression determines which dates the entry
Calendar mode provides commands to insert certain commonly used
- i a
- Add an anniversary diary entry for the selected date
- i b
- Add a block diary entry for the current region
- i c
- Add a cyclic diary entry starting at the date
If you want to make a diary entry that applies to the anniversary of a
specific date, move point to that date and use the i a command.
This displays the end of your diary file in another window and inserts
the anniversary description; you can then type the rest of the diary
entry. The entry looks like this:
%%(diary-anniversary 10 31 1948) Arthur's birthday
This entry applies to October 31 in any year after 1948; ‘10 31
1948’ specifies the date. (If you are using the European calendar
style, the month and day are interchanged.) The reason this expression
requires a beginning year is that advanced diary functions can use it to
calculate the number of elapsed years.
A block diary entry applies to a specified range of consecutive
dates. Here is a block diary entry that applies to all dates from June
24, 1990 through July 10, 1990:
%%(diary-block 6 24 1990 7 10 1990) Vacation
The ‘6 24 1990’ indicates the starting date and the ‘7 10 1990’
indicates the stopping date. (Again, if you are using the European calendar
style, the month and day are interchanged.)
To insert a block entry, place point and the mark on the two
dates that begin and end the range, and type i b. This command
displays the end of your diary file in another window and inserts the
block description; you can then type the diary entry.
Cyclic diary entries repeat after a fixed interval of days. To
create one, select the starting date and use the i c command. The
command prompts for the length of interval, then inserts the entry,
which looks like this:
%%(diary-cyclic 50 3 1 1990) Renew medication
This entry applies to March 1, 1990 and every 50th day following;
‘3 1 1990’ specifies the starting date. (If you are using the
European calendar style, the month and day are interchanged.)
All three of these commands make marking diary entries. To insert a
nonmarking entry, give a numeric argument to the command. For example,
C-u i a makes a nonmarking anniversary diary entry.
Marking sexp diary entries in the calendar is extremely
time-consuming, since every date visible in the calendar window must be
individually checked. So it's a good idea to make sexp diary entries
nonmarking (with ‘&’) when possible.
Another sophisticated kind of sexp entry, a floating diary entry,
specifies a regularly occurring event by offsets specified in days,
weeks, and months. It is comparable to a crontab entry interpreted by
cron utility. Here is a nonmarking, floating diary entry
that applies to the last Thursday in November:
&%%(diary-float 11 4 -1) American Thanksgiving
The 11 specifies November (the eleventh month), the 4 specifies Thursday
(the fourth day of the week, where Sunday is numbered zero), and the
−1 specifies “last” (1 would mean “first,” 2 would mean
“second,” −2 would mean “second-to-last,” and so on). The
month can be a single month or a list of months. Thus you could change
the 11 above to ‘'(1 2 3)’ and have the entry apply to the last
Thursday of January, February, and March. If the month is
entry applies to all months of the year.
Each of the standard sexp diary entries takes an optional parameter
specifying the name of a face or a single-character string to use when
marking the entry in the calendar. Most generally, sexp diary entries
can perform arbitrary computations to determine when they apply.
see Sexp Diary Entries.