1 @c This is part of the Emacs manual.
2 @c Copyright (C) 2004, 2005, 2006, 2007, 2008, 2009
3 @c Free Software Foundation, Inc.
4 @c See file emacs.texi for copying conditions.
6 @c This file is included either in emacs-xtra.texi (when producing the
7 @c printed version) or in the main Emacs manual (for the on-line version).
9 @c Moved here from the Emacs Lisp Reference Manual, 2005-03-26.
10 @node Advanced Calendar/Diary Usage
11 @section Customizing the Calendar and Diary
13 There are many customizations that you can use to make the calendar and
14 diary suit your personal tastes.
17 * Calendar Customizing:: Calendar layout and hooks.
18 * Holiday Customizing:: Defining your own holidays.
19 * Date Display Format:: Changing the format.
20 * Time Display Format:: Changing the format.
21 * Diary Customizing:: Defaults you can set.
22 * Non-Gregorian Diary:: Diary entries based on other calendars.
23 * Fancy Diary Display:: Enhancing the diary display, sorting entries,
24 using included diary files.
25 * Sexp Diary Entries:: Fancy things you can do.
28 @node Calendar Customizing
29 @subsection Customizing the Calendar
31 @vindex calendar-intermonth-text
32 @cindex calendar layout
33 @cindex calendar week numbers
34 The calendar display unfortunately cannot be changed from three
35 months, but you can customize the whitespace used by setting the
36 variables: @code{calendar-left-margin},
37 @code{calendar-intermonth-spacing}, @code{calendar-column-width},
38 @code{calendar-day-header-width}, and @code{calendar-day-digit-width}.
39 To display text @emph{between} the months, for example week numbers,
40 customize the variables @code{calendar-intermonth-header} and
41 @code{calendar-intermonth-text} as described in their documentation.
43 @vindex calendar-holiday-marker
44 @vindex diary-entry-marker
45 @vindex calenday-today-marker
46 The variable @code{calendar-holiday-marker} specifies how to mark a
47 date as being a holiday. Its value may be a single-character string to
48 insert next to the date, or a face name to use for displaying the date.
49 Likewise, the variable @code{diary-entry-marker} specifies how to mark a
50 date that has diary entries, and @code{calenday-today-marker} is used by
51 the function @code{calendar-mark-today} to mark today's date. By
52 default, the calendar uses faces named @code{holiday}, @code{diary}, and
53 @code{calendar-today} for these purposes.
55 @vindex calendar-load-hook
56 The variable @code{calendar-load-hook} is a normal hook run when the
57 calendar package is first loaded (before actually starting to display
60 @vindex calendar-initial-window-hook
61 Starting the calendar runs the normal hook
62 @code{calendar-initial-window-hook}. Recomputation of the calendar
63 display does not run this hook. But if you leave the calendar with the
64 @kbd{q} command and reenter it, the hook runs again.@refill
66 @vindex calendar-today-visible-hook
67 @findex calendar-star-date
68 The variable @code{calendar-today-visible-hook} is a normal hook run
69 after the calendar buffer has been prepared with the calendar when the
70 current date is visible in the window. One use of this hook is to
71 mark today's date; to do that use either of the functions
72 @code{calendar-mark-today} or @code{calendar-star-date}:
74 @findex calendar-mark-today
76 (add-hook 'calendar-today-visible-hook 'calendar-mark-today)
79 @vindex calendar-today-invisible-hook
81 A similar normal hook, @code{calendar-today-invisible-hook} is run if
82 the current date is @emph{not} visible in the window.
84 @vindex calendar-move-hook
85 Each of the calendar cursor motion commands runs the hook
86 @code{calendar-move-hook} after it moves the cursor.
88 @node Holiday Customizing
89 @subsection Customizing the Holidays
91 @vindex calendar-holidays
92 @vindex holiday-oriental-holidays
93 @vindex holiday-solar-holidays
94 Emacs knows about holidays defined by entries on one of several lists.
95 The lists of holidays that Emacs uses are for general holidays
96 (@code{holiday-general-holidays}), local holidays
97 (@code{holiday-local-holidays}), Baha'i holidays
98 (@code{holiday-bahai-holidays}), Christian holidays
99 (@code{holiday-christian-holidays}), Hebrew (Jewish) holidays
100 (@code{holiday-hebrew-holidays}), Islamic (Muslim) holidays
101 (@code{holiday-islamic-holidays}), Oriental holidays
102 (@code{holiday-oriental-holidays}), sun- and moon-related holidays
103 (@code{holiday-solar-holidays}), and other holidays
104 (@code{holiday-other-holidays}).
106 You can customize these lists of holidays to your own needs, deleting or
107 adding holidays as described below. Set any of them to @code{nil} to
108 eliminate the associated holidays.
110 @vindex holiday-general-holidays
111 The general holidays are, by default, holidays common throughout the
114 @vindex holiday-local-holidays
115 There are no default local holidays, but your site may supply some.
117 @vindex holiday-bahai-holidays
118 @vindex holiday-christian-holidays
119 @vindex holiday-hebrew-holidays
120 @vindex holiday-islamic-holidays
121 @vindex calendar-bahai-all-holidays-flag
122 @vindex calendar-christian-all-holidays-flag
123 @vindex calendar-hebrew-all-holidays-flag
124 @vindex calendar-islamic-all-holidays-flag
125 By default, Emacs does not include all the holidays of the religions
126 that it knows, only those commonly found in secular calendars. For a
127 more extensive collection of religious holidays, you can set any (or
128 all) of the variables @code{calendar-bahai-all-holidays-flag},
129 @code{calendar-christian-all-holidays-flag},
130 @code{calendar-hebrew-all-holidays-flag}, or
131 @code{calendar-islamic-all-holidays-flag} to @code{t}.
133 @vindex holiday-other-holidays
134 You can set the variable @code{holiday-other-holidays} to any list of
135 holidays. This list, normally empty, is intended for individual use.
137 @cindex holiday forms
138 Each of the holiday variables is a list of @dfn{holiday forms}, each
139 form describing a holiday (or sometimes a list of holidays).
141 Here is a table of the possible kinds of holiday form. Day numbers
142 and month numbers count starting from 1, but ``dayname'' numbers
143 count Sunday as 0. The element @var{string} is always the
144 description of the holiday, as a string.
147 @item (holiday-fixed @var{month} @var{day} @var{string})
148 A fixed date on the Gregorian calendar.
150 @item (holiday-float @var{month} @var{dayname} @var{k} @var{string}
152 The @var{k}th @var{dayname} (@var{dayname}=0 for Sunday, and so on)
153 after or before Gregorian date @var{month}, @var{day}. Negative @var{k}
154 means count back from the end of the month. Optional @var{day} defaults
155 to 1 if @var{k} is positive, and the last day of @var{month} otherwise.
157 @item (holiday-chinese @var{month} @var{day} @var{string})
158 A fixed date on the Chinese calendar.
160 @item (holiday-hebrew @var{month} @var{day} @var{string})
161 A fixed date on the Hebrew calendar.
163 @item (holiday-islamic @var{month} @var{day} @var{string})
164 A fixed date on the Islamic calendar.
166 @item (holiday-julian @var{month} @var{day} @var{string})
167 A fixed date on the Julian calendar.
169 @item (holiday-sexp @var{sexp} @var{string})
170 A date calculated by the Lisp expression @var{sexp}. The expression
171 should use the variable @code{year} to compute and return the date of a
172 holiday in the form of a list @code{(@var{month} @var{day} @var{year})},
173 or @code{nil} if the holiday doesn't happen this year.
175 @item (if @var{condition} @var{holiday-form})
176 A holiday that happens only if @var{condition} is true.
178 @item (@var{function} @r{[}@var{args}@r{]})
179 A list of dates calculated by the function @var{function}, called with
180 arguments @var{args}.
183 For example, suppose you want to add Bastille Day, celebrated in
184 France on July 14 (i.e., the fourteenth day of the seventh month). You
185 can do this as follows:
188 (setq other-holidays '((holiday-fixed 7 14 "Bastille Day")))
191 Many holidays occur on a specific day of the week, at a specific time
192 of month. Here is a holiday form describing Hurricane Supplication Day,
193 celebrated in the Virgin Islands on the fourth Monday in August:
196 (holiday-float 8 1 4 "Hurricane Supplication Day")
200 Here the 8 specifies August, the 1 specifies Monday (Sunday is 0,
201 Tuesday is 2, and so on), and the 4 specifies the fourth occurrence in
202 the month (1 specifies the first occurrence, 2 the second occurrence,
203 @minus{}1 the last occurrence, @minus{}2 the second-to-last occurrence, and
206 You can specify holidays that occur on fixed days of the Baha'i,
207 Chinese, Hebrew, Islamic, and Julian calendars too. For example,
211 '((holiday-hebrew 10 2 "Last day of Hanukkah")
212 (holiday-islamic 3 12 "Mohammed's Birthday")
213 (holiday-julian 4 2 "Jefferson's Birthday")))
217 adds the last day of Hanukkah (since the Hebrew months are numbered with
218 1 starting from Nisan), the Islamic feast celebrating Mohammed's
219 birthday (since the Islamic months are numbered from 1 starting with
220 Muharram), and Thomas Jefferson's birthday, which is 2 April 1743 on the
223 To include a holiday conditionally, use either Emacs Lisp's @code{if}
224 or the @code{holiday-sexp} form. For example, American presidential
225 elections occur on the first Tuesday after the first Monday in November
226 of years divisible by 4:
229 (holiday-sexp '(if (zerop (% year 4))
230 (calendar-gregorian-from-absolute
231 (1+ (calendar-dayname-on-or-before
232 1 (+ 6 (calendar-absolute-from-gregorian
233 (list 11 1 year)))))))
234 "US Presidential Election")
241 (if (zerop (% displayed-year 4))
243 (calendar-extract-day
244 (calendar-gregorian-from-absolute
245 (1+ (calendar-dayname-on-or-before
246 1 (+ 6 (calendar-absolute-from-gregorian
247 (list 11 1 displayed-year)))))))
248 "US Presidential Election"))
251 Some holidays just don't fit into any of these forms because special
252 calculations are involved in their determination. In such cases you
253 must write a Lisp function to do the calculation. To include eclipses,
254 for example, add @code{(eclipses)} to @code{holiday-other-holidays}
255 and write an Emacs Lisp function @code{eclipses} that returns a
256 (possibly empty) list of the relevant Gregorian dates among the range
257 visible in the calendar window, with descriptive strings, like this:
260 (((6 27 1991) "Lunar Eclipse") ((7 11 1991) "Solar Eclipse") ... )
263 @node Date Display Format
264 @subsection Date Display Format
265 @vindex calendar-date-display-form
267 You can customize the manner of displaying dates in the diary, in mode
268 lines, and in messages by setting @code{calendar-date-display-form}.
269 This variable holds a list of expressions that can involve the variables
270 @code{month}, @code{day}, and @code{year}, which are all numbers in
271 string form, and @code{monthname} and @code{dayname}, which are both
272 alphabetic strings. In the American style, the default value of this
276 ((if dayname (concat dayname ", ")) monthname " " day ", " year)
280 while in the European style this value is the default:
283 ((if dayname (concat dayname ", ")) day " " monthname " " year)
287 The default ISO date representation is:
290 ((format "%s-%.2d-%.2d" year (string-to-number month)
291 (string-to-number day)))
295 This specifies a typical American format:
298 (month "/" day "/" (substring year -2))
301 @node Time Display Format
302 @subsection Time Display Format
303 @vindex calendar-time-display-form
305 The calendar and diary by default display times of day in the
306 conventional American style with the hours from 1 through 12, minutes,
307 and either @samp{am} or @samp{pm}. If you prefer the European style,
308 also known in the US as military, in which the hours go from 00 to 23,
309 you can alter the variable @code{calendar-time-display-form}. This
310 variable is a list of expressions that can involve the variables
311 @code{12-hours}, @code{24-hours}, and @code{minutes}, which are all
312 numbers in string form, and @code{am-pm} and @code{time-zone}, which are
313 both alphabetic strings. The default value is:
316 (12-hours ":" minutes am-pm
317 (if time-zone " (") time-zone (if time-zone ")"))
321 Here is a value that provides European style times:
324 (24-hours ":" minutes
325 (if time-zone " (") time-zone (if time-zone ")"))
328 Note that few calendar functions return a time of day (at present, only
331 @node Diary Customizing
332 @subsection Customizing the Diary
334 @vindex diary-show-holidays-flag
335 Ordinarily, the mode line of the diary window indicates any holidays
336 that fall on the date of the diary entries. The process of checking for
337 holidays can be slow, depending on the defined holidays. In that case,
338 setting @code{diary-show-holidays-flag} to @code{nil} will speed up the
341 @vindex diary-number-of-entries
342 The variable @code{diary-number-of-entries} controls the number of
343 days of diary entries to be displayed at one time. It affects the
344 initial display when @code{calendar-view-diary-initially-flag} is
345 @code{t}, as well as the command @kbd{M-x diary}. For example, a value
346 of 1 (the default) displays only the current day's diary entries,
347 whereas a value of 2 will also show the next day's entries. The value
348 can also be a vector of seven integers: for example, if the value is
349 @code{[0 2 2 2 2 4 1]} then no diary entries appear on Sunday, the
350 current date's and the next day's diary entries appear Monday through
351 Thursday, Friday through Monday's entries appear on Friday, while on
352 Saturday only that day's entries appear.
354 @vindex diary-print-entries-hook
355 @findex diary-print-entries
356 The variable @code{diary-print-entries-hook} is a normal hook run
357 after preparation of a temporary buffer containing just the diary
358 entries currently visible in the diary buffer. (The other, irrelevant
359 diary entries are really absent from the temporary buffer; in the diary
360 buffer, they are merely hidden.) The default value of this hook does
361 the printing with the command @code{lpr-buffer}. If you want to use a
362 different command to do the printing, just change the value of this
363 hook. Other uses might include, for example, rearranging the lines into
364 order by day and time.
366 @vindex diary-date-forms
367 You can customize the form of dates in your diary file by setting the
368 variable @code{diary-date-forms}. This variable is a list of patterns
369 for recognizing a date. Each date pattern is a list whose elements may
370 be regular expressions (@pxref{Regular Expressions,,, elisp, the Emacs
371 Lisp Reference Manual}) or the symbols @code{month}, @code{day},
372 @code{year}, @code{monthname}, and @code{dayname}. All these elements
373 serve as patterns that match certain kinds of text in the diary file.
374 In order for the date pattern, as a whole, to match, all of its elements
375 must match consecutively.
377 A regular expression in a date pattern matches in its usual fashion,
378 using the standard syntax table altered so that @samp{*} is a word
381 The symbols @code{month}, @code{day}, @code{year}, @code{monthname},
382 and @code{dayname} match the month number, day number, year number,
383 month name, and day name of the date being considered. The symbols that
384 match numbers allow leading zeros; those that match names allow
385 capitalization and abbreviation (as specified by
386 @code{calendar-month-abbrev-array} and
387 @code{calendar-day-abbrev-array}). All the symbols can match @samp{*};
388 since @samp{*} in a diary entry means ``any day'', ``any month'', and so
389 on, it should match regardless of the date being considered.
391 The default value of @code{diary-date-forms} in the American style is
392 provided by @code{diary-american-date-forms}:
395 ((month "/" day "[^/0-9]")
396 (month "/" day "/" year "[^0-9]")
397 (monthname " *" day "[^,0-9]")
398 (monthname " *" day ", *" year "[^0-9]")
403 Other default styles are provided by @code{diary-european-date-forms}
404 and @code{diary-iso-date-forms}.
406 The date patterns in the list must be @emph{mutually exclusive} and
407 must not match any portion of the diary entry itself, just the date and
408 one character of whitespace. If, to be mutually exclusive, the pattern
409 must match a portion of the diary entry text---beyond the whitespace
410 that ends the date---then the first element of the date pattern
411 @emph{must} be @code{backup}. This causes the date recognizer to back
412 up to the beginning of the current word of the diary entry, after
413 finishing the match. Even if you use @code{backup}, the date pattern
414 must absolutely not match more than a portion of the first word of the
415 diary entry. For example, the default value of
416 @code{diary-european-date-forms} is:
419 ((day "/" month "[^/0-9]")
420 (day "/" month "/" year "[^0-9]")
421 (backup day " *" monthname "\\W+\\<\\([^*0-9]\\|\\([0-9]+[:aApP]\\)\\)")
422 (day " *" monthname " *" year "[^0-9]")
427 Notice the use of @code{backup} in the third pattern, because it needs
428 to match part of a word beyond the date itself to distinguish it from
431 @node Non-Gregorian Diary
432 @subsection Diary Entries Using non-Gregorian Calendars
434 As well as entries based on the standard Gregorian calendar, your
435 diary can have entries based on Baha'i, Hebrew, or Islamic dates.
436 Recognition of such entries can be time-consuming, however, and since
437 most people don't use them, you must explicitly enable their use. If
438 you want the diary to recognize Hebrew-date diary entries, for example,
441 @vindex diary-nongregorian-listing-hook
442 @vindex diary-nongregorian-marking-hook
443 @findex diary-hebrew-list-entries
444 @findex diary-hebrew-mark-entries
445 @findex diary-islamic-list-entries
446 @findex diary-islamic-mark-entries
447 @findex diary-bahai-list-entries
448 @findex diary-bahai-mark-entries
450 (add-hook 'diary-nongregorian-listing-hook 'diary-hebrew-list-entries)
451 (add-hook 'diary-nongregorian-marking-hook 'diary-hebrew-mark-entries)
455 Similarly, for Islamic and Baha'i entries, add
456 @code{diary-islamic-list-entries} and @code{diary-islamic-mark-entries}, or
457 @code{diary-bahai-list-entries} and @code{diary-bahai-mark-entries}.
459 @vindex diary-bahai-entry-symbol
460 @vindex diary-hebrew-entry-symbol
461 @vindex diary-islamic-entry-symbol
462 These diary entries have the same formats as Gregorian-date diary
463 entries; except that @code{diary-bahai-entry-symbol} (default @samp{B})
464 must precede a Baha'i date, @code{diary-hebrew-entry-symbol} (default
465 @samp{H}) a Hebrew date, and @code{diary-islamic-entry-symbol} (default
466 @samp{I}) an Islamic date. Moreover, non-Gregorian month names may not
467 be abbreviated (because the first three letters are often not unique).
468 For example, a diary entry for the Hebrew date Heshvan 25 could look
472 HHeshvan 25 Happy Hebrew birthday!
476 and would appear in the diary for any date that corresponds to Heshvan 25
477 on the Hebrew calendar. And here is an Islamic-date diary entry that matches
481 IDhu al-Qada 25 Happy Islamic birthday!
484 As with Gregorian-date diary entries, non-Gregorian entries are
485 nonmarking if preceded by @code{diary-nonmarking-symbol} (default
488 Here is a table of commands used in the calendar to create diary
489 entries that match the selected date and other dates that are similar in
490 the Baha'i, Hebrew, or Islamic calendars:
494 @code{diary-hebrew-insert-entry}
496 @code{diary-hebrew-insert-monthly-entry}
498 @code{diary-hebrew-insert-yearly-entry}
500 @code{diary-islamic-insert-entry}
502 @code{diary-islamic-insert-monthly-entry}
504 @code{diary-islamic-insert-yearly-entry}
506 @code{diary-bahai-insert-entry}
508 @code{diary-bahai-insert-monthly-entry}
510 @code{diary-bahai-insert-yearly-entry}
513 @findex diary-hebrew-insert-entry
514 @findex diary-hebrew-insert-monthly-entry
515 @findex diary-hebrew-insert-yearly-entry
516 @findex diary-islamic-insert-entry
517 @findex diary-islamic-insert-monthly-entry
518 @findex diary-islamic-insert-yearly-entry
519 @findex diary-bahai-insert-entry
520 @findex diary-bahai-insert-monthly-entry
521 @findex diary-bahai-insert-yearly-entry
522 These commands work much like the corresponding commands for ordinary
523 diary entries: they apply to the date that point is on in the calendar
524 window, and what they do is insert just the date portion of a diary
525 entry at the end of your diary file. You must then insert the rest of
526 the diary entry. The basic commands add an entry for the specific
527 non-Gregorian date, the @samp{monthly} commands for the given
528 non-Gregorian day-within-month in every month, and the @samp{yearly}
529 commands for the given non-Gregorian day and month in every year.
531 @node Fancy Diary Display
532 @subsection Fancy Diary Display
533 @vindex diary-display-function
534 @findex diary-simple-display
535 @findex diary-fancy-display
538 Diary display works by preparing the diary buffer and then running the
539 function specified by the variable @code{diary-display-function}. The
540 default value (@code{diary-simple-display}) hides the irrelevant diary
541 entries and then displays the buffer. The alternative
542 @code{diary-fancy-display} displays diary entries and holidays by
543 copying them into a special buffer that exists only for the sake of
544 display. Copying to a separate buffer provides an opportunity to change
545 the displayed text to make it prettier---for example, to sort the
546 entries by the dates they apply to.
548 As with simple diary display, you can print a hard copy of the buffer
549 with @code{diary-print-entries}. To print a hard copy of a day-by-day
550 diary for a week, position point on Sunday of that week, type
551 @kbd{7 d}, and then do @kbd{M-x diary-print-entries}. As usual, the
552 inclusion of the holidays slows down the display slightly; you can speed
553 things up by setting the variable @code{diary-show-holidays-flag} to
556 @vindex diary-list-include-blanks
557 Ordinarily, the fancy diary buffer does not show days for which there are
558 no diary entries, even if that day is a holiday. If you want such days to be
559 shown in the fancy diary buffer, set the variable
560 @code{diary-list-include-blanks} to @code{t}.@refill
562 @cindex sorting diary entries
563 If you use the fancy diary display, you can use the normal hook
564 @code{diary-list-entries-hook} to sort each day's diary entries by their
565 time of day. Here's how:
567 @findex diary-sort-entries
569 (add-hook 'diary-list-entries-hook 'diary-sort-entries t)
573 For each day, this sorts diary entries that begin with a recognizable
574 time of day according to their times. Diary entries without times come
575 first within each day.
577 @vindex diary-include-string
578 Fancy diary display also has the ability to process included diary
579 files. This permits a group of people to share a diary file for events
580 that apply to all of them. Lines in the diary file starting with
581 @code{diary-include-string}:
584 #include "@var{filename}"
588 include the diary entries from the file @var{filename} in the fancy
589 diary buffer. The include mechanism is recursive, so that included
590 files can include other files, and so on (you must be careful not to
591 have a cycle of inclusions, of course). Here is how to enable the
594 @vindex diary-list-entries-hook
595 @vindex diary-mark-entries-hook
596 @findex diary-include-other-diary-files
597 @findex diary-mark-included-diary-files
599 (add-hook 'diary-list-entries-hook 'diary-include-other-diary-files)
600 (add-hook 'diary-mark-entries-hook 'diary-mark-included-diary-files)
603 The include mechanism works only with the fancy diary display, because
604 ordinary diary display shows the entries directly from your diary file.
606 @node Sexp Diary Entries
607 @subsection Sexp Entries and the Fancy Diary Display
608 @cindex sexp diary entries
610 @vindex diary-sexp-entry-symbol
611 Sexp diary entries allow you to do more than just have complicated
612 conditions under which a diary entry applies. Sexp entries should be
613 preceded by @code{diary-sexp-entry-symbol} (default @samp{%%}) in the
614 diary file. If you use the fancy diary display, sexp entries can
615 generate the text of the entry depending on the date itself.
617 For example, an anniversary diary entry can insert
618 the number of years since the anniversary date into the text of the
619 diary entry. Thus the @samp{%d} in this diary entry:
621 @findex diary-anniversary
623 %%(diary-anniversary 10 31 1948) Arthur's birthday (%d years old)
627 gets replaced by the age, so on October 31, 1990 the entry appears in
628 the fancy diary buffer like this:
631 Arthur's birthday (42 years old)
635 If the diary file instead contains this entry:
638 %%(diary-anniversary 10 31 1948) Arthur's %d%s birthday
642 the entry in the fancy diary buffer for October 31, 1990 appears like this:
645 Arthur's 42nd birthday
648 Similarly, cyclic diary entries can interpolate the number of repetitions
653 %%(diary-cyclic 50 1 1 1990) Renew medication (%d%s time)
660 Renew medication (5th time)
664 in the fancy diary display on September 8, 1990.
666 There is an early reminder diary sexp that includes its entry in the
667 diary not only on the date of occurrence, but also on earlier dates.
668 For example, if you want a reminder a week before your anniversary, you
673 %%(diary-remind '(diary-anniversary 12 22 1968) 7) Ed's anniversary
677 and the fancy diary will show @samp{Ed's anniversary} both on December
678 15 and on December 22.
681 The function @code{diary-date} applies to dates described by a month,
682 day, year combination, each of which can be an integer, a list of
683 integers, or @code{t} (meaning all values). For example,
686 %%(diary-date '(10 11 12) 22 t) Rake leaves
690 causes the fancy diary to show
697 on October 22, November 22, and December 22 of every year.
700 The function @code{diary-float} allows you to describe diary entries
701 that apply to dates like the third Friday of November, or the last
702 Tuesday in April. The parameters are the @var{month}, @var{dayname},
703 and an index @var{n}. The entry appears on the @var{n}th @var{dayname}
704 after the first day of @var{month}, where @var{dayname}=0 means Sunday,
705 1 means Monday, and so on. If @var{n} is negative it counts backward
706 from the end of @var{month}. The value of @var{month} can be a list of
707 months, a single month, or @code{t} to specify all months. You can also
708 use an optional parameter @var{day} to specify the @var{n}th
709 @var{dayname} on or after/before @var{day} of @var{month}; the value of
710 @var{day} defaults to 1 if @var{n} is positive and to the last day of
711 @var{month} if @var{n} is negative. For example,
714 %%(diary-float t 1 -1) Pay rent
718 causes the fancy diary to show
725 on the last Monday of every month.
727 The generality of sexp diary entries lets you specify any diary
728 entry that you can describe algorithmically. A sexp diary entry
729 contains an expression that computes whether the entry applies to any
730 given date. If its value is non-@code{nil}, the entry applies to that
731 date; otherwise, it does not. The expression can use the variable
732 @code{date} to find the date being considered; its value is a list
733 (@var{month} @var{day} @var{year}) that refers to the Gregorian
736 The sexp diary entry applies to a date when the expression's value
737 is non-@code{nil}, but some values have more specific meanings. If
738 the value is a string, that string is a description of the event which
739 occurs on that date. The value can also have the form
740 @code{(@var{mark} . @var{string})}; then @var{mark} specifies how to
741 mark the date in the calendar, and @var{string} is the description of
742 the event. If @var{mark} is a single-character string, that character
743 appears next to the date in the calendar. If @var{mark} is a face
744 name, the date is displayed in that face. If @var{mark} is
745 @code{nil}, that specifies no particular highlighting for the date.
747 Suppose you get paid on the 21st of the month if it is a weekday, and
748 on the Friday before if the 21st is on a weekend. Here is how to write
749 a sexp diary entry that matches those dates:
752 &%%(let ((dayname (calendar-day-of-week date))
754 (or (and (= day 21) (memq dayname '(1 2 3 4 5)))
755 (and (memq day '(19 20)) (= dayname 5)))
756 ) Pay check deposited
759 The following sexp diary entries take advantage of the ability (in the fancy
760 diary display) to concoct diary entries whose text varies based on the date:
762 @findex diary-sunrise-sunset
763 @findex diary-lunar-phases
764 @findex diary-day-of-year
765 @findex diary-iso-date
766 @findex diary-julian-date
767 @findex diary-astro-day-number
768 @findex diary-bahai-date
769 @findex diary-chinese-date
770 @findex diary-coptic-date
771 @findex diary-ethiopic-date
772 @findex diary-hebrew-date
773 @findex diary-islamic-date
774 @findex diary-french-date
775 @findex diary-mayan-date
776 @findex diary-persian-date
778 @item %%(diary-sunrise-sunset)
779 Make a diary entry for today's local times of sunrise and sunset.
780 @item %%(diary-lunar-phases)
781 Make a diary entry for the phases (quarters) of the moon.
782 @item %%(diary-day-of-year)
783 Make a diary entry with today's day number in the current year and the number
784 of days remaining in the current year.
785 @item %%(diary-iso-date)
786 Make a diary entry with today's equivalent ISO commercial date.
787 @item %%(diary-julian-date)
788 Make a diary entry with today's equivalent Julian calendar date.
789 @item %%(diary-astro-day-number)
790 Make a diary entry with today's equivalent astronomical (Julian) day number.
791 @item %%(diary-bahai-date)
792 Make a diary entry with today's equivalent Baha'i calendar date.
793 @item %%(diary-chinese-date)
794 Make a diary entry with today's equivalent Chinese calendar date.
795 @item %%(diary-coptic-date)
796 Make a diary entry with today's equivalent Coptic calendar date.
797 @item %%(diary-ethiopic-date)
798 Make a diary entry with today's equivalent Ethiopic calendar date.
799 @item %%(diary-french-date)
800 Make a diary entry with today's equivalent date on the French Revolutionary
802 @item %%(diary-hebrew-date)
803 Make a diary entry with today's equivalent Hebrew calendar date.
804 @item %%(diary-islamic-date)
805 Make a diary entry with today's equivalent Islamic calendar date.
806 @item %%(diary-mayan-date)
807 Make a diary entry with today's equivalent Mayan calendar date.
808 @item %%(diary-persian-date)
809 Make a diary entry with today's equivalent Persian calendar date.
813 For example, including the diary entry
816 &%%(diary-hebrew-date)
820 causes every day's diary display to contain the equivalent date on the
821 Hebrew calendar, if you are using the fancy diary display. (With simple
822 diary display, the literal line @samp{&%%(diary-hebrew-date)} appears in
823 the diary for any date.)
825 This function has been used to construct certain standard Hebrew sexp
829 @findex diary-hebrew-rosh-hodesh
830 @cindex parasha, weekly
831 @findex diary-hebrew-parasha
832 @cindex candle lighting times
833 @findex diary-hebrew-sabbath-candles
835 @findex diary-hebrew-omer
837 @findex diary-hebrew-yahrzeit
839 @item %%(diary-hebrew-rosh-hodesh)
840 Make a diary entry that tells the occurrence and ritual announcement of each
842 @item %%(diary-hebrew-parasha)
843 Make a Saturday diary entry that tells the weekly synagogue scripture reading.
844 @item %%(diary-hebrew-sabbath-candles)
845 Make a Friday diary entry that tells the @emph{local time} of Sabbath
847 @item %%(diary-hebrew-omer)
848 Make a diary entry that gives the omer count, when appropriate.
849 @item %%(diary-hebrew-yahrzeit @var{month} @var{day} @var{year}) @var{name}
850 Make a diary entry marking the anniversary of a date of death. The date
851 is the @emph{Gregorian} (civil) date of death. The diary entry appears
852 on the proper Hebrew calendar anniversary and on the day before. (The
853 order of the parameters changes according to the calendar date style;
854 for example in the European style to @var{day}, @var{month}, @var{year}.)
857 All the functions documented above take an optional argument
858 @var{mark} which specifies how to mark the date in the calendar display.
859 If one of these functions decides that it applies to a certain date,
860 it returns a value that contains @var{mark}, as described above.
863 arch-tag: 52cb299f-fd1f-4616-bfe6-91b988669431