*** empty log message ***
[emacs.git] / lispref / calendar.texi
blob4b60a19505bc67e680a8ab533ed5ac519f9a0f66
1 @c -*-texinfo-*-
2 @c This is part of the GNU Emacs Lisp Reference Manual.
3 @c Copyright (C) 1990, 1991, 1992, 1993, 1995, 1998 Free Software Foundation, Inc. 
4 @c See the file elisp.texi for copying conditions.
5 @node Calendar, System Interface, Display, Top
6 @chapter Customizing the Calendar and Diary
8   There are many customizations that you can use to make the calendar and
9 diary suit your personal tastes.
11 @menu
12 * Calendar Customizing::   Defaults you can set.
13 * Holiday Customizing::    Defining your own holidays.
14 * Date Display Format::    Changing the format.
15 * Time Display Format::    Changing the format.
16 * Daylight Savings::       Changing the default.
17 * Diary Customizing::      Defaults you can set.
18 * Hebrew/Islamic Entries:: How to obtain them.
19 * Fancy Diary Display::    Enhancing the diary display, sorting entries, 
20                              using included diary files.
21 * Sexp Diary Entries::     Fancy things you can do.
22 * Appt Customizing::       Customizing appointment reminders.
23 @end menu
25 @node Calendar Customizing
26 @section Customizing the Calendar
27 @vindex view-diary-entries-initially
29   If you set the variable @code{view-diary-entries-initially} to
30 @code{t}, calling up the calendar automatically displays the diary
31 entries for the current date as well.  The diary dates appear only if
32 the current date is visible.  If you add both of the following lines to
33 your init file:@refill
35 @example
36 (setq view-diary-entries-initially t)
37 (calendar)
38 @end example
40 @noindent
41 this displays both the calendar and diary windows whenever you start Emacs.
43 @vindex view-calendar-holidays-initially
44   Similarly, if you set the variable
45 @code{view-calendar-holidays-initially} to @code{t}, entering the
46 calendar automatically displays a list of holidays for the current
47 three-month period.  The holiday list appears in a separate
48 window.
50 @vindex mark-diary-entries-in-calendar
51   You can set the variable @code{mark-diary-entries-in-calendar} to
52 @code{t} in order to mark any dates with diary entries.  This takes
53 effect whenever the calendar window contents are recomputed.  There are
54 two ways of marking these dates: by changing the face (@pxref{Faces}),
55 or by placing a plus sign (@samp{+}) beside the date.
57 @vindex mark-holidays-in-calendar
58   Similarly, setting the variable @code{mark-holidays-in-calendar} to
59 @code{t} marks holiday dates, either with a change of face or with an
60 asterisk (@samp{*}).
62 @vindex calendar-holiday-marker
63 @vindex diary-entry-marker
64   The variable @code{calendar-holiday-marker} specifies how to mark a
65 date as being a holiday.  Its value may be a character to insert next to
66 the date, or a face name to use for displaying the date.  Likewise, the
67 variable @code{diary-entry-marker} specifies how to mark a date that has
68 diary entries.  The calendar creates faces named @code{holiday-face} and
69 @code{diary-face} for these purposes; those symbols are the default
70 values of these variables.
72 @vindex calendar-load-hook
73   The variable @code{calendar-load-hook} is a normal hook run when the
74 calendar package is first loaded (before actually starting to display
75 the calendar).
77 @vindex initial-calendar-window-hook
78   Starting the calendar runs the normal hook
79 @code{initial-calendar-window-hook}.  Recomputation of the calendar
80 display does not run this hook.  But if you leave the calendar with the
81 @kbd{q} command and reenter it, the hook runs again.@refill
83 @vindex today-visible-calendar-hook
84   The variable @code{today-visible-calendar-hook} is a normal hook run
85 after the calendar buffer has been prepared with the calendar when the
86 current date is visible in the window.  One use of this hook is to
87 replace today's date with asterisks; to do that, use the hook function
88 @code{calendar-star-date}.
90 @findex calendar-star-date
91 @example
92 (add-hook 'today-visible-calendar-hook 'calendar-star-date)
93 @end example
95 @noindent
96 Another standard hook function marks the current date, either by
97 changing its face or by adding an asterisk.  Here's how to use it:
99 @findex calendar-mark-today
100 @example
101 (add-hook 'today-visible-calendar-hook 'calendar-mark-today)
102 @end example
104 @noindent
105 @vindex calendar-today-marker
106 The variable @code{calendar-today-marker} specifies how to mark today's
107 date.  Its value should be a character to insert next to the date or a
108 face name to use for displaying the date.  A face named
109 @code{calendar-today-face} is provided for this purpose; that symbol is
110 the default for this variable.
112 @vindex today-invisible-calendar-hook
113 @noindent
114   A similar normal hook, @code{today-invisible-calendar-hook} is run if
115 the current date is @emph{not} visible in the window.
117 @vindex calendar-move-hook
118   Starting in Emacs 21, each of the calendar cursor motion commands
119 runs the hook @code{calendar-move-hook} after it moves the cursor.
121 @node Holiday Customizing
122 @section Customizing the Holidays
124 @vindex calendar-holidays
125 @vindex christian-holidays
126 @vindex hebrew-holidays
127 @vindex islamic-holidays
128   Emacs knows about holidays defined by entries on one of several lists.
129 You can customize these lists of holidays to your own needs, adding or
130 deleting holidays.  The lists of holidays that Emacs uses are for
131 general holidays (@code{general-holidays}), local holidays
132 (@code{local-holidays}), Christian holidays (@code{christian-holidays}),
133 Hebrew (Jewish) holidays (@code{hebrew-holidays}), Islamic (Moslem)
134 holidays (@code{islamic-holidays}), and other holidays
135 (@code{other-holidays}).
137 @vindex general-holidays
138   The general holidays are, by default, holidays common throughout the
139 United States.  To eliminate these holidays, set @code{general-holidays}
140 to @code{nil}.
142 @vindex local-holidays
143   There are no default local holidays (but sites may supply some).  You
144 can set the variable @code{local-holidays} to any list of holidays, as
145 described below.
147 @vindex all-christian-calendar-holidays
148 @vindex all-hebrew-calendar-holidays
149 @vindex all-islamic-calendar-holidays
150   By default, Emacs does not include all the holidays of the religions
151 that it knows, only those commonly found in secular calendars.  For a
152 more extensive collection of religious holidays, you can set any (or
153 all) of the variables @code{all-christian-calendar-holidays},
154 @code{all-hebrew-calendar-holidays}, or
155 @code{all-islamic-calendar-holidays} to @code{t}.  If you want to
156 eliminate the religious holidays, set any or all of the corresponding
157 variables @code{christian-holidays}, @code{hebrew-holidays}, and
158 @code{islamic-holidays} to @code{nil}.@refill
160 @vindex other-holidays
161   You can set the variable @code{other-holidays} to any list of
162 holidays.  This list, normally empty, is intended for individual use.
164 @cindex holiday forms
165   Each of the lists (@code{general-holidays}, @code{local-holidays},
166 @code{christian-holidays}, @code{hebrew-holidays},
167 @code{islamic-holidays}, and @code{other-holidays}) is a list of
168 @dfn{holiday forms}, each holiday form describing a holiday (or
169 sometimes a list of holidays).
171   Here is a table of the possible kinds of holiday form.  Day numbers
172 and month numbers count starting from 1, but ``dayname'' numbers
173 count Sunday as 0.  The element @var{string} is always the
174 name of the holiday, as a string.
176 @table @code
177 @item (holiday-fixed @var{month} @var{day} @var{string})
178 A fixed date on the Gregorian calendar.
180 @item (holiday-float @var{month} @var{dayname} @var{k} @var{string})
181 The @var{k}th @var{dayname} in @var{month} on the Gregorian calendar
182 (@var{dayname}=0 for Sunday, and so on); negative @var{k} means count back
183 from the end of the month.
185 @item (holiday-hebrew @var{month} @var{day} @var{string})
186 A fixed date on the Hebrew calendar.
188 @item (holiday-islamic @var{month} @var{day} @var{string})
189 A fixed date on the Islamic calendar.
191 @item (holiday-julian @var{month} @var{day} @var{string})
192 A fixed date on the Julian calendar.
194 @item (holiday-sexp @var{sexp} @var{string})
195 A date calculated by the Lisp expression @var{sexp}.  The expression
196 should use the variable @code{year} to compute and return the date of a
197 holiday, or @code{nil} if the holiday doesn't happen this year.  The
198 value of @var{sexp} must represent the date as a list of the form
199 @code{(@var{month} @var{day} @var{year})}.
201 @item (if @var{condition} @var{holiday-form})
202 A holiday that happens only if @var{condition} is true.
204 @item (@var{function} @r{[}@var{args}@r{]})
205 A list of dates calculated by the function @var{function}, called with
206 arguments @var{args}.
207 @end table
209   For example, suppose you want to add Bastille Day, celebrated in
210 France on July 14.  You can do this as follows:
212 @smallexample
213 (setq other-holidays '((holiday-fixed 7 14 "Bastille Day")))
214 @end smallexample
216 @noindent
217 The holiday form @code{(holiday-fixed 7 14 "Bastille Day")} specifies the
218 fourteenth day of the seventh month (July).
220   Many holidays occur on a specific day of the week, at a specific time
221 of month.  Here is a holiday form describing Hurricane Supplication Day,
222 celebrated in the Virgin Islands on the fourth Monday in August:
224 @smallexample
225 (holiday-float 8 1 4 "Hurricane Supplication Day")
226 @end smallexample
228 @noindent
229 Here the 8 specifies August, the 1 specifies Monday (Sunday is 0,
230 Tuesday is 2, and so on), and the 4 specifies the fourth occurrence in
231 the month (1 specifies the first occurrence, 2 the second occurrence,
232 @minus{}1 the last occurrence, @minus{}2 the second-to-last occurrence, and
233 so on).
235   You can specify holidays that occur on fixed days of the Hebrew,
236 Islamic, and Julian calendars too.  For example,
238 @smallexample
239 (setq other-holidays
240       '((holiday-hebrew 10 2 "Last day of Hanukkah")
241         (holiday-islamic 3 12 "Mohammed's Birthday")
242         (holiday-julian 4 2 "Jefferson's Birthday")))
243 @end smallexample
245 @noindent
246 adds the last day of Hanukkah (since the Hebrew months are numbered with
247 1 starting from Nisan), the Islamic feast celebrating Mohammed's
248 birthday (since the Islamic months are numbered from 1 starting with
249 Muharram), and Thomas Jefferson's birthday, which is 2 April 1743 on the
250 Julian calendar.
252   To include a holiday conditionally, use either Emacs Lisp's @code{if} or the
253 @code{holiday-sexp} form.  For example, American presidential elections
254 occur on the first Tuesday after the first Monday in November of years
255 divisible by 4:
257 @smallexample
258 (holiday-sexp (if (= 0 (% year 4))
259                    (calendar-gregorian-from-absolute
260                     (1+ (calendar-dayname-on-or-before
261                           1 (+ 6 (calendar-absolute-from-gregorian
262                                   (list 11 1 year))))))
263               "US Presidential Election"))
264 @end smallexample
266 @noindent
269 @smallexample
270 (if (= 0 (% displayed-year 4))
271     (fixed 11
272            (extract-calendar-day
273              (calendar-gregorian-from-absolute
274                (1+ (calendar-dayname-on-or-before
275                      1 (+ 6 (calendar-absolute-from-gregorian
276                               (list 11 1 displayed-year)))))))
277            "US Presidential Election"))
278 @end smallexample
280   Some holidays just don't fit into any of these forms because special
281 calculations are involved in their determination.  In such cases you
282 must write a Lisp function to do the calculation.  To include eclipses,
283 for example, add @code{(eclipses)} to @code{other-holidays}
284 and write an Emacs Lisp function @code{eclipses} that returns a
285 (possibly empty) list of the relevant Gregorian dates among the range
286 visible in the calendar window, with descriptive strings, like this:
288 @smallexample
289 (((6 27 1991) "Lunar Eclipse") ((7 11 1991) "Solar Eclipse") ... )
290 @end smallexample
292 @node Date Display Format
293 @section Date Display Format
294 @vindex calendar-date-display-form
296   You can customize the manner of displaying dates in the diary, in mode
297 lines, and in messages by setting @code{calendar-date-display-form}.
298 This variable holds a list of expressions that can involve the variables
299 @code{month}, @code{day}, and @code{year}, which are all numbers in
300 string form, and @code{monthname} and @code{dayname}, which are both
301 alphabetic strings.  In the American style, the default value of this
302 list is as follows:
304 @smallexample
305 ((if dayname (concat dayname ", ")) monthname " " day ", " year)
306 @end smallexample
308 @noindent
309 while in the European style this value is the default:
311 @smallexample
312 ((if dayname (concat dayname ", ")) day " " monthname " " year)
313 @end smallexample
315 @noindent
316 The ISO standard date representation is this:
318 @smallexample
319 (year "-" month "-" day)
320 @end smallexample
322 @noindent
323 This specifies a typical American format:
325 @smallexample
326 (month "/" day "/" (substring year -2))
327 @end smallexample
329 @node Time Display Format
330 @section Time Display Format
331 @vindex calendar-time-display-form
333   The calendar and diary by default display times of day in the
334 conventional American style with the hours from 1 through 12, minutes,
335 and either @samp{am} or @samp{pm}.  If you prefer the European style,
336 also known in the US as military, in which the hours go from 00 to 23,
337 you can alter the variable @code{calendar-time-display-form}.  This
338 variable is a list of expressions that can involve the variables
339 @code{12-hours}, @code{24-hours}, and @code{minutes}, which are all
340 numbers in string form, and @code{am-pm} and @code{time-zone}, which are
341 both alphabetic strings.  The default value of
342 @code{calendar-time-display-form} is as follows:
344 @smallexample
345 (12-hours ":" minutes am-pm
346           (if time-zone " (") time-zone (if time-zone ")"))
347 @end smallexample
349 @noindent
350 Here is a value that provides European style times:
352 @smallexample
353 (24-hours ":" minutes
354           (if time-zone " (") time-zone (if time-zone ")"))
355 @end smallexample
357 @node Daylight Savings
358 @section Daylight Savings Time
359 @cindex daylight savings time
361   Emacs understands the difference between standard time and daylight
362 savings time---the times given for sunrise, sunset, solstices,
363 equinoxes, and the phases of the moon take that into account.  The rules
364 for daylight savings time vary from place to place and have also varied
365 historically from year to year.  To do the job properly, Emacs needs to
366 know which rules to use.
368   Some operating systems keep track of the rules that apply to the place
369 where you are; on these systems, Emacs gets the information it needs
370 from the system automatically.  If some or all of this information is
371 missing, Emacs fills in the gaps with the rules currently used in
372 Cambridge, Massachusetts, which is the center of GNU's world.
375 @vindex calendar-daylight-savings-starts
376 @vindex calendar-daylight-savings-ends
377   If the default choice of rules is not appropriate for your location,
378 you can tell Emacs the rules to use by setting the variables
379 @code{calendar-daylight-savings-starts} and
380 @code{calendar-daylight-savings-ends}.  Their values should be Lisp
381 expressions that refer to the variable @code{year}, and evaluate to the
382 Gregorian date on which daylight savings time starts or (respectively)
383 ends, in the form of a list @code{(@var{month} @var{day} @var{year})}.
384 The values should be @code{nil} if your area does not use daylight
385 savings time.
387   Emacs uses these expressions to determine the start and end dates of
388 daylight savings time as holidays and for correcting times of day in the
389 solar and lunar calculations.
391   The values for Cambridge, Massachusetts are as follows:
393 @example
394 @group
395 (calendar-nth-named-day 1 0 4 year)
396 (calendar-nth-named-day -1 0 10 year)
397 @end group
398 @end example
400 @noindent
401 i.e., the first 0th day (Sunday) of the fourth month (April) in
402 the year specified by @code{year}, and the last Sunday of the tenth month
403 (October) of that year.  If daylight savings time were
404 changed to start on October 1, you would set
405 @code{calendar-daylight-savings-starts} to this:
407 @example
408 (list 10 1 year)
409 @end example
411   For a more complex example, suppose daylight savings time begins on
412 the first of Nisan on the Hebrew calendar.  You should set
413 @code{calendar-daylight-savings-starts} to this value:
415 @example
416 (calendar-gregorian-from-absolute
417   (calendar-absolute-from-hebrew
418     (list 1 1 (+ year 3760))))
419 @end example
421 @noindent
422 because Nisan is the first month in the Hebrew calendar and the Hebrew
423 year differs from the Gregorian year by 3760 at Nisan.
425   If there is no daylight savings time at your location, or if you want
426 all times in standard time, set @code{calendar-daylight-savings-starts}
427 and @code{calendar-daylight-savings-ends} to @code{nil}.
429 @vindex calendar-daylight-time-offset
430   The variable @code{calendar-daylight-time-offset} specifies the
431 difference between daylight savings time and standard time, measured in
432 minutes.  The value for Cambridge is 60.
434 @vindex calendar-daylight-savings-starts-time
435 @vindex calendar-daylight-savings-ends-time
436   The variable @code{calendar-daylight-savings-starts-time} and the
437 variable @code{calendar-daylight-savings-ends-time} specify the number
438 of minutes after midnight local time when the transition to and from
439 daylight savings time should occur.  For Cambridge, both variables'
440 values are 120.
442 @node Diary Customizing
443 @section Customizing the Diary
445 @vindex holidays-in-diary-buffer
446   Ordinarily, the mode line of the diary buffer window indicates any
447 holidays that fall on the date of the diary entries.  The process of
448 checking for holidays can take several seconds, so including holiday
449 information delays the display of the diary buffer noticeably.  If you'd
450 prefer to have a faster display of the diary buffer but without the
451 holiday information, set the variable @code{holidays-in-diary-buffer} to
452 @code{nil}.@refill
454 @vindex number-of-diary-entries
455   The variable @code{number-of-diary-entries} controls the number of
456 days of diary entries to be displayed at one time.  It affects the
457 initial display when @code{view-diary-entries-initially} is @code{t}, as
458 well as the command @kbd{M-x diary}.  For example, the default value is
459 1, which says to display only the current day's diary entries.  If the
460 value is 2, both the current day's and the next day's entries are
461 displayed.  The value can also be a vector of seven elements: for
462 example, if the value is @code{[0 2 2 2 2 4 1]} then no diary entries
463 appear on Sunday, the current date's and the next day's diary entries
464 appear Monday through Thursday, Friday through Monday's entries appear
465 on Friday, while on Saturday only that day's entries appear.
467 @vindex print-diary-entries-hook
468 @findex print-diary-entries
469   The variable @code{print-diary-entries-hook} is a normal hook run
470 after preparation of a temporary buffer containing just the diary
471 entries currently visible in the diary buffer.  (The other, irrelevant
472 diary entries are really absent from the temporary buffer; in the diary
473 buffer, they are merely hidden.)  The default value of this hook does
474 the printing with the command @code{lpr-buffer}.  If you want to use a
475 different command to do the printing, just change the value of this
476 hook.  Other uses might include, for example, rearranging the lines into
477 order by day and time.
479 @vindex diary-date-forms
480   You can customize the form of dates in your diary file, if neither the
481 standard American nor European styles suits your needs, by setting the
482 variable @code{diary-date-forms}.  This variable is a list of patterns
483 for recognizing a date.  Each date pattern is a list whose elements may
484 be regular expressions (@pxref{Regular Expressions}) or the symbols
485 @code{month}, @code{day}, @code{year}, @code{monthname}, and
486 @code{dayname}.  All these elements serve as patterns that match certain
487 kinds of text in the diary file.  In order for the date pattern, as a
488 whole, to match, all of its elements must match consecutively.
490   A regular expression in a date pattern matches in its usual fashion,
491 using the standard syntax table altered so that @samp{*} is a word
492 constituent.
494   The symbols @code{month}, @code{day}, @code{year}, @code{monthname},
495 and @code{dayname} match the month number, day number, year number,
496 month name, and day name of the date being considered.  The symbols that
497 match numbers allow leading zeros; those that match names allow
498 three-letter abbreviations and capitalization.  All the symbols can
499 match @samp{*}; since @samp{*} in a diary entry means ``any day'', ``any
500 month'', and so on, it should match regardless of the date being
501 considered.
503   The default value of @code{diary-date-forms} in the American style is
504 this:
506 @example
507 ((month "/" day "[^/0-9]")
508  (month "/" day "/" year "[^0-9]")
509  (monthname " *" day "[^,0-9]")
510  (monthname " *" day ", *" year "[^0-9]")
511  (dayname "\\W"))
512 @end example
514   The date patterns in the list must be @emph{mutually exclusive} and
515 must not match any portion of the diary entry itself, just the date and
516 one character of whitespace.  If, to be mutually exclusive, the pattern
517 must match a portion of the diary entry text---beyond the whitespace
518 that ends the date---then the first element of the date pattern
519 @emph{must} be @code{backup}.  This causes the date recognizer to back
520 up to the beginning of the current word of the diary entry, after
521 finishing the match.  Even if you use @code{backup}, the date pattern
522 must absolutely not match more than a portion of the first word of the
523 diary entry.  The default value of @code{diary-date-forms} in the
524 European style is this list:
526 @example
527 ((day "/" month "[^/0-9]")
528  (day "/" month "/" year "[^0-9]")
529  (backup day " *" monthname "\\W+\\<[^*0-9]")
530  (day " *" monthname " *" year "[^0-9]")
531  (dayname "\\W"))
532 @end example
534 @noindent
535 Notice the use of @code{backup} in the third pattern, because it needs
536 to match part of a word beyond the date itself to distinguish it from
537 the fourth pattern.
539 @node Hebrew/Islamic Entries
540 @section Hebrew- and Islamic-Date Diary Entries
542   Your diary file can have entries based on Hebrew or Islamic dates, as
543 well as entries based on the world-standard Gregorian calendar.
544 However, because recognition of such entries is time-consuming and most
545 people don't use them, you must explicitly enable their use.  If you
546 want the diary to recognize Hebrew-date diary entries, for example, 
547 you must do this:
549 @vindex nongregorian-diary-listing-hook
550 @vindex nongregorian-diary-marking-hook
551 @findex list-hebrew-diary-entries
552 @findex mark-hebrew-diary-entries
553 @smallexample
554 (add-hook 'nongregorian-diary-listing-hook 'list-hebrew-diary-entries)
555 (add-hook 'nongregorian-diary-marking-hook 'mark-hebrew-diary-entries)
556 @end smallexample
558 @noindent
559 If you want Islamic-date entries, do this:
561 @findex list-islamic-diary-entries
562 @findex mark-islamic-diary-entries
563 @smallexample
564 (add-hook 'nongregorian-diary-listing-hook 'list-islamic-diary-entries)
565 (add-hook 'nongregorian-diary-marking-hook 'mark-islamic-diary-entries)
566 @end smallexample
568   Hebrew- and Islamic-date diary entries have the same formats as
569 Gregorian-date diary entries, except that @samp{H} precedes a Hebrew
570 date and @samp{I} precedes an Islamic date.  Moreover, because the
571 Hebrew and Islamic month names are not uniquely specified by the first
572 three letters, you may not abbreviate them.  For example, a diary entry
573 for the Hebrew date Heshvan 25 could look like this:
575 @smallexample
576 HHeshvan 25 Happy Hebrew birthday!
577 @end smallexample
579 @noindent
580 and would appear in the diary for any date that corresponds to Heshvan 25
581 on the Hebrew calendar.  And here is an Islamic-date diary entry that matches
582 Dhu al-Qada 25:
584 @smallexample
585 IDhu al-Qada 25 Happy Islamic birthday!
586 @end smallexample
588   As with Gregorian-date diary entries, Hebrew- and Islamic-date entries
589 are nonmarking if they are preceded with an ampersand (@samp{&}).
591   Here is a table of commands used in the calendar to create diary entries
592 that match the selected date and other dates that are similar in the Hebrew
593 or Islamic calendar:
595 @table @kbd
596 @item i h d
597 Add a diary entry for the Hebrew date corresponding to the selected date
598 (@code{insert-hebrew-diary-entry}).
599 @item i h m
600 Add a diary entry for the day of the Hebrew month corresponding to the
601 selected date (@code{insert-monthly-hebrew-diary-entry}).  This diary
602 entry matches any date that has the same Hebrew day-within-month as the
603 selected date.
604 @item i h y
605 Add a diary entry for the day of the Hebrew year corresponding to the
606 selected date (@code{insert-yearly-hebrew-diary-entry}).  This diary 
607 entry matches any date which has the same Hebrew month and day-within-month
608 as the selected date.
609 @item i i d
610 Add a diary entry for the Islamic date corresponding to the selected date
611 (@code{insert-islamic-diary-entry}).
612 @item i i m
613 Add a diary entry for the day of the Islamic month corresponding to the
614 selected date (@code{insert-monthly-islamic-diary-entry}).
615 @item i i y
616 Add a diary entry for the day of the Islamic year corresponding to the
617 selected date (@code{insert-yearly-islamic-diary-entry}).
618 @end table
620 @findex insert-hebrew-diary-entry
621 @findex insert-monthly-hebrew-diary-entry
622 @findex insert-yearly-hebrew-diary-entry
623 @findex insert-islamic-diary-entry
624 @findex insert-monthly-islamic-diary-entry
625 @findex insert-yearly-islamic-diary-entry
626   These commands work much like the corresponding commands for ordinary
627 diary entries: they apply to the date that point is on in the calendar
628 window, and what they do is insert just the date portion of a diary entry
629 at the end of your diary file.  You must then insert the rest of the 
630 diary entry.
632 @node Fancy Diary Display
633 @section Fancy Diary Display
634 @vindex diary-display-hook
635 @findex simple-diary-display
637   Diary display works by preparing the diary buffer and then running the
638 hook @code{diary-display-hook}.  The default value of this hook
639 (@code{simple-diary-display}) hides the irrelevant diary entries and
640 then displays the buffer.  However, if you specify the hook as follows,
642 @cindex diary buffer
643 @findex fancy-diary-display
644 @example
645 (add-hook 'diary-display-hook 'fancy-diary-display)
646 @end example
648 @noindent
649 this enables fancy diary display.  It displays diary entries and
650 holidays by copying them into a special buffer that exists only for the
651 sake of display.  Copying to a separate buffer provides an opportunity
652 to change the displayed text to make it prettier---for example, to sort
653 the entries by the dates they apply to.
655   As with simple diary display, you can print a hard copy of the buffer
656 with @code{print-diary-entries}.  To print a hard copy of a day-by-day
657 diary for a week, position point on Sunday of that week, type
658 @kbd{7 d}, and then do @kbd{M-x print-diary-entries}.  As usual, the
659 inclusion of the holidays slows down the display slightly; you can speed
660 things up by setting the variable @code{holidays-in-diary-buffer} to
661 @code{nil}.
663 @vindex diary-list-include-blanks
664   Ordinarily, the fancy diary buffer does not show days for which there are
665 no diary entries, even if that day is a holiday.  If you want such days to be
666 shown in the fancy diary buffer, set the variable
667 @code{diary-list-include-blanks} to @code{t}.@refill
669 @cindex sorting diary entries
670   If you use the fancy diary display, you can use the normal hook
671 @code{list-diary-entries-hook} to sort each day's diary entries by their
672 time of day.  Here's how:
674 @findex sort-diary-entries
675 @example
676 (add-hook 'list-diary-entries-hook 'sort-diary-entries t)
677 @end example
679 @noindent
680 For each day, this sorts diary entries that begin with a recognizable
681 time of day according to their times.  Diary entries without times come
682 first within each day.
684   Fancy diary display also has the ability to process included diary
685 files.  This permits a group of people to share a diary file for events
686 that apply to all of them.  Lines in the diary file of this form:
688 @smallexample
689 #include "@var{filename}"
690 @end smallexample
692 @noindent
693 includes the diary entries from the file @var{filename} in the fancy
694 diary buffer.  The include mechanism is recursive, so that included files
695 can include other files, and so on; you must be careful not to have a
696 cycle of inclusions, of course.  Here is how to enable the include
697 facility:
699 @vindex list-diary-entries-hook
700 @vindex mark-diary-entries-hook
701 @findex include-other-diary-files
702 @findex mark-included-diary-files
703 @smallexample
704 (add-hook 'list-diary-entries-hook 'include-other-diary-files)
705 (add-hook 'mark-diary-entries-hook 'mark-included-diary-files)
706 @end smallexample
708 The include mechanism works only with the fancy diary display, because
709 ordinary diary display shows the entries directly from your diary file.
711 @node Sexp Diary Entries
712 @section Sexp Entries and the Fancy Diary Display
713 @cindex sexp diary entries
715   Sexp diary entries allow you to do more than just have complicated
716 conditions under which a diary entry applies.  If you use the fancy
717 diary display, sexp entries can generate the text of the entry depending
718 on the date itself.  For example, an anniversary diary entry can insert
719 the number of years since the anniversary date into the text of the
720 diary entry.  Thus the @samp{%d} in this dairy entry:
722 @findex diary-anniversary
723 @smallexample
724 %%(diary-anniversary 10 31 1948) Arthur's birthday (%d years old)
725 @end smallexample
727 @noindent
728 gets replaced by the age, so on October 31, 1990 the entry appears in
729 the fancy diary buffer like this:
731 @smallexample
732 Arthur's birthday (42 years old)
733 @end smallexample
735 @noindent
736 If the diary file instead contains this entry:
738 @smallexample
739 %%(diary-anniversary 10 31 1948) Arthur's %d%s birthday
740 @end smallexample
742 @noindent
743 the entry in the fancy diary buffer for October 31, 1990 appears like this:
745 @smallexample
746 Arthur's 42nd birthday
747 @end smallexample
749   Similarly, cyclic diary entries can interpolate the number of repetitions
750 that have occurred:
752 @findex diary-cyclic
753 @smallexample
754 %%(diary-cyclic 50 1 1 1990) Renew medication (%d%s time)
755 @end smallexample
757 @noindent
758 looks like this:
760 @smallexample
761 Renew medication (5th time)
762 @end smallexample
764 @noindent
765 in the fancy diary display on September 8, 1990.
767   There is an early reminder diary sexp that includes its entry in the
768 diary not only on the date of occurrence, but also on earlier dates.
769 For example, if you want a reminder a week before your anniversary, you
770 can use
772 @findex diary-remind
773 @smallexample
774 %%(diary-remind '(diary-anniversary 12 22 1968) 7) Ed's anniversary
775 @end smallexample
777 @noindent
778 and the fancy diary will show
779 @smallexample
780 Ed's anniversary
781 @end smallexample
782 @noindent
783 both on December 15 and on December 22.
785 @findex diary-date
786   The function @code{diary-date} applies to dates described by a month,
787 day, year combination, each of which can be an integer, a list of
788 integers, or @code{t}. The value @code{t} means all values.  For
789 example,
791 @smallexample
792 %%(diary-date '(10 11 12) 22 t) Rake leaves
793 @end smallexample
795 @noindent
796 causes the fancy diary to show
798 @smallexample
799 Rake leaves
800 @end smallexample
802 @noindent
803 on October 22, November 22, and December 22 of every year.
805 @findex diary-float
806   The function @code{diary-float} allows you to describe diary entries
807 that apply to dates like the third Friday of November, or the last
808 Tuesday in April.  The parameters are the @var{month}, @var{dayname},
809 and an index @var{n}. The entry appears on the @var{n}th @var{dayname}
810 of @var{month}, where @var{dayname}=0 means Sunday, 1 means Monday, and
811 so on.  If @var{n} is negative it counts backward from the end of
812 @var{month}.  The value of @var{month} can be a list of months, a single
813 month, or @code{t} to specify all months.  You can also use an optional
814 parameter @var{day} to specify the @var{n}th @var{dayname} of
815 @var{month} on or after/before @var{day}; the value of @var{day} defaults
816 to 1 if @var{n} is positive and to the last day of @var{month} if
817 @var{n} is negative.  For example,
819 @smallexample
820 %%(diary-float t 1 -1) Pay rent
821 @end smallexample
823 @noindent
824 causes the fancy diary to show
826 @smallexample
827 Pay rent
828 @end smallexample
830 @noindent
831 on the last Monday of every month.
833   The generality of sexp diary entries lets you specify any diary entry
834 that you can describe algorithmically.  A sexp diary entry contains an
835 expression that computes whether the entry applies to any given date.
836 If its value is non-@code{nil}, the entry applies to that date;
837 otherwise, it does not.  The expression can use the variable  @code{date}
838 to find the date being considered; its value is a list (@var{month}
839 @var{day} @var{year}) that refers to the Gregorian calendar.
841   Suppose you get paid on the 21st of the month if it is a weekday, and
842 on the Friday before if the 21st is on a weekend.  Here is how to write
843 a sexp diary entry that matches those dates:
845 @smallexample
846 &%%(let ((dayname (calendar-day-of-week date))
847          (day (car (cdr date))))
848       (or (and (= day 21) (memq dayname '(1 2 3 4 5)))
849           (and (memq day '(19 20)) (= dayname 5)))
850          ) Pay check deposited
851 @end smallexample
853   The following sexp diary entries take advantage of the ability (in the fancy
854 diary display) to concoct diary entries whose text varies based on the date:
856 @findex diary-sunrise-sunset
857 @findex diary-phases-of-moon
858 @findex diary-day-of-year
859 @findex diary-iso-date
860 @findex diary-julian-date
861 @findex diary-astro-day-number
862 @findex diary-hebrew-date
863 @findex diary-islamic-date
864 @findex diary-french-date
865 @findex diary-mayan-date
866 @table @code
867 @item %%(diary-sunrise-sunset)
868 Make a diary entry for the local times of today's sunrise and sunset.
869 @item %%(diary-phases-of-moon)
870 Make a diary entry for the phases (quarters) of the moon.
871 @item %%(diary-day-of-year)
872 Make a diary entry with today's day number in the current year and the number
873 of days remaining in the current year.
874 @item %%(diary-iso-date)
875 Make a diary entry with today's equivalent ISO commercial date.
876 @item %%(diary-julian-date)
877 Make a diary entry with today's equivalent date on the Julian calendar.
878 @item %%(diary-astro-day-number)
879 Make a diary entry with today's equivalent astronomical (Julian) day number.
880 @item %%(diary-hebrew-date)
881 Make a diary entry with today's equivalent date on the Hebrew calendar.
882 @item %%(diary-islamic-date)
883 Make a diary entry with today's equivalent date on the Islamic calendar.
884 @item %%(diary-french-date)
885 Make a diary entry with today's equivalent date on the French Revolutionary
886 calendar.
887 @item %%(diary-mayan-date)
888 Make a diary entry with today's equivalent date on the Mayan calendar.
889 @end table
891 @noindent
892 Thus including the diary entry
894 @example
895 &%%(diary-hebrew-date)
896 @end example
898 @noindent
899 causes every day's diary display to contain the equivalent date on the
900 Hebrew calendar, if you are using the fancy diary display.  (With simple
901 diary display, the line @samp{&%%(diary-hebrew-date)} appears in the
902 diary for any date, but does nothing particularly useful.)
904   These functions can be used to construct sexp diary entries based on
905 the Hebrew calendar in certain standard ways:
907 @cindex rosh hodesh
908 @findex diary-rosh-hodesh
909 @cindex parasha, weekly
910 @findex diary-parasha
911 @cindex candle lighting times
912 @findex diary-sabbath-candles
913 @cindex omer count
914 @findex diary-omer
915 @cindex yahrzeits
916 @findex diary-yahrzeit
917 @table @code
918 @item %%(diary-rosh-hodesh)
919 Make a diary entry that tells the occurrence and ritual announcement of each
920 new Hebrew month.
921 @item %%(diary-parasha)
922 Make a Saturday diary entry that tells the weekly synagogue scripture reading.
923 @item %%(diary-sabbath-candles)
924 Make a Friday diary entry that tells the @emph{local time} of Sabbath
925 candle lighting.
926 @item %%(diary-omer)
927 Make a diary entry that gives the omer count, when appropriate.
928 @item %%(diary-yahrzeit @var{month} @var{day} @var{year}) @var{name}
929 Make a diary entry marking the anniversary of a date of death.  The date
930 is the @emph{Gregorian} (civil) date of death.  The diary entry appears
931 on the proper Hebrew calendar anniversary and on the day before.  (In
932 the European style, the order of the parameters is changed to @var{day},
933 @var{month}, @var{year}.)
934 @end table
936 @node Appt Customizing
937 @section Customizing Appointment Reminders
939   You can specify exactly how Emacs reminds you of an appointment, and
940 how far in advance it begins doing so, by setting these variables:
942 @vindex appt-message-warning-time
943 @vindex appt-audible
944 @vindex appt-visible
945 @vindex appt-display-mode-line
946 @vindex appt-msg-window
947 @vindex appt-display-duration
948 @vindex appt-disp-window-function
949 @vindex appt-delete-window-function
950 @table @code
951 @item appt-message-warning-time
952 The time in minutes before an appointment that the reminder begins.  The
953 default is 10 minutes.
954 @item appt-audible
955 If this is non-@code{nil}, Emacs rings the
956 terminal bell for appointment reminders.  The default is @code{t}.
957 @item appt-visible
958 If this is non-@code{nil}, Emacs displays the appointment
959 message in the echo area.  The default is @code{t}.
960 @item appt-display-mode-line
961 If this is non-@code{nil}, Emacs displays the number of minutes
962 to the appointment on the mode line.  The default is @code{t}.
963 @item appt-msg-window
964 If this is non-@code{nil}, Emacs displays the appointment
965 message in another window.  The default is @code{t}.
966 @item appt-disp-window-function
967 This variable holds a function to use to create the other window
968 for the appointment message.
969 @item appt-delete-window-function
970 This variable holds a function to use to get rid of the appointment
971 message window, when its time is up.
972 @item appt-display-duration
973 The number of seconds to display an appointment message.  The default
974 is 5 seconds.
975 @end table