31.13.2 Customizing the Holidays

There are several variables listing the default holidays that Emacs knows about. These are: holiday-general-holidays, holiday-local-holidays, holiday-solar-holidays, holiday-bahai-holidays, holiday-christian-holidays, holiday-hebrew-holidays, holiday-islamic-holidays, holiday-oriental-holidays, and holiday-other-holidays. The names should be self-explanatory; e.g., holiday-solar-holidays lists sun- and moon-related holidays.

You can customize these lists of holidays to your own needs, deleting or adding holidays as described below. Set any of them to nil to not show the associated holidays.

The general holidays are, by default, holidays common throughout the United States. In contrast, holiday-local-holidays and holiday-other-holidays are both empty by default. These are intended for system-wide settings and your individual use, respectively.

By default, Emacs does not include all the holidays of the religions that it knows, only those commonly found in secular calendars. For a more extensive collection of religious holidays, you can set any (or all) of the variables calendar-bahai-all-holidays-flag, calendar-christian-all-holidays-flag, calendar-hebrew-all-holidays-flag, or calendar-islamic-all-holidays-flag to t.

Each of the holiday variables is a list of holiday forms, each form describing a holiday (or sometimes a list of holidays). Here is a table of the possible kinds of holiday form. Day numbers and month numbers count starting from 1, but dayname numbers count Sunday as 0. The argument string is always the description of the holiday, as a string.

(holiday-fixed month day string)

A fixed date on the Gregorian calendar.

(holiday-float month dayname k string

&optional day) The kth dayname (dayname=0 for Sunday, and so on) after or before Gregorian date month, day. Negative k means count back from the end of the month. Optional day defaults to 1 if k is positive, and the last day of month otherwise.

(holiday-chinese month day string)

A fixed date on the Chinese calendar.

(holiday-hebrew month day string)

A fixed date on the Hebrew calendar.

(holiday-islamic month day string)

A fixed date on the Islamic calendar.

(holiday-julian month day string)

A fixed date on the Julian calendar.

(holiday-sexp sexp string)

A date calculated by the Lisp expression sexp. The expression should use the variable year to compute and return the date of a holiday in the form of a list (month day year), or nil if the holiday doesn’t happen this year.

(if condition holiday-form)

A holiday that happens only if condition is true.

(function [args])

A list of dates calculated by the function function, called with arguments args.

For example, suppose you want to add Bastille Day, celebrated in France on July 14 (i.e., the fourteenth day of the seventh month). You can do this as follows:

(setq holiday-other-holidays '((holiday-fixed 7 14 "Bastille Day")))

Many holidays occur on a specific day of the week, at a specific time of month. Here is a holiday form describing Hurricane Supplication Day, celebrated in the Virgin Islands on the fourth Monday in July:

(holiday-float 7 1 4 "Hurricane Supplication Day")

Here the 7 specifies July, the 1 specifies Monday (Sunday is 0, Tuesday is 2, and so on), and the 4 specifies the fourth occurrence in the month (1 specifies the first occurrence, 2 the second occurrence, -1 the last occurrence, -2 the second-to-last occurrence, and so on).

You can specify holidays that occur on fixed days of the Bahá’í, Chinese, Hebrew, Islamic, and Julian calendars too. For example,

(setq holiday-other-holidays
      '((holiday-hebrew 10 2 "Last day of Hanukkah")
        (holiday-islamic 3 12 "Mohammed's Birthday")
        (holiday-julian 4 2 "Jefferson's Birthday")))

adds the last day of Hanukkah (since the Hebrew months are numbered with 1 starting from Nisan), the Islamic feast celebrating Mohammed’s birthday (since the Islamic months are numbered from 1 starting with Muharram), and Thomas Jefferson’s birthday, which is 2 April 1743 on the Julian calendar.

To include a holiday conditionally, use either Emacs Lisp’s if or the holiday-sexp form. For example, American presidential elections occur on the first Tuesday after the first Monday in November of years divisible by 4:

(holiday-sexp '(if (zerop (% year 4))
                   (calendar-gregorian-from-absolute
                    (1+ (calendar-dayname-on-or-before
                          1 (+ 6 (calendar-absolute-from-gregorian
                                  (list 11 1 year)))))))
              "US Presidential Election")

or

(if (zerop (% displayed-year 4))
    (holiday-fixed 11
           (calendar-extract-day
             (calendar-gregorian-from-absolute
               (1+ (calendar-dayname-on-or-before
                     1 (+ 6 (calendar-absolute-from-gregorian
                              (list 11 1 displayed-year)))))))
           "US Presidential Election"))

Some holidays just don’t fit into any of these forms because special calculations are involved in their determination. In such cases you must write a Lisp function to do the calculation. To include eclipses, for example, add (eclipses) to holiday-other-holidays and write an Emacs Lisp function eclipses that returns a (possibly empty) list of the relevant Gregorian dates among the range visible in the calendar window, with descriptive strings, like this:

(((6 4 2012) "Lunar Eclipse") ((11 13 2012) "Solar Eclipse") ... )