1 @c This is part of the Emacs manual.
2 @c Copyright (C) 2004-2011 Free Software Foundation, Inc.
3 @c See file emacs.texi for copying conditions.
5 @c This file is included either in emacs-xtra.texi (when producing the
6 @c printed version) or in the main Emacs manual (for the on-line version).
8 @c Moved here from the Emacs Lisp Reference Manual, 2005-03-26.
9 @node Advanced Calendar/Diary Usage
10 @section Customizing the Calendar and Diary
12 There are many customizations that you can use to make the calendar and
13 diary suit your personal tastes.
16 * Calendar Customizing:: Calendar layout and hooks.
17 * Holiday Customizing:: Defining your own holidays.
18 * Date Display Format:: Changing the format.
19 * Time Display Format:: Changing the format.
20 * Diary Customizing:: Defaults you can set.
21 * Non-Gregorian Diary:: Diary entries based on other calendars.
22 * Diary Display:: A choice of ways to display the diary.
23 * Fancy Diary Display:: Sorting diary entries, using included diary files.
24 * Sexp Diary Entries:: More flexible diary entries.
27 @node Calendar Customizing
28 @subsection Customizing the Calendar
30 @vindex calendar-intermonth-text
31 @cindex calendar layout
32 @cindex calendar week numbers
33 The calendar display unfortunately cannot be changed from three
34 months, but you can customize the whitespace used by setting the
35 variables: @code{calendar-left-margin},
36 @code{calendar-day-header-width}, @code{calendar-day-digit-width},
37 @code{calendar-column-width}, and @code{calendar-intermonth-spacing}.
38 To display text @emph{between} the months, for example week numbers,
39 customize the variables @code{calendar-intermonth-header} and
40 @code{calendar-intermonth-text} as described in their documentation.
42 @vindex calendar-holiday-marker
43 @vindex diary-entry-marker
44 @vindex calenday-today-marker
45 The variable @code{calendar-holiday-marker} specifies how to mark a
46 date as being a holiday. Its value may be a single-character string to
47 insert next to the date, or a face name to use for displaying the date.
48 Likewise, the variable @code{diary-entry-marker} specifies how to mark a
49 date that has diary entries, and @code{calenday-today-marker} is used by
50 the function @code{calendar-mark-today} to mark today's date. By
51 default, the calendar uses faces named @code{holiday}, @code{diary}, and
52 @code{calendar-today} for these purposes.
54 @vindex calendar-load-hook
55 The variable @code{calendar-load-hook} is a normal hook run when the
56 calendar package is first loaded (before actually starting to display
59 @vindex calendar-initial-window-hook
60 Starting the calendar runs the normal hook
61 @code{calendar-initial-window-hook}. Recomputation of the calendar
62 display does not run this hook. But if you leave the calendar with the
63 @kbd{q} command and reenter it, the hook runs again.@refill
65 @vindex calendar-today-visible-hook
66 @findex calendar-star-date
67 The variable @code{calendar-today-visible-hook} is a normal hook run
68 after the calendar buffer has been prepared with the calendar when the
69 current date is visible in the window. One use of this hook is to
70 mark today's date; to do that use either of the functions
71 @code{calendar-mark-today} or @code{calendar-star-date}:
73 @findex calendar-mark-today
75 (add-hook 'calendar-today-visible-hook 'calendar-mark-today)
78 @vindex calendar-today-invisible-hook
80 A similar normal hook, @code{calendar-today-invisible-hook} is run if
81 the current date is @emph{not} visible in the window.
83 @vindex calendar-move-hook
84 Each of the calendar cursor motion commands runs the hook
85 @code{calendar-move-hook} after it moves the cursor.
87 @node Holiday Customizing
88 @subsection Customizing the Holidays
90 @vindex calendar-holidays
91 @vindex holiday-oriental-holidays
92 @vindex holiday-solar-holidays
93 Emacs knows about holidays defined by entries on one of several lists.
94 The lists of holidays that Emacs uses are for
95 general holidays (@code{holiday-general-holidays}),
96 local holidays (@code{holiday-local-holidays}),
97 sun- and moon-related holidays (@code{holiday-solar-holidays}),
98 Baha'i holidays (@code{holiday-bahai-holidays}),
99 Christian holidays (@code{holiday-christian-holidays}),
100 Hebrew (Jewish) holidays (@code{holiday-hebrew-holidays}),
101 Islamic (Muslim) holidays (@code{holiday-islamic-holidays}),
102 Oriental holidays (@code{holiday-oriental-holidays}),
103 and other holidays (@code{holiday-other-holidays}).
105 You can customize these lists of holidays to your own needs, deleting or
106 adding holidays as described below. Set any of them to @code{nil} to
107 eliminate the associated holidays.
109 @vindex holiday-general-holidays
110 The general holidays are, by default, holidays common throughout the
113 @vindex holiday-local-holidays
114 There are no default local holidays, but your site may supply some.
116 @vindex holiday-bahai-holidays
117 @vindex holiday-christian-holidays
118 @vindex holiday-hebrew-holidays
119 @vindex holiday-islamic-holidays
120 @vindex calendar-bahai-all-holidays-flag
121 @vindex calendar-christian-all-holidays-flag
122 @vindex calendar-hebrew-all-holidays-flag
123 @vindex calendar-islamic-all-holidays-flag
124 By default, Emacs does not include all the holidays of the religions
125 that it knows, only those commonly found in secular calendars. For a
126 more extensive collection of religious holidays, you can set any (or
127 all) of the variables @code{calendar-bahai-all-holidays-flag},
128 @code{calendar-christian-all-holidays-flag},
129 @code{calendar-hebrew-all-holidays-flag}, or
130 @code{calendar-islamic-all-holidays-flag} to @code{t}.
132 @vindex holiday-other-holidays
133 You can set the variable @code{holiday-other-holidays} to any list of
134 holidays. This list, normally empty, is intended for individual use.
136 @cindex holiday forms
137 Each of the holiday variables is a list of @dfn{holiday forms}, each
138 form describing a holiday (or sometimes a list of holidays).
140 Here is a table of the possible kinds of holiday form. Day numbers
141 and month numbers count starting from 1, but ``dayname'' numbers
142 count Sunday as 0. The element @var{string} is always the
143 description of the holiday, as a string.
146 @item (holiday-fixed @var{month} @var{day} @var{string})
147 A fixed date on the Gregorian calendar.
149 @item (holiday-float @var{month} @var{dayname} @var{k} @var{string}
151 The @var{k}th @var{dayname} (@var{dayname}=0 for Sunday, and so on)
152 after or before Gregorian date @var{month}, @var{day}. Negative @var{k}
153 means count back from the end of the month. Optional @var{day} defaults
154 to 1 if @var{k} is positive, and the last day of @var{month} otherwise.
156 @item (holiday-chinese @var{month} @var{day} @var{string})
157 A fixed date on the Chinese calendar.
159 @item (holiday-hebrew @var{month} @var{day} @var{string})
160 A fixed date on the Hebrew calendar.
162 @item (holiday-islamic @var{month} @var{day} @var{string})
163 A fixed date on the Islamic calendar.
165 @item (holiday-julian @var{month} @var{day} @var{string})
166 A fixed date on the Julian calendar.
168 @item (holiday-sexp @var{sexp} @var{string})
169 A date calculated by the Lisp expression @var{sexp}. The expression
170 should use the variable @code{year} to compute and return the date of a
171 holiday in the form of a list @code{(@var{month} @var{day} @var{year})},
172 or @code{nil} if the holiday doesn't happen this year.
174 @item (if @var{condition} @var{holiday-form})
175 A holiday that happens only if @var{condition} is true.
177 @item (@var{function} @r{[}@var{args}@r{]})
178 A list of dates calculated by the function @var{function}, called with
179 arguments @var{args}.
182 For example, suppose you want to add Bastille Day, celebrated in
183 France on July 14 (i.e., the fourteenth day of the seventh month). You
184 can do this as follows:
187 (setq holiday-other-holidays '((holiday-fixed 7 14 "Bastille Day")))
190 Many holidays occur on a specific day of the week, at a specific time
191 of month. Here is a holiday form describing Hurricane Supplication Day,
192 celebrated in the Virgin Islands on the fourth Monday in August:
195 (holiday-float 8 1 4 "Hurricane Supplication Day")
199 Here the 8 specifies August, the 1 specifies Monday (Sunday is 0,
200 Tuesday is 2, and so on), and the 4 specifies the fourth occurrence in
201 the month (1 specifies the first occurrence, 2 the second occurrence,
202 @minus{}1 the last occurrence, @minus{}2 the second-to-last occurrence, and
205 You can specify holidays that occur on fixed days of the Baha'i,
206 Chinese, Hebrew, Islamic, and Julian calendars too. For example,
209 (setq holiday-other-holidays
210 '((holiday-hebrew 10 2 "Last day of Hanukkah")
211 (holiday-islamic 3 12 "Mohammed's Birthday")
212 (holiday-julian 4 2 "Jefferson's Birthday")))
216 adds the last day of Hanukkah (since the Hebrew months are numbered with
217 1 starting from Nisan), the Islamic feast celebrating Mohammed's
218 birthday (since the Islamic months are numbered from 1 starting with
219 Muharram), and Thomas Jefferson's birthday, which is 2 April 1743 on the
222 To include a holiday conditionally, use either Emacs Lisp's @code{if}
223 or the @code{holiday-sexp} form. For example, American presidential
224 elections occur on the first Tuesday after the first Monday in November
225 of years divisible by 4:
228 (holiday-sexp '(if (zerop (% year 4))
229 (calendar-gregorian-from-absolute
230 (1+ (calendar-dayname-on-or-before
231 1 (+ 6 (calendar-absolute-from-gregorian
232 (list 11 1 year)))))))
233 "US Presidential Election")
240 (if (zerop (% displayed-year 4))
242 (calendar-extract-day
243 (calendar-gregorian-from-absolute
244 (1+ (calendar-dayname-on-or-before
245 1 (+ 6 (calendar-absolute-from-gregorian
246 (list 11 1 displayed-year)))))))
247 "US Presidential Election"))
250 Some holidays just don't fit into any of these forms because special
251 calculations are involved in their determination. In such cases you
252 must write a Lisp function to do the calculation. To include eclipses,
253 for example, add @code{(eclipses)} to @code{holiday-other-holidays}
254 and write an Emacs Lisp function @code{eclipses} that returns a
255 (possibly empty) list of the relevant Gregorian dates among the range
256 visible in the calendar window, with descriptive strings, like this:
259 (((6 27 1991) "Lunar Eclipse") ((7 11 1991) "Solar Eclipse") ... )
262 @node Date Display Format
263 @subsection Date Display Format
264 @vindex calendar-date-display-form
266 You can customize the manner of displaying dates in the diary, in mode
267 lines, and in messages by setting @code{calendar-date-display-form}.
268 This variable holds a list of expressions that can involve the variables
269 @code{month}, @code{day}, and @code{year}, which are all numbers in
270 string form, and @code{monthname} and @code{dayname}, which are both
271 alphabetic strings. In the American style, the default value of this
275 ((if dayname (concat dayname ", ")) monthname " " day ", " year)
279 while in the European style this value is the default:
282 ((if dayname (concat dayname ", ")) day " " monthname " " year)
286 The default ISO date representation is:
289 ((format "%s-%.2d-%.2d" year (string-to-number month)
290 (string-to-number day)))
294 This specifies a typical American format:
297 (month "/" day "/" (substring year -2))
300 @node Time Display Format
301 @subsection Time Display Format
302 @vindex calendar-time-display-form
304 The calendar and diary by default display times of day in the
305 conventional American style with the hours from 1 through 12, minutes,
306 and either @samp{am} or @samp{pm}. If you prefer the European style,
307 also known in the US as military, in which the hours go from 00 to 23,
308 you can alter the variable @code{calendar-time-display-form}. This
309 variable is a list of expressions that can involve the variables
310 @code{12-hours}, @code{24-hours}, and @code{minutes}, which are all
311 numbers in string form, and @code{am-pm} and @code{time-zone}, which are
312 both alphabetic strings. The default value is:
315 (12-hours ":" minutes am-pm
316 (if time-zone " (") time-zone (if time-zone ")"))
320 Here is a value that provides European style times:
323 (24-hours ":" minutes
324 (if time-zone " (") time-zone (if time-zone ")"))
327 Note that few calendar functions return a time of day (at present, only
330 @node Diary Customizing
331 @subsection Customizing the Diary
333 @vindex diary-show-holidays-flag
334 Ordinarily, the diary window indicates any holidays that fall on the
335 date of the diary entries, either in the mode line or the buffer itself.
336 The process of checking for holidays can be slow, depending on the
337 defined holidays. In that case, setting @code{diary-show-holidays-flag}
338 to @code{nil} will speed up the diary display.
340 @vindex diary-number-of-entries
341 The variable @code{diary-number-of-entries} controls the number of
342 days of diary entries to be displayed at one time. It affects the
343 initial display when @code{calendar-view-diary-initially-flag} is
344 @code{t}, as well as the command @kbd{M-x diary}. For example, a value
345 of 1 (the default) displays only the current day's diary entries,
346 whereas a value of 2 will also show the next day's entries. The value
347 can also be a vector of seven integers: for example, if the value is
348 @code{[0 2 2 2 2 4 1]} then no diary entries appear on Sunday, the
349 current date's and the next day's diary entries appear Monday through
350 Thursday, Friday through Monday's entries appear on Friday, while on
351 Saturday only that day's entries appear.
353 @vindex diary-date-forms
354 You can customize the form of dates in your diary file by setting the
355 variable @code{diary-date-forms}. This variable is a list of patterns
356 for recognizing a date. Each date pattern is a list whose elements may
357 be regular expressions (@pxref{Regular Expressions,,, elisp, the Emacs
358 Lisp Reference Manual}) or the symbols @code{month}, @code{day},
359 @code{year}, @code{monthname}, and @code{dayname}. All these elements
360 serve as patterns that match certain kinds of text in the diary file.
361 In order for the date pattern, as a whole, to match, all of its elements
362 must match consecutively.
364 A regular expression in a date pattern matches in its usual fashion,
365 using the standard syntax table altered so that @samp{*} is a word
368 The symbols @code{month}, @code{day}, @code{year}, @code{monthname},
369 and @code{dayname} match the month number, day number, year number,
370 month name, and day name of the date being considered. The symbols that
371 match numbers allow leading zeros; those that match names allow
372 capitalization and abbreviation (as specified by
373 @code{calendar-month-abbrev-array} and
374 @code{calendar-day-abbrev-array}). All the symbols can match @samp{*};
375 since @samp{*} in a diary entry means ``any day'', ``any month'', and so
376 on, it should match regardless of the date being considered.
378 The default value of @code{diary-date-forms} in the American style is
379 provided by @code{diary-american-date-forms}:
382 ((month "/" day "[^/0-9]")
383 (month "/" day "/" year "[^0-9]")
384 (monthname " *" day "[^,0-9]")
385 (monthname " *" day ", *" year "[^0-9]")
390 Other default styles are provided by @code{diary-european-date-forms}
391 and @code{diary-iso-date-forms}.
393 The date patterns in the list must be @emph{mutually exclusive} and
394 must not match any portion of the diary entry itself, just the date and
395 one character of whitespace. If, to be mutually exclusive, the pattern
396 must match a portion of the diary entry text---beyond the whitespace
397 that ends the date---then the first element of the date pattern
398 @emph{must} be @code{backup}. This causes the date recognizer to back
399 up to the beginning of the current word of the diary entry, after
400 finishing the match. Even if you use @code{backup}, the date pattern
401 must absolutely not match more than a portion of the first word of the
402 diary entry. For example, the default value of
403 @code{diary-european-date-forms} is:
406 ((day "/" month "[^/0-9]")
407 (day "/" month "/" year "[^0-9]")
408 (backup day " *" monthname "\\W+\\<\\([^*0-9]\\|\\([0-9]+[:aApP]\\)\\)")
409 (day " *" monthname " *" year "[^0-9]")
414 Notice the use of @code{backup} in the third pattern, because it needs
415 to match part of a word beyond the date itself to distinguish it from
418 @node Non-Gregorian Diary
419 @subsection Diary Entries Using non-Gregorian Calendars
421 As well as entries based on the standard Gregorian calendar, your
422 diary can have entries based on Baha'i, Hebrew, or Islamic dates.
423 Recognition of such entries can be time-consuming, however, and since
424 most people don't use them, you must explicitly enable their use. If
425 you want the diary to recognize Hebrew-date diary entries, for example,
428 @vindex diary-nongregorian-listing-hook
429 @vindex diary-nongregorian-marking-hook
430 @findex diary-hebrew-list-entries
431 @findex diary-hebrew-mark-entries
432 @findex diary-islamic-list-entries
433 @findex diary-islamic-mark-entries
434 @findex diary-bahai-list-entries
435 @findex diary-bahai-mark-entries
437 (add-hook 'diary-nongregorian-listing-hook 'diary-hebrew-list-entries)
438 (add-hook 'diary-nongregorian-marking-hook 'diary-hebrew-mark-entries)
442 Similarly, for Islamic and Baha'i entries, add
443 @code{diary-islamic-list-entries} and @code{diary-islamic-mark-entries}, or
444 @code{diary-bahai-list-entries} and @code{diary-bahai-mark-entries}.
446 @vindex diary-bahai-entry-symbol
447 @vindex diary-hebrew-entry-symbol
448 @vindex diary-islamic-entry-symbol
449 These diary entries have the same formats as Gregorian-date diary
450 entries; except that @code{diary-bahai-entry-symbol} (default @samp{B})
451 must precede a Baha'i date, @code{diary-hebrew-entry-symbol} (default
452 @samp{H}) a Hebrew date, and @code{diary-islamic-entry-symbol} (default
453 @samp{I}) an Islamic date. Moreover, non-Gregorian month names may not
454 be abbreviated (because the first three letters are often not unique).
455 (Note also that you must use ``Adar I'' if you want Adar of a common
456 Hebrew year.) For example, a diary entry for the Hebrew date Heshvan 25
457 could look like this:
460 HHeshvan 25 Happy Hebrew birthday!
464 and would appear in the diary for any date that corresponds to Heshvan 25
465 on the Hebrew calendar. And here is an Islamic-date diary entry that matches
469 IDhu al-Qada 25 Happy Islamic birthday!
472 As with Gregorian-date diary entries, non-Gregorian entries are
473 nonmarking if preceded by @code{diary-nonmarking-symbol} (default
476 Here is a table of commands used in the calendar to create diary
477 entries that match the selected date and other dates that are similar in
478 the Baha'i, Hebrew, or Islamic calendars:
482 @code{diary-hebrew-insert-entry}
484 @code{diary-hebrew-insert-monthly-entry}
486 @code{diary-hebrew-insert-yearly-entry}
488 @code{diary-islamic-insert-entry}
490 @code{diary-islamic-insert-monthly-entry}
492 @code{diary-islamic-insert-yearly-entry}
494 @code{diary-bahai-insert-entry}
496 @code{diary-bahai-insert-monthly-entry}
498 @code{diary-bahai-insert-yearly-entry}
501 @findex diary-hebrew-insert-entry
502 @findex diary-hebrew-insert-monthly-entry
503 @findex diary-hebrew-insert-yearly-entry
504 @findex diary-islamic-insert-entry
505 @findex diary-islamic-insert-monthly-entry
506 @findex diary-islamic-insert-yearly-entry
507 @findex diary-bahai-insert-entry
508 @findex diary-bahai-insert-monthly-entry
509 @findex diary-bahai-insert-yearly-entry
510 These commands work much like the corresponding commands for ordinary
511 diary entries: they apply to the date that point is on in the calendar
512 window, and what they do is insert just the date portion of a diary
513 entry at the end of your diary file. You must then insert the rest of
514 the diary entry. The basic commands add an entry for the specific
515 non-Gregorian date, the @samp{monthly} commands for the given
516 non-Gregorian day-within-month in every month, and the @samp{yearly}
517 commands for the given non-Gregorian day and month in every year.
520 @subsection Diary Display
521 @vindex diary-display-function
522 @findex diary-simple-display
523 @findex diary-fancy-display
526 Diary display works by preparing the list of diary entries and then
527 running the function specified by the variable
528 @code{diary-display-function}. The default value
529 @code{diary-fancy-display} displays diary entries and holidays by
530 copying them into a special buffer that exists only for the sake of
531 display. Copying diary entries to a separate buffer provides an
532 opportunity to change the displayed text to make it prettier---for
533 example, to sort the entries by the dates they apply to.
535 @vindex diary-list-include-blanks
536 Ordinarily, the fancy diary buffer does not show days for which there
537 are no diary entries, even if that day is a holiday. If you want such
538 days to be shown in the fancy diary buffer, set the variable
539 @code{diary-list-include-blanks} to @code{t}.@refill
541 @c View mode does not seem to be described in the manual.
542 @c buffers.texi has a brief mention.
543 The fancy diary buffer enables View mode, a minor mode that provides
544 commands for scrolling and searching the text. For example, @key{SPC}
545 and @key{DEL} scroll forward and backward, and @key{s} starts an
546 incremental search. See the documentation of the function
547 @code{view-mode} for more information.
549 The alternative display method @code{diary-simple-display} shows the
550 actual diary buffer, and uses invisible text to hide entries that don't
551 apply. Holidays are shown in the mode line. The advantage of this
552 method is that you can edit the buffer and save your changes directly to
553 the diary file. This method is not as flexible as the fancy method,
554 however. For example, it cannot sort entries. Another disadvantage is
555 that invisible text can be confusing. For example, if you copy a region
556 of text in order to paste it elsewhere, invisible text may be included.
557 Similarly, since the diary buffer as you see it is an illusion, simply
558 printing the buffer may not print what you see on your screen.
560 @vindex diary-print-entries-hook
561 @findex diary-print-entries
562 For this reason, there is a special command to print hard copy of the
563 diary buffer @emph{as it appears}; this command is @kbd{M-x
564 diary-print-entries}. It works with either display method, although
565 with the fancy display you can also print the buffer like any other. To
566 print a hard copy of a day-by-day diary for a week, position point on
567 the first day of the week, type @kbd{7 d}, and then do @kbd{M-x
568 diary-print-entries}. As usual, the inclusion of the holidays slows
569 down the display slightly; you can speed things up by setting the
570 variable @code{diary-show-holidays-flag} to @code{nil}.
572 This command prepares a temporary buffer that contains only the diary
573 entries currently visible in the diary buffer. Unlike with the simple
574 display, the other irrelevant entries are really absent, not just
575 hidden. After preparing the buffer, it runs the hook
576 @code{diary-print-entries-hook}. The default value of this hook sends
577 the data directly to the printer with the command @code{lpr-buffer}
578 (@pxref{Printing}). If you want to use a different command to do the
579 printing, just change the value of this hook. Other uses might include,
580 for example, rearranging the lines into order by day and time.
582 You can edit the diary entries as they appear in the simple diary
583 window, but it is important to remember that the buffer displayed
584 contains the @emph{entire} diary file, with portions of it concealed
585 from view. This means, for instance, that the @kbd{C-f}
586 (@code{forward-char}) command can put point at what appears to be the
587 end of the line, but what is in reality the middle of some concealed
590 @emph{Be careful when editing the diary entries in the simple display!}
591 Inserting additional lines or adding/deleting characters in the middle
592 of a visible line cannot cause problems, but editing at the end of a
593 line may not do what you expect. Deleting a line may delete other
594 invisible entries that follow it. Before editing the simple diary
595 buffer, it is best to display the entire file with @kbd{s}
596 (@code{diary-show-all-entries}).
598 @node Fancy Diary Display
599 @subsection Fancy Diary Display
601 The following features only work with the fancy diary display.
603 @cindex sorting diary entries
604 You can use the normal hook @code{diary-list-entries-hook} to sort
605 each day's diary entries by their time of day. Here's how:
607 @findex diary-sort-entries
609 (add-hook 'diary-list-entries-hook 'diary-sort-entries t)
613 For each day, this sorts diary entries that begin with a recognizable
614 time of day according to their times. Diary entries without times come
615 first within each day. Note how the sort command is placed at the end
616 of the hook list, in case earlier members of the list change the order
617 of the diary entries, or add items.
619 @vindex diary-include-string
620 Your main diary file can include other files. This permits a group of
621 people to share a diary file for events that apply to all of them.
622 Lines in the diary file starting with @code{diary-include-string}:
625 #include "@var{filename}"
629 include the diary entries from the file @var{filename} in the fancy
630 diary buffer. The include mechanism is recursive, so that included
631 files can include other files, and so on (you must be careful not to
632 have a cycle of inclusions, of course). Here is how to enable the
635 @vindex diary-list-entries-hook
636 @vindex diary-mark-entries-hook
637 @findex diary-include-other-diary-files
638 @findex diary-mark-included-diary-files
640 (add-hook 'diary-list-entries-hook 'diary-include-other-diary-files)
641 (add-hook 'diary-mark-entries-hook 'diary-mark-included-diary-files)
644 The include mechanism works only with the fancy diary display, because
645 simple diary display shows the entries directly from your diary file.
647 @node Sexp Diary Entries
648 @subsection Sexp Entries and the Fancy Diary Display
649 @cindex sexp diary entries
651 @vindex diary-sexp-entry-symbol
652 Sexp diary entries allow you to do more than just have complicated
653 conditions under which a diary entry applies. Sexp entries should be
654 preceded by @code{diary-sexp-entry-symbol} (default @samp{%%}) in the
655 diary file. With the fancy diary display, sexp entries can generate the
656 text of the entry depending on the date itself.
658 For example, an anniversary diary entry can insert
659 the number of years since the anniversary date into the text of the
660 diary entry. Thus the @samp{%d} in this diary entry:
662 @findex diary-anniversary
664 %%(diary-anniversary 10 31 1948) Arthur's birthday (%d years old)
668 gets replaced by the age, so on October 31, 1990 the entry appears in
669 the fancy diary buffer like this:
672 Arthur's birthday (42 years old)
676 If the diary file instead contains this entry:
679 %%(diary-anniversary 10 31 1948) Arthur's %d%s birthday
683 the entry in the fancy diary buffer for October 31, 1990 appears like this:
686 Arthur's 42nd birthday
689 Similarly, cyclic diary entries can interpolate the number of repetitions
694 %%(diary-cyclic 50 1 1 1990) Renew medication (%d%s time)
701 Renew medication (5th time)
705 in the fancy diary display on September 8, 1990.
707 There is an early reminder diary sexp that includes its entry in the
708 diary not only on the date of occurrence, but also on earlier dates.
709 For example, if you want a reminder a week before your anniversary, you
714 %%(diary-remind '(diary-anniversary 12 22 1968) 7) Ed's anniversary
718 and the fancy diary will show @samp{Ed's anniversary} both on December
719 15 and on December 22.
722 The function @code{diary-date} applies to dates described by a month,
723 day, year combination, each of which can be an integer, a list of
724 integers, or @code{t} (meaning all values). For example,
727 %%(diary-date '(10 11 12) 22 t) Rake leaves
731 causes the fancy diary to show
738 on October 22, November 22, and December 22 of every year.
741 The function @code{diary-float} allows you to describe diary entries
742 that apply to dates like the third Friday of November, or the last
743 Tuesday in April. The parameters are the @var{month}, @var{dayname},
744 and an index @var{n}. The entry appears on the @var{n}th @var{dayname}
745 after the first day of @var{month}, where @var{dayname}=0 means Sunday,
746 1 means Monday, and so on. If @var{n} is negative it counts backward
747 from the end of @var{month}. The value of @var{month} can be a list of
748 months, a single month, or @code{t} to specify all months. You can also
749 use an optional parameter @var{day} to specify the @var{n}th
750 @var{dayname} on or after/before @var{day} of @var{month}; the value of
751 @var{day} defaults to 1 if @var{n} is positive and to the last day of
752 @var{month} if @var{n} is negative. For example,
755 %%(diary-float t 1 -1) Pay rent
759 causes the fancy diary to show
766 on the last Monday of every month.
768 The generality of sexp diary entries lets you specify any diary
769 entry that you can describe algorithmically. A sexp diary entry
770 contains an expression that computes whether the entry applies to any
771 given date. If its value is non-@code{nil}, the entry applies to that
772 date; otherwise, it does not. The expression can use the variable
773 @code{date} to find the date being considered; its value is a list
774 (@var{month} @var{day} @var{year}) that refers to the Gregorian
777 The sexp diary entry applies to a date when the expression's value
778 is non-@code{nil}, but some values have more specific meanings. If
779 the value is a string, that string is a description of the event which
780 occurs on that date. The value can also have the form
781 @code{(@var{mark} . @var{string})}; then @var{mark} specifies how to
782 mark the date in the calendar, and @var{string} is the description of
783 the event. If @var{mark} is a single-character string, that character
784 appears next to the date in the calendar. If @var{mark} is a face
785 name, the date is displayed in that face. If @var{mark} is
786 @code{nil}, that specifies no particular highlighting for the date.
788 Suppose you get paid on the 21st of the month if it is a weekday, and
789 on the Friday before if the 21st is on a weekend. Here is how to write
790 a sexp diary entry that matches those dates:
793 &%%(let ((dayname (calendar-day-of-week date))
795 (or (and (= day 21) (memq dayname '(1 2 3 4 5)))
796 (and (memq day '(19 20)) (= dayname 5)))
797 ) Pay check deposited
800 The following sexp diary entries take advantage of the ability (in the fancy
801 diary display) to concoct diary entries whose text varies based on the date:
803 @findex diary-sunrise-sunset
804 @findex diary-lunar-phases
805 @findex diary-day-of-year
806 @findex diary-iso-date
807 @findex diary-julian-date
808 @findex diary-astro-day-number
809 @findex diary-bahai-date
810 @findex diary-chinese-date
811 @findex diary-coptic-date
812 @findex diary-ethiopic-date
813 @findex diary-hebrew-date
814 @findex diary-islamic-date
815 @findex diary-french-date
816 @findex diary-mayan-date
817 @findex diary-persian-date
819 @item %%(diary-sunrise-sunset)
820 Make a diary entry for today's local times of sunrise and sunset.
821 @item %%(diary-lunar-phases)
822 Make a diary entry for the phases (quarters) of the moon.
823 @item %%(diary-day-of-year)
824 Make a diary entry with today's day number in the current year and the number
825 of days remaining in the current year.
826 @item %%(diary-iso-date)
827 Make a diary entry with today's equivalent ISO commercial date.
828 @item %%(diary-julian-date)
829 Make a diary entry with today's equivalent Julian calendar date.
830 @item %%(diary-astro-day-number)
831 Make a diary entry with today's equivalent astronomical (Julian) day number.
832 @item %%(diary-bahai-date)
833 Make a diary entry with today's equivalent Baha'i calendar date.
834 @item %%(diary-chinese-date)
835 Make a diary entry with today's equivalent Chinese calendar date.
836 @item %%(diary-coptic-date)
837 Make a diary entry with today's equivalent Coptic calendar date.
838 @item %%(diary-ethiopic-date)
839 Make a diary entry with today's equivalent Ethiopic calendar date.
840 @item %%(diary-french-date)
841 Make a diary entry with today's equivalent date on the French Revolutionary
843 @item %%(diary-hebrew-date)
844 Make a diary entry with today's equivalent Hebrew calendar date.
845 @item %%(diary-islamic-date)
846 Make a diary entry with today's equivalent Islamic calendar date.
847 @item %%(diary-mayan-date)
848 Make a diary entry with today's equivalent Mayan calendar date.
849 @item %%(diary-persian-date)
850 Make a diary entry with today's equivalent Persian calendar date.
854 For example, including the diary entry
857 &%%(diary-hebrew-date)
861 causes every day's diary display to contain the equivalent date on the
862 Hebrew calendar, if you are using the fancy diary display. (With simple
863 diary display, the literal line @samp{&%%(diary-hebrew-date)} appears in
864 the diary for any date.)
866 This function has been used to construct certain standard Hebrew sexp
870 @findex diary-hebrew-rosh-hodesh
871 @cindex parasha, weekly
872 @findex diary-hebrew-parasha
873 @cindex candle lighting times
874 @findex diary-hebrew-sabbath-candles
876 @findex diary-hebrew-omer
878 @findex diary-hebrew-yahrzeit
880 @item %%(diary-hebrew-rosh-hodesh)
881 Make a diary entry that tells the occurrence and ritual announcement of each
883 @item %%(diary-hebrew-parasha)
884 Make a Saturday diary entry that tells the weekly synagogue scripture reading.
885 @item %%(diary-hebrew-sabbath-candles)
886 Make a Friday diary entry that tells the @emph{local time} of Sabbath
888 @item %%(diary-hebrew-omer)
889 Make a diary entry that gives the omer count, when appropriate.
890 @item %%(diary-hebrew-yahrzeit @var{month} @var{day} @var{year}) @var{name}
891 Make a diary entry marking the anniversary of a date of death. The date
892 is the @emph{Gregorian} (civil) date of death. The diary entry appears
893 on the proper Hebrew calendar anniversary and on the day before. (The
894 order of the parameters changes according to the calendar date style;
895 for example in the European style to @var{day}, @var{month}, @var{year}.)
898 All the functions documented above take an optional argument
899 @var{mark} which specifies how to mark the date in the calendar display.
900 If one of these functions decides that it applies to a certain date,
901 it returns a value that contains @var{mark}, as described above.