31.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 applies to.

Calendar mode provides commands to insert certain commonly used sexp entries:

i a

Add an anniversary diary entry for the selected date ( diary-insert-anniversary-entry).

i b

Add a block diary entry for the current region ( diary-insert-block-entry).

i c

Add a cyclic diary entry starting at the date ( diary-insert-cyclic-entry).

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 1988) Arthur's birthday

This entry applies to October 31 in any year after 1988; ‘ 10 31 1988’ specifies the date. (If you are using the European or ISO calendar style, the input order of month, day and year is different.) 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, 2012 through July 10, 2012:

%%(diary-block 6 24 2012 7 10 2012) Vacation

The ‘ 6 24 2012’ indicates the starting date and the ‘ 7 10 2012’ indicates the stopping date. (Again, if you are using the European or ISO calendar style, the input order of month, day and year is different.)

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 2012) Renew medication

This entry applies to March 1, 2012 and every 50th day following; ‘ 3 1 2012’ specifies the starting date. (If you are using the European or ISO calendar style, the input order of month, day and year is different.)

All three of these commands make marking diary entries. To insert a nonmarking entry, give a prefix argument to the command. For example, C-u i a makes a nonmarking anniversary diary entry.

Marking sexp diary entries in the calendar can be 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 the cron utility. Here is a nonmarking, floating diary entry that applies to the fourth Thursday in November:

&%%(diary-float 11 4 4) 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 second 4 specifies the fourth Thursday (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 t, the entry applies to all months of the year.

%%(diary-offset '(diary-float t 3 4) 2) Monthly committee meeting

This entry applies to the Saturday after the third Thursday of each month. The 2 specifies number of days after when the sexp '(diary-float t 3 4) would evaluate to t. This is useful when for example your organization has a committee meeting two days after every monthly meeting which takes place on the third Thursday, or if you would like to attend a virtual meeting scheduled in a different timezone causing a difference in the date.

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 Entries and the Fancy Diary Display.