(U+9675): Use `->denotational' and `->subsumptive'.
[chise/xemacs-chise.git.1] / man / xemacs / calendar.texi
1 @node Calendar/Diary, Sorting, Reading Mail, Top
2 @section Calendar Mode and the Diary
3 @cindex calendar
4 @findex calendar
5
6   Emacs provides the functions of a desk calendar, with a diary of
7 planned or past events.  To enter the calendar, type @kbd{M-x calendar};
8 this displays a three-month calendar centered on the current month, with
9 point on the current date.  With a numeric argument, as in @kbd{C-u M-x
10 calendar}, it prompts you for the month and year to be the center of the
11 three-month calendar.  The calendar uses its own buffer, whose major
12 mode is Calendar mode.
13
14   @kbd{Button2} in the calendar brings up a menu of operations on a
15 particular date; @kbd{Buttons3} brings up a menu of commonly used
16 calendar features that are independent of any particular date.  To exit
17 the calendar, type @kbd{q}.  @xref{Calendar, Customizing the Calendar
18 and Diary,, lispref, The XEmacs Lisp Reference Manual}, for customization
19 information about the calendar and diary.
20  
21 @menu
22 * Calendar Motion::        Moving through the calendar; selecting a date.
23 * Scroll Calendar::        Bringing earlier or later months onto the screen.
24 * Mark and Region::        Remembering dates, the mark ring.
25 * General Calendar::       Exiting or recomputing the calendar.
26 * LaTeX Calendar::         Print a calendar using LaTeX.
27 * Holidays::               Displaying dates of holidays.
28 * Sunrise/Sunset::         Displaying local times of sunrise and sunset.
29 * Lunar Phases::           Displaying phases of the moon.
30 * Other Calendars::        Converting dates to other calendar systems.
31 * Diary::                  Displaying events from your diary.
32 * Calendar Customization:: Altering the behavior of the features above.
33 @end menu
34
35 @node Calendar Motion, Scroll Calendar, Calendar/Diary, Calendar/Diary
36 @subsection Movement in the Calendar
37
38 @cindex moving inside the calendar
39   Calendar mode lets you move through the calendar in logical units of
40 time such as days, weeks, months, and years.  If you move outside the
41 three months originally displayed, the calendar display ``scrolls''
42 automatically through time to make the selected date visible.  Moving to
43 a date lets you view its holidays or diary entries, or convert it to other
44 calendars; moving longer time periods is also useful simply to scroll the
45 calendar.
46
47 @menu
48 * Calendar Unit Motion::       Moving by days, weeks, months, and years.
49 * Move to Beginning or End::   Moving to start/end of weeks, months, and years.
50 * Specified Dates::            Moving to the current date or another 
51                                specific date.
52 @end menu
53
54 @node Calendar Unit Motion, Move to Beginning or End, Calendar Motion, Calendar Motion
55 @subsubsection Motion by Integral Days, Weeks, Months, Years
56
57   The commands for movement in the calendar buffer parallel the
58 commands for movement in text.  You can move forward and backward by
59 days, weeks, months, and years.
60
61 @table @kbd
62 @item C-f
63 Move point one day forward (@code{calendar-forward-day}).
64 @item C-b
65 Move point one day backward (@code{calendar-backward-day}).
66 @item C-n
67 Move point one week forward (@code{calendar-forward-week}).
68 @item C-p
69 Move point one week backward (@code{calendar-backward-week}).
70 @item M-@}
71 Move point one month forward (@code{calendar-forward-month}).
72 @item M-@{
73 Move point one month backward (@code{calendar-backward-month}).
74 @item C-x ]
75 Move point one year forward (@code{calendar-forward-year}).
76 @item C-x [
77 Move point one year backward (@code{calendar-backward-year}).
78 @end table
79
80 @kindex C-f @r{(Calendar mode)}
81 @findex calendar-forward-day
82 @kindex C-b @r{(Calendar mode)}
83 @findex calendar-backward-day
84 @kindex C-n @r{(Calendar mode)}
85 @findex calendar-forward-week
86 @kindex C-p @r{(Calendar mode)}
87 @findex calendar-backward-week
88   The day and week commands are natural analogues of the usual Emacs
89 commands for moving by characters and by lines.  Just as @kbd{C-n}
90 usually moves to the same column in the following line, in Calendar
91 mode it moves to the same day in the following week.  And @kbd{C-p}
92 moves to the same day in the previous week.
93
94   The arrow keys are equivalent to @kbd{C-f}, @kbd{C-b}, @kbd{C-n} and
95 @kbd{C-p}, just as they normally are in other modes.
96
97 @kindex M-@} @r{(Calendar mode)}
98 @findex calendar-forward-month
99 @kindex M-@{ @r{(Calendar mode)}
100 @findex calendar-backward-month
101 @kindex C-x ] @r{(Calendar mode)}
102 @findex calendar-forward-year
103 @kindex C-x [ @r{(Calendar mode)}
104 @findex calendar-forward-year
105   The commands for motion by months and years work like those for
106 weeks, but move a larger distance.  The month commands @kbd{M-@}} and
107 @kbd{M-@{} move forward or backward by an entire month's time.  The
108 year commands @kbd{C-x ]} and @w{@kbd{C-x [}} move forward or backward a
109 whole year.
110
111   The easiest way to remember these commands is to consider months and
112 years analogous to paragraphs and pages of text, respectively.  But the
113 commands themselves are not quite analogous.  The ordinary Emacs paragraph
114 commands move to the beginning or end of a paragraph, whereas these month
115 and year commands move by an entire month or an entire year, which usually
116 involves skipping across the end of a month or year.
117
118   All these commands accept a numeric argument as a repeat count.
119 For convenience, the digit keys and the minus sign specify numeric
120 arguments in Calendar mode even without the Meta modifier.  For example,
121 @kbd{100 C-f} moves point 100 days forward from its present location.
122
123 @node Move to Beginning or End, Specified Dates, Calendar Unit Motion, Calendar Motion
124 @subsubsection Beginning or End of Week, Month or Year
125
126   A week (or month, or year) is not just a quantity of days; we think of
127 weeks (months, years) as starting on particular dates.  So Calendar mode
128 provides commands to move to the beginning or end of a week, month or
129 year:
130  
131 @table @kbd
132 @kindex C-a @r{(Calendar mode)}
133 @findex calendar-beginning-of-week
134 @item C-a
135 Move point to start of week (@code{calendar-beginning-of-week}).
136 @kindex C-e @r{(Calendar mode)}
137 @findex calendar-end-of-week
138 @item C-e
139 Move point to end of week (@code{calendar-end-of-week}).
140 @kindex M-a @r{(Calendar mode)}
141 @findex calendar-beginning-of-month
142 @item M-a
143 Move point to start of month (@code{calendar-beginning-of-month}).
144 @kindex M-e @r{(Calendar mode)}
145 @findex calendar-end-of-month
146 @item M-e
147 Move point to end of month (@code{calendar-end-of-month}).
148 @kindex M-< @r{(Calendar mode)}
149 @findex calendar-beginning-of-year
150 @item M-<
151 Move point to start of year (@code{calendar-beginning-of-year}).
152 @kindex M-> @r{(Calendar mode)}
153 @findex calendar-end-of-year
154 @item M->
155 Move point to end of year (@code{calendar-end-of-year}).
156 @end table
157
158   These commands also take numeric arguments as repeat counts, with the
159 repeat count indicating how many weeks, months, or years to move
160 backward or forward.
161
162 @vindex calendar-week-start-day
163 @cindex weeks, which day they start on
164 @cindex calendar, first day of week
165   By default, weeks begin on Sunday.  To make them begin on Monday
166 instead, set the variable @code{calendar-week-start-day} to 1.
167
168 @node Specified Dates,,Move to Beginning or End, Calendar Motion
169 @subsubsection Particular Dates
170
171   Calendar mode provides commands for moving to a particular date
172 specified in various ways.
173
174 @table @kbd
175 @item g d
176 Move point to specified date (@code{calendar-goto-date}).
177 @item o
178 Center calendar around specified month (@code{calendar-other-month}).
179 @item .
180 Move point to today's date (@code{calendar-goto-today}).
181 @end table
182
183 @kindex g d @r{(Calendar mode)}
184 @findex calendar-goto-date
185   @kbd{g d} (@code{calendar-goto-date}) prompts for a year, a month, and a day
186 of the month, and then moves to that date.  Because the calendar includes all
187 dates from the beginning of the current era, you must type the year in its
188 entirety; that is, type @samp{1990}, not @samp{90}.
189
190 @kindex o @r{(Calendar mode)}
191 @findex calendar-other-month
192   @kbd{o} (@code{calendar-other-month}) prompts for a month and year,
193 then centers the three-month calendar around that month.
194
195 @kindex . @r{(Calendar mode)}
196 @findex calendar-goto-today
197   You can return to today's date with @kbd{.}@:
198 (@code{calendar-goto-today}).
199
200 @node Scroll Calendar, Mark and Region, Calendar Motion, Calendar/Diary
201 @subsection Scrolling the Calendar through Time
202
203 @cindex scrolling in the calendar
204   The calendar display scrolls automatically through time when you move out
205 of the visible portion.  You can also scroll it manually.  Imagine that the
206 calendar window contains a long strip of paper with the months on it.
207 Scrolling it means moving the strip so that new months become visible in
208 the window.
209
210 @table @kbd
211 @item C-x <
212 Scroll calendar one month forward (@code{scroll-calendar-left}).
213 @item C-x >
214 Scroll calendar one month backward (@code{scroll-calendar-right}).
215 @item C-v
216 @itemx @key{NEXT}
217 Scroll calendar three months forward
218 (@code{scroll-calendar-left-three-months}).
219 @item M-v
220 @itemx @key{PRIOR}
221 Scroll calendar three months backward
222 (@code{scroll-calendar-right-three-months}).
223 @end table
224
225 @kindex C-x < @r{(Calendar mode)}
226 @findex scroll-calendar-left
227 @kindex C-x > @r{(Calendar mode)}
228 @findex scroll-calendar-right
229   The most basic calendar scroll commands scroll by one month at a
230 time.  This means that there are two months of overlap between the
231 display before the command and the display after.  @kbd{C-x <} scrolls
232 the calendar contents one month to the left; that is, it moves the
233 display forward in time.  @kbd{C-x >} scrolls the contents to the
234 right, which moves backwards in time.
235
236 @kindex C-v @r{(Calendar mode)}
237 @findex scroll-calendar-left-three-months
238 @kindex M-v @r{(Calendar mode)}
239 @findex scroll-calendar-right-three-months
240   The commands @kbd{C-v} and @kbd{M-v} scroll the calendar by an entire
241 ``screenful''---three months---in analogy with the usual meaning of
242 these commands.  @kbd{C-v} makes later dates visible and @kbd{M-v} makes
243 earlier dates visible.  These commands take a numeric argument as a
244 repeat count; in particular, since @kbd{C-u} multiplies the next command
245 by four, typing @kbd{C-u C-v} scrolls the calendar forward by a year and
246 typing @kbd{C-u M-v} scrolls the calendar backward by a year.
247
248   The function keys @key{NEXT} and @key{PRIOR} are equivalent to
249 @kbd{C-v} and @kbd{M-v}, just as they are in other modes.
250
251
252 @node Mark and Region, General Calendar, Scroll Calendar, Calendar/Diary
253 @subsection The Mark and the Region
254
255   The concept of the mark applies to the calendar just as to any other
256 buffer, but it marks a @emph{date}, not a @emph{position} in the buffer.
257 The region consists of the days between the mark and point (including
258 the starting and stopping dates).
259
260 @table @kbd
261 @item C-SPC
262 Set the mark to today's date (@code{calendar-set-mark}).
263 @item C-@@
264 The same.
265 @item C-x C-x
266 Interchange mark and point (@code{calendar-exchange-point-and-mark}).
267 @item M-=
268 Display the number of days in the current region
269 (@code{calendar-count-days-region}).
270 @end table
271
272 @kindex C-@@ @r{(Calendar mode)}
273 @kindex C-SPC @r{(Calendar mode)}
274 @findex calendar-set-mark
275 @kindex C-x C-x @r{(Calendar mode)}
276 @findex calendar-exchange-point-and-mark
277   You set the mark in the calendar, as in any other buffer, by using @kbd{C-@@}
278 or @kbd{C-SPC} (@code{calendar-set-mark}).  You return to the marked date
279 with the command @kbd{C-x C-x} (@code{calendar-exchange-point-and-mark})
280 which puts the mark where point was and point where mark was.  The calendar
281 is scrolled as necessary, if the marked date was not visible on the
282 screen.  This does not change the extent of the region.
283
284 @kindex M-= @r{(Calendar mode)}
285 @findex calendar-count-days-region
286   To determine the number of days in the region, type @kbd{M-=}
287 (@code{calendar-count-days-region}).  The numbers of days printed is
288 @emph{inclusive}; that is, it includes the days specified by mark and
289 point.
290
291 @cindex mark ring
292   The main use of the mark in the calendar is to remember dates that you may
293 want to go back to.  To make this feature more useful, the mark ring
294 (@pxref{Mark Ring}) operates exactly as in other buffers:  Emacs remembers
295 16 previous locations of the mark.  To return to a marked date, type @kbd{C-u
296 C-SPC} (or @kbd{C-u C-@@}); this is the command @code{calendar-set-mark} given
297 a numeric argument.  It moves point to where the mark was, restores the mark
298 from the ring of former marks, and stores the previous point at the end of
299 the mark ring.  So, repeated use of this command moves point through all
300 the old marks on the ring, one by one.
301
302 @node General Calendar, LaTeX Calendar, Mark and Region, Calendar/Diary
303 @subsection Miscellaneous Calendar Commands
304
305 @table @kbd
306 @item p d
307 Display day-in-year (@code{calendar-print-day-of-year}).
308 @item ?
309 Briefly describe calendar commands (@code{describe-calendar-mode}).
310 @item C-c C-l
311 Regenerate the calendar window (@code{redraw-calendar}).
312 @item SPC
313 Scroll the next window (@code{scroll-other-window}).
314 @item q
315 Exit from calendar (@code{exit-calendar}).
316 @end table
317
318 @kindex p d @r{(Calendar mode)}
319 @cindex day of year
320 @findex calendar-print-day-of-year
321   If you want to know how many days have elapsed since the start of
322 the year, or the number of days remaining in the year, type the @kbd{p d}
323 command (@code{calendar-print-day-of-year}).  This displays both
324 of those numbers in the echo area.
325
326 @kindex ? @r{(Calendar mode)}
327 @findex describe-calendar-mode
328   To display a brief description of the calendar commands, type @kbd{?}
329 (@code{describe-calendar-mode}).  For a fuller description, type @kbd{C-h m}.
330
331 @kindex SPC @r{(Calendar mode)}
332 @findex scroll-other-window
333   You can use @kbd{SPC} (@code{scroll-other-window}) to scroll the other
334 window.  This is handy when you display a list of holidays or diary entries
335 in another window.
336
337 @kindex C-c C-l @r{(Calendar mode)}
338 @findex redraw-calendar
339   If the calendar window text gets corrupted, type @kbd{C-c C-l}
340 (@code{redraw-calendar}) to redraw it.  (This can only happen if you use
341 non-Calendar-mode editing commands.)
342
343 @kindex SPC @r{(Calendar mode)}
344   In Calendar mode, you can use @kbd{SPC} (@code{scroll-other-window})
345 to scroll the other window.  This is handy when you display a list of
346 holidays or diary entries in another window.
347
348 @kindex q @r{(Calendar mode)}
349 @findex exit-calendar
350   To exit from the calendar, type @kbd{q} (@code{exit-calendar}).  This
351 buries all buffers related to the calendar, selecting other buffers.
352 (If a frame contains a dedicated calendar window, exiting from the
353 calendar iconifies that frame.)
354
355 @node LaTeX Calendar, Holidays, General Calendar, Calendar/Diary
356 @section LaTeX Calendar
357 @cindex calendar and La@TeX{}
358
359    The Calendar La@TeX{} commands produce a buffer of La@TeX{} code that
360 prints as a calendar.  Depending on the command you use, the printed
361 calendar covers the day, week, month or year that point is in.
362
363 @kindex t @r{(Calendar mode)}
364 @table @kbd
365 @item t m
366 Generate a one-month calendar (@code{cal-tex-cursor-month}).
367 @item t M
368 Generate a sideways-printing one-month calendar
369 (@code{cal-tex-cursor-month-landscape}).
370 @item t d
371 Generate a one-day calendar
372 (@code{cal-tex-cursor-day}).
373 @item t w 1
374 Generate a one-page calendar for one week
375 (@code{cal-tex-cursor-week}).
376 @item t w 2
377 Generate a two-page calendar for one week
378 (@code{cal-tex-cursor-week2}).
379 @item t w 3
380 Generate an ISO-style calendar for one week
381 (@code{cal-tex-cursor-week-iso}).
382 @item t w 4
383 Generate a calendar for one Monday-starting week
384 (@code{cal-tex-cursor-week-monday}).
385 @item t f w
386 Generate a Filofax-style two-weeks-at-a-glance calendar
387 (@code{cal-tex-cursor-filofax-2week}).
388 @item t f W
389 Generate a Filofax-style one-week-at-a-glance calendar
390 (@code{cal-tex-cursor-filofax-week}).
391 @item t y
392 Generate a calendar for one year
393 (@code{cal-tex-cursor-year}).
394 @item t Y
395 Generate a sideways-printing calendar for one year
396 (@code{cal-tex-cursor-year-landscape}).
397 @item t f y
398 Generate a Filofax-style calendar for one year
399 (@code{cal-tex-cursor-filofax-year}).
400 @end table
401
402   Some of these commands print the calendar sideways (in ``landscape
403 mode''), so it can be wider than it is long.  Some of them use Filofax
404 paper size (3.75in x 6.75in).  All of these commands accept a prefix
405 argument which specifies how many days, weeks, months or years to print
406 (starting always with the selected one).
407
408   If the variable @code{cal-tex-holidays} is non-@code{nil} (the
409 default), then the printed calendars show the holidays in
410 @code{calendar-holidays}.  If the variable @code{cal-tex-diary} is
411 non-@code{nil} (the default is @code{nil}), diary entries are included
412 also (in weekly and monthly calendars only).
413
414 @node Holidays, Sunrise/Sunset, LaTeX Calendar, Calendar/Diary
415 @subsection Holidays
416 @cindex holidays
417
418   The Emacs calendar knows about all major and many minor holidays,
419 and can display them.
420
421 @table @kbd
422 @item h
423 Display holidays for the selected date
424 (@code{calendar-cursor-holidays}).
425 @item Button2 Holidays
426 Display any holidays for the date you click on.
427 @item x
428 Mark holidays in the calendar window (@code{mark-calendar-holidays}).
429 @item u
430 Unmark calendar window (@code{calendar-unmark}).
431 @item a
432 List all holidays for the displayed three months in another window
433 (@code{list-calendar-holidays}).
434 @item M-x holidays
435 List all holidays for three months around today's date in another
436 window.
437 @item M-x list-holidays
438 List holidays in another window for a specified range of years.
439 @end table
440
441 @kindex h @r{(Calendar mode)}
442 @findex calendar-cursor-holidays
443   To see if any holidays fall on a given date, position point on that
444 date in the calendar window and use the @kbd{h} command.  Alternatively,
445 click on that date with @kbd{Button2} and then choose @kbd{Holidays}
446 from the menu that appears.  Either way, this displays the holidays for
447 that date, in the echo area if they fit there, otherwise in a separate
448 window.
449
450 @kindex x @r{(Calendar mode)}
451 @findex mark-calendar-holidays
452 @kindex u @r{(Calendar mode)}
453 @findex calendar-unmark
454   To view the distribution of holidays for all the dates shown in the
455 calendar, use the @kbd{x} command.  This displays the dates that are
456 holidays in a different face (or places a @samp{*} after these dates, if 
457 display with multiple faces is not available). The command applies both
458 to the currently visible months and to other months that subsequently
459 become visible by scrolling.  To turn marking off and erase the current
460 marks, type @kbd{u}, which also erases any diary marks (@pxref{Diary}).
461
462 @kindex a @r{(Calendar mode)}
463 @findex list-calendar-holidays
464   To get even more detailed information, use the @kbd{a} command, which
465 displays a separate buffer containing a list of all holidays in the
466 current three-month range.  You can use @key{SPC} in the calendar window
467 to scroll that list.
468
469 @findex holidays
470   The command @kbd{M-x holidays} displays the list of holidays for the
471 current month and the preceding and succeeding months; this works even
472 if you don't have a calendar window.  If you want the list of holidays
473 centered around a different month, use @kbd{C-u M-x holidays}, which
474 prompts for the month and year.
475
476   The holidays known to Emacs include United States holidays and the
477 major Christian, Jewish, and Islamic holidays; also the solstices and
478 equinoxes.
479
480 @findex list-holidays
481    The command @kbd{M-x list-holidays} displays the list of holidays for
482 a range of years.  This function asks you for the starting and stopping
483 years, and allows you to choose all the holidays or one of several
484 categories of holidays.  You can use this command even if you don't have
485 a calendar window.
486
487   The dates used by Emacs for holidays are based on @emph{current
488 practice}, not historical fact.  Historically, for instance, the start
489 of daylight savings time and even its existence have varied from year to
490 year, but present United States law mandates that daylight savings time
491 begins on the first Sunday in April.  When the daylight savings rules
492 are set up for the United States, Emacs always uses the present
493 definition, even though it is wrong for some prior years.
494
495 @node Sunrise/Sunset, Lunar Phases, Holidays, Calendar/Diary
496 @subsection Times of Sunrise and Sunset
497 @cindex sunrise and sunset
498
499   Special calendar commands can tell you, to within a minute or two, the
500 times of sunrise and sunset for any date.
501
502 @table @kbd
503 @item S
504 Display times of sunrise and sunset for the selected date
505 (@code{calendar-sunrise-sunset}).
506 @item Button2 Sunrise/Sunset
507 Display times of sunrise and sunset for the date you click on.
508 @item M-x sunrise-sunset
509 Display times of sunrise and sunset for today's date.
510 @item C-u M-x sunrise-sunset
511 Display times of sunrise and sunset for a specified date.
512 @end table
513
514 @kindex S @r{(Calendar mode)}
515 @findex calendar-sunrise-sunset
516 @findex sunrise-sunset
517   Within the calendar, to display the @emph{local times} of sunrise and
518 sunset in the echo area, move point to the date you want, and type
519 @kbd{S}.  Alternatively, click @kbd{Button2} on the date, then choose
520 @kbd{Sunrise/Sunset} from the menu that appears.  The command @kbd{M-x
521 sunrise-sunset} is available outside the calendar to display this
522 information for today's date or a specified date.  To specify a date
523 other than today, use @kbd{C-u M-x sunrise-sunset}, which prompts for
524 the year, month, and day.
525
526   You can display the times of sunrise and sunset for any location and
527 any date with @kbd{C-u C-u M-x sunrise-sunset}.  This asks you for a
528 longitude, latitude, number of minutes difference from Coordinated
529 Universal Time, and date, and then tells you the times of sunrise and
530 sunset for that location on that date.
531
532   Because the times of sunrise and sunset depend on the location on
533 earth, you need to tell Emacs your latitude, longitude, and location
534 name before using these commands.  Here is an example of what to set:
535
536 @vindex calendar-location-name
537 @vindex calendar-longitude
538 @vindex calendar-latitude
539 @example
540 (setq calendar-latitude 40.1)
541 (setq calendar-longitude -88.2)
542 (setq calendar-location-name "Urbana, IL")
543 @end example
544
545 @noindent
546 Use one decimal place in the values of @code{calendar-latitude} and
547 @code{calendar-longitude}.
548
549   Your time zone also affects the local time of sunrise and sunset.
550 Emacs usually gets time zone information from the operating system, but
551 if these values are not what you want (or if the operating system does
552 not supply them), you must set them yourself.  Here is an example:
553
554 @vindex calendar-time-zone
555 @vindex calendar-standard-time-zone-name
556 @vindex calendar-daylight-time-zone-name
557 @example
558 (setq calendar-time-zone -360)
559 (setq calendar-standard-time-zone-name "CST")
560 (setq calendar-daylight-time-zone-name "CDT")
561 @end example
562
563 @noindent
564 The value of @code{calendar-time-zone} is the number of minutes
565 difference between your local standard time and Coordinated Universal
566 Time (Greenwich time).  The values of
567 @code{calendar-standard-time-zone-name} and
568 @code{calendar-daylight-time-zone-name} are the abbreviations used in
569 your time zone.  Emacs displays the times of sunrise and sunset
570 @emph{corrected for daylight savings time}.  @xref{Daylight Savings},
571 for how daylight savings time is determined.
572
573   As a user, you might find it convenient to set the calendar location
574 variables for your usual physical location in your init file.  And when
575 you install Emacs on a machine, you can create a @file{default.el} file
576 which sets them properly for the typical location of most users of that
577 machine.  @xref{Init File}.
578
579 @node Lunar Phases, Other Calendars, Sunrise/Sunset, Calendar/Diary
580 @subsection Phases of the Moon
581 @cindex phases of the moon
582 @cindex moon, phases of
583
584   These calendar commands display the dates and times of the phases of
585 the moon (new moon, first quarter, full moon, last quarter).  This
586 feature is useful for debugging problems that ``depend on the phase of
587 the moon.''
588
589 @table @kbd
590 @item M
591 Display the dates and times for all the quarters of the moon for the
592 three-month period shown (@code{calendar-phases-of-moon}).
593 @item M-x phases-of-moon
594 Display dates and times of the quarters of the moon for three months around
595 today's date.
596 @end table
597
598 @kindex M @r{(Calendar mode)}
599 @findex calendar-phases-of-moon
600   Within the calendar, use the @kbd{M} command to display a separate
601 buffer of the phases of the moon for the current three-month range.  The
602 dates and times listed are accurate to within a few minutes.
603
604 @findex phases-of-moon
605   Outside the calendar, use the command @kbd{M-x phases-of-moon} to
606 display the list of the phases of the moon for the current month and the
607 preceding and succeeding months.  For information about a different
608 month, use @kbd{C-u M-x phases-of-moon}, which prompts for the month and
609 year.
610  
611   The dates and times given for the phases of the moon are given in
612 local time (corrected for daylight savings, when appropriate); but if
613 the variable @code{calendar-time-zone} is void, Coordinated Universal
614 Time (the Greenwich time zone) is used.  @xref{Daylight Savings}.
615
616 @node Other Calendars, Calendar Systems, Lunar Phases, Calendar/Diary
617 @subsection  Conversion To and From Other Calendars
618
619 @cindex Gregorian calendar
620   The Emacs calendar displayed is @emph{always} the Gregorian calendar,
621 sometimes called the ``new style'' calendar, which is used in most of
622 the world today.  However, this calendar did not exist before the
623 sixteenth century and was not widely used before the eighteenth century;
624 it did not fully displace the Julian calendar and gain universal
625 acceptance until the early twentieth century.  The Emacs calendar can
626 display any month since January, year 1 of the current era, but the
627 calendar displayed is the Gregorian, even for a date at which the
628 Gregorian calendar did not exist.
629
630   While Emacs cannot display other calendars, it can convert dates to
631 and from several other calendars.
632
633 @menu
634 * Calendar Systems::      The calendars Emacs understands
635                             (aside from Gregorian).
636 * To Other Calendar::     Converting the selected date to various calendars.
637 * From Other Calendar::   Moving to a date specified in another calendar.
638 * Mayan Calendar::        Moving to a date specified in a Mayan calendar.
639 @end menu
640
641   If you are interested in these calendars, you can convert dates one at a
642 time.  Put point on the desired date of the Gregorian calendar and press the
643 appropriate keys.  The @kbd{p} is a mnemonic for ``print'' since Emacs
644 ``prints' the equivalent date in the echo area.
645 @node Calendar Systems, To Other Calendar, Other Calendars, Other Calendars
646 @section Supported Calendar Systems
647
648 @cindex ISO commercial calendar
649   The ISO commercial calendar is used largely in Europe.
650
651 @cindex Julian calendar
652   The Julian calendar, named after Julius Caesar, was the one used in Europe
653 throughout medieval times, and in many countries up until the nineteenth
654 century.
655
656 @cindex Julian day numbers
657 @cindex astronomical day numbers
658   Astronomers use a simple counting of days elapsed since noon, Monday,
659 January 1, 4713 B.C. on the Julian calendar.  The number of days elapsed
660 is called the @emph{Julian day number} or the @emph{Astronomical day number}.
661
662 @cindex Hebrew calendar
663   The Hebrew calendar is used by tradition in the Jewish religion.  The
664 Emacs calendar program uses the Hebrew calendar to determine the dates
665 of Jewish holidays.  Hebrew calendar dates begin and end at sunset.
666
667 @cindex Islamic calendar
668   The Islamic calendar is used in many predominantly Islamic countries.
669 Emacs uses it to determine the dates of Islamic holidays.  There is no
670 universal agreement in the Islamic world about the calendar; Emacs uses
671 a widely accepted version, but the precise dates of Islamic holidays
672 often depend on proclamation by religious authorities, not on
673 calculations.  As a consequence, the actual dates of observance can vary
674 slightly from the dates computed by Emacs.  Islamic calendar dates begin
675 and end at sunset.
676
677 @cindex French Revolutionary calendar
678   The French Revolutionary calendar was created by the Jacobins after the 1789
679 revolution, to represent a more secular and nature-based view of the annual
680 cycle, and to install a 10-day week in a rationalization measure similar to
681 the metric system.  The French government officially abandoned this
682 calendar at the end of 1805.
683
684 @cindex Mayan calendar
685   The Maya of Central America used three separate, overlapping calendar
686 systems, the @emph{long count}, the @emph{tzolkin}, and the @emph{haab}.
687 Emacs knows about all three of these calendars.  Experts dispute the
688 exact correlation between the Mayan calendar and our calendar; Emacs uses the
689 Goodman-Martinez-Thompson correlation in its calculations.
690
691 @cindex Coptic calendar
692 @cindex Ethiopic calendar
693   The Copts use a calendar based on the ancient Egyptian solar calendar.
694 Their calendar consists of twelve 30-day months followed by an extra
695 five-day period.  Once every fourth year they add a leap day to this
696 extra period to make it six days.  The Ethiopic calendar is identical in
697 structure, but has different year numbers and month names.
698
699 @cindex Persian calendar
700   The Persians use a solar calendar based on a design of Omar Khayyam.
701 Their calendar consists of twelve months of which the first six have 31
702 days, the next five have 30 days, and the last has 29 in ordinary years
703 and 30 in leap years.  Leap years occur in a complicated pattern every
704 four or five years.
705
706 @cindex Chinese calendar
707   The Chinese calendar is a complicated system of lunar months arranged
708 into solar years.  The years go in cycles of sixty, each year containing
709 either twelve months in an ordinary year or thirteen months in a leap
710 year; each month has either 29 or 30 days.  Years, ordinary months, and
711 days are named by combining one of ten ``celestial stems'' with one of
712 twelve ``terrestrial branches'' for a total of sixty names that are
713 repeated in a cycle of sixty.
714
715 @node To Other Calendar, From Other Calendar, Calendar Systems, Other Calendars
716 @section Converting To Other Calendars
717
718   The following commands describe the selected date (the date at point)
719 in various other calendar systems:
720
721 @table @kbd
722 @item Button2  Other Calendars
723 Display the date that you click on, expressed in various other calendars.
724 @kindex p @r{(Calendar mode)}
725 @findex calendar-print-iso-date
726 @item p c
727 Display ISO commercial calendar equivalent for selected day
728 (@code{calendar-print-iso-date}).
729 @findex calendar-print-julian-date
730 @item p j
731 Display Julian date for selected day (@code{calendar-print-julian-date}).
732 @findex calendar-print-astro-day-number
733 @item p a
734 Display astronomical (Julian) day number for selected day
735 (@code{calendar-print-astro-day-number}).
736 @findex calendar-print-hebrew-date
737 @item p h
738 Display Hebrew date for selected day (@code{calendar-print-hebrew-date}).
739 @findex calendar-print-islamic-date
740 @item p i
741 Display Islamic date for selected day (@code{calendar-print-islamic-date}).
742 @findex calendar-print-french-date
743 @item p f
744 Display French Revolutionary date for selected day
745 (@code{calendar-print-french-date}).
746 @findex calendar-print-chinese-date
747 @item p C
748 Display Chinese date for selected day
749 (@code{calendar-print-chinese-date}).
750 @findex calendar-print-coptic-date
751 @item p k
752 Display Coptic date for selected day
753 (@code{calendar-print-coptic-date}).
754 @findex calendar-print-ethiopic-date
755 @item p e
756 Display Ethiopic date for selected day
757 (@code{calendar-print-ethiopic-date}).
758 @findex calendar-print-persian-date
759 @item p p
760 Display Persian date for selected day
761 (@code{calendar-print-persian-date}).
762 @findex calendar-print-mayan-date
763 @item p m
764 Display Mayan date for selected day (@code{calendar-print-mayan-date}).
765 @end table
766
767   If you are using X, the easiest way to translate a date into other
768 calendars is to click on it with @kbd{Button2}, then choose @kbd{Other
769 Calendars} from the menu that appears.  This displays the equivalent
770 forms of the date in all the calendars Emacs understands, in the form of
771 a menu.  (Choosing an alternative from this menu doesn't actually do
772 anything---the menu is used only for display.)
773
774   Put point on the desired date of the Gregorian calendar, then type the
775 appropriate keys.  The @kbd{p} is a mnemonic for ``print'' since Emacs
776 ``prints'' the equivalent date in the echo area.
777
778 @node From Other Calendar, Mayan Calendar, To Other Calendar, Other Calendars
779 @section Converting From Other Calendars
780
781   You can use the other supported calendars to specify a date to move
782 to.  This section describes the commands for doing this using calendars
783 other than Mayan; for the Mayan calendar, see the following section.
784
785 @kindex g @var{char} @r{(Calendar mode)}
786 @findex calendar-goto-iso-date
787 @findex calendar-goto-julian-date
788 @findex calendar-goto-astro-day-number
789 @findex calendar-goto-hebrew-date
790 @findex calendar-goto-islamic-date
791 @findex calendar-goto-french-date
792 @findex calendar-goto-chinese-date
793 @findex calendar-goto-persian-date
794 @findex calendar-goto-coptic-date
795 @findex calendar-goto-ethiopic-date
796 @table @kbd
797 @item g c
798 Move to a date specified in the ISO commercial calendar
799 (@code{calendar-goto-iso-date}).
800 @item g j
801 Move to a date specified in the Julian calendar
802 (@code{calendar-goto-julian-date}).
803 @item g a
804 Move to a date specified in astronomical (Julian) day number
805 (@code{calendar-goto-astro-day-number}).
806 @item g h
807 Move to a date specified in the Hebrew calendar
808 (@code{calendar-goto-hebrew-date}).
809 @item g i
810 Move to a date specified in the Islamic calendar
811 (@code{calendar-goto-islamic-date}).
812 @item g f
813 Move to a date specified in the French Revolutionary calendar
814 (@code{calendar-goto-french-date}).
815 @item g C
816 Move to a date specified in the Chinese calendar
817 (@code{calendar-goto-chinese-date}).
818 @item g p
819 Move to a date specified in the Persian calendar
820 (@code{calendar-goto-persian-date}).
821 @item g k
822 Move to a date specified in the Coptic calendar
823 (@code{calendar-goto-coptic-date}).
824 @item g e
825 Move to a date specified in the Ethiopic calendar
826 (@code{calendar-goto-ethiopic-date}).
827 @end table
828
829   These commands ask you for a date on the other calendar, move point to
830 the Gregorian calendar date equivalent to that date, and display the
831 other calendar's date in the echo area.  Emacs uses strict completion
832 (@pxref{Completion}) whenever it asks you to type a month name, so you
833 don't have to worry about the spelling of Hebrew, Islamic, or French names.
834
835 @findex list-yahrzeit-dates
836 @cindex yahrzeits
837   One common question concerning the Hebrew calendar is the computation
838 of the anniversary of a date of death, called a ``yahrzeit.''  The Emacs
839 calendar includes a facility for such calculations.  If you are in the
840 calendar, the command @kbd{M-x list-yahrzeit-dates} asks you for a
841 range of years and then displays a list of the yahrzeit dates for those
842 years for the date given by point.  If you are not in the calendar,
843 this command first asks you for the date of death and the range of
844 years, and then displays the list of yahrzeit dates.
845
846 @node Mayan Calendar, Diary ,From Other Calendar ,Other Calendars
847 @subsection Converting from the Mayan Calendar
848
849   Here are the commands to select dates based on the Mayan calendar:
850
851 @table @kbd
852 @item g m l
853 Move to a date specified by the long count calendar
854 (@code{calendar-goto-mayan-long-count-date}).
855 @item g m n t
856 Move to the next occurrence of a place in the
857 tzolkin calendar (@code{calendar-next-tzolkin-date}).
858 @item g m p t
859 Move to the previous occurrence of a place in the
860 tzolkin calendar (@code{calendar-previous-tzolkin-date}).
861 @item g m n h
862 Move to the next occurrence of a place in the
863 haab calendar (@code{calendar-next-haab-date}).
864 @item g m p h
865 Move to the previous occurrence of a place in the
866 haab calendar (@code{calendar-previous-haab-date}).
867 @item g m n c
868 Move to the next occurrence of a place in the
869 calendar round (@code{calendar-next-calendar-round-date}).
870 @item g m p c
871 Move to the previous occurrence of a place in the
872 calendar round (@code{calendar-previous-calendar-round-date}).
873 @end table
874
875 @cindex Mayan long count
876   To understand these commands, you need to understand the Mayan calendars.
877 The @dfn{long count} is a counting of days with these units:
878  
879 @display
880 1 kin = 1 day@ @ @ 1 uinal = 20 kin@ @ @ 1 tun = 18 uinal
881 1 katun = 20 tun@ @ @ 1 baktun = 20 katun
882 @end display
883
884 @kindex g m l @r{(Calendar mode)}
885 @findex calendar-goto-mayan-long-count-date
886 @noindent
887 Thus, the long count date 12.16.11.16.6 means 12 baktun, 16 katun, 11
888 tun, 16 uinal, and 6 kin.  The Emacs calendar can handle Mayan long
889 count dates as early as 7.17.18.13.1, but no earlier.  When you use the
890 @kbd{g m l} command, type the Mayan long count date with the baktun,
891 katun, tun, uinal, and kin separated by periods.
892
893 @findex calendar-previous-tzolkin-date
894 @findex calendar-next-tzolkin-date
895 @cindex Mayan tzolkin calendar
896   The Mayan tzolkin calendar is a cycle of 260 days formed by a pair of
897 independent cycles of 13 and 20 days.  Since this cycle repeats
898 endlessly, Emacs provides commands to move backward and forward to the
899 previous or next point in the cycle.  Type @kbd{g m p t} to go to the
900 previous tzolkin date; Emacs asks you for a tzolkin date and moves point
901 to the previous occurrence of that date.  Similarly, type @kbd{g m n t}
902 to go to the next occurrence of a tzolkin date.
903
904 @findex calendar-previous-haab-date
905 @findex calendar-next-haab-date
906 @cindex Mayan haab calendar
907   The Mayan haab calendar is a cycle of 365 days arranged as 18 months
908 of 20 days each, followed a 5-day monthless period.  Like the tzolkin
909 cycle, this cycle repeats endlessly, and there are commands to move
910 backward and forward to the previous or next point in the cycle.  Type
911 @kbd{g m p h} to go to the previous haab date; Emacs asks you for a haab
912 date and moves point to the previous occurrence of that date.
913 Similarly, type @kbd{g m n h} to go to the next occurrence of a haab
914 date.
915
916 @c This is omitted because it is too long for smallbook format.
917 @c @findex calendar-previous-calendar-round-date
918 @findex calendar-next-calendar-round-date
919 @cindex Mayan calendar round
920   The Maya also used the combination of the tzolkin date and the haab
921 date.  This combination is a cycle of about 52 years called a
922 @emph{calendar round}.  If you type @kbd{g m p c}, Emacs asks you for
923 both a haab and a tzolkin date and then moves point to the previous
924 occurrence of that combination.  Use @kbd{g m n c} to move point to the
925 next occurrence of a combination.  These commands signal an error if the
926 haab/tzolkin date combination you have typed is impossible.
927
928   Emacs uses strict completion (@pxref{Completion}) whenever it
929 asks you to type a Mayan name, so you don't have to worry about
930 spelling.
931
932 @node Diary, Calendar Customization, Mayan Calendar, Calendar/Diary
933 @subsection The Diary
934 @cindex diary
935
936   The Emacs diary keeps track of appointments or other events on a daily
937 basis, in conjunction with the calendar.  To use the diary feature, you
938 must first create a @dfn{diary file} containing a list of events and
939 their dates.  Then Emacs can automatically pick out and display the
940 events for today, for the immediate future, or for any specified
941 date.
942
943   By default, Emacs uses @file{~/diary} as the diary file.  This is the
944 same file that the @code{calendar} utility uses.  A sample
945 @file{~/diary} file is:
946
947 @example
948 12/22/1988 Twentieth wedding anniversary!!
949 &1/1. Happy New Year!
950 10/22 Ruth's birthday.
951 * 21, *: Payday
952 Tuesday--weekly meeting with grad students at 10am
953          Supowit, Shen, Bitner, and Kapoor to attend.
954 1/13/89 Friday the thirteenth!!
955 &thu 4pm squash game with Lloyd.
956 mar 16 Dad's birthday
957 April 15, 1989 Income tax due.
958 &* 15 time cards due.
959 @end example
960
961 @noindent
962 This example uses extra spaces to align the event descriptions of most
963 of the entries.  Such formatting is purely a matter of taste.
964
965   Although you probably will start by creating a diary manually, Emacs
966 provides a number of commands to let you view, add, and change diary
967 entries.  You can also share diary entries with other users
968 (@pxref{Included Diary Files}).
969
970 @menu
971 * Diary Commands::         Viewing diary entries and associated calendar dates.
972 * Format of Diary File::   Entering events in your diary.
973 * Date Formats::           Various ways you can specify dates.
974 * Adding to Diary::        Commands to create diary entries.
975 * Special Diary Entries::  Anniversaries, blocks of dates, cyclic entries, etc.
976 @end menu
977
978 @node Diary Commands, Format of Diary File, Diary, Diary
979 @subsection Commands Displaying Diary Entries
980
981   Once you have created a @file{~/diary} file, you can use the calendar
982 to view it.  You can also view today's events outside of Calendar mode.
983
984 @table @kbd
985 @item d
986 Display all diary entries for the selected date
987 (@code{view-diary-entries}).
988 @item Button2 Diary
989 Display all diary entries for the date you click on.
990 @item s
991 Display the entire diary file (@code{show-all-diary-entries}).
992 @item m
993 Mark all visible dates that have diary entries
994 (@code{mark-diary-entries}).
995 @item u
996 Unmark the calendar window (@code{calendar-unmark}).
997 @item M-x print-diary-entries
998 Print hard copy of the diary display as it appears.
999 @item M-x diary
1000 Display all diary entries for today's date.
1001 @item M-x diary-mail-entries
1002 Mail yourself email reminders about upcoming diary entries.
1003 @end table
1004
1005 @kindex d @r{(Calendar mode)}
1006 @findex view-diary-entries
1007   Displaying the diary entries with @kbd{d} shows in a separate window
1008 the diary entries for the selected date in the calendar.  The mode line
1009 of the new window shows the date of the diary entries and any holidays
1010 that fall on that date.  If you specify a numeric argument with @kbd{d},
1011 it shows all the diary entries for that many successive days.  Thus,
1012 @kbd{2 d} displays all the entries for the selected date and for the
1013 following day.
1014
1015   Another way to display the diary entries for a date is to click
1016 @kbd{Button2} on the date, and then choose @kbd{Diary} from the menu
1017 that appears.
1018
1019 @kindex m @r{(Calendar mode)}
1020 @findex mark-diary-entries
1021 @kindex u @r{(Calendar mode)}
1022 @findex calendar-unmark
1023   To get a broader view of which days are mentioned in the diary, use
1024 the @kbd{m} command.  This displays the dates that have diary entries
1025 in a different face (or places a @samp{+} after these dates, if
1026 display with multiple faces is not available).  The command applies both
1027 to the currently visible months and to other months that subsequently
1028 become visible by scrolling.  To turn marking off and erase the current
1029 marks, type @kbd{u}, which also turns off holiday marks
1030 (@pxref{Holidays}).
1031
1032 @kindex s @r{(Calendar mode)}
1033 @findex show-all-diary-entries
1034   To see the full diary file, rather than just some of the entries, use
1035 the @kbd{s} command.
1036
1037   Display of selected diary entries uses the selective display feature
1038 to hide entries that don't apply.
1039
1040 @findex print-diary-entries
1041   The diary buffer as you see it is an illusion, so simply printing the
1042 buffer does not print what you see on your screen.  There is a special
1043 command to print hard copy of the diary buffer @emph{as it appears};
1044 this command is @kbd{M-x print-diary-entries}.  It sends the data
1045 directly to the printer.  You can customize it like @code{lpr-region}
1046 (@pxref{Hardcopy}).
1047
1048 @findex diary
1049   The command @kbd{M-x diary} displays the diary entries for the current
1050 date, independently of the calendar display, and optionally for the next
1051 few days as well; the variable @code{number-of-diary-entries} specifies
1052 how many days to include (@pxref{Customization}).
1053
1054   If you put @code{(diary)} in your init file, this
1055 automatically displays a window with the day's diary entries, when you
1056 enter Emacs.  @xref{Init File}.  The mode line of the displayed window
1057 shows the date and any holidays that fall on that date.
1058
1059 @findex diary-mail-entries
1060 @vindex diary-mail-days
1061   Many users like to receive notice of events in their diary as email.
1062 To send such mail to yourself, use the command @kbd{M-x
1063 diary-mail-entries}.  A prefix argument specifies how many days
1064 (starting with today) to check; otherwise, the variable
1065 @code{diary-mail-days} says how many days.
1066
1067 @node Format of Diary File, Date Formats, Diary Commands, Diary
1068 @subsection The Diary File
1069 @cindex diary file
1070
1071 @vindex diary-file
1072   Your @dfn{diary file} is a file that records events associated with
1073 particular dates.  The name of the diary file is specified by the
1074 variable @code{diary-file}; @file{~/diary} is the default.  The
1075 @code{calendar} utility program supports a subset of the format allowed
1076 by the Emacs diary facilities, so you can use that utility to view the
1077 diary file, with reasonable results aside from the entries it cannot
1078 understand.
1079
1080   Each entry in the diary file describes one event and consists of one
1081 or more lines.  An entry always begins with a date specification at the
1082 left margin.  The rest of the entry is simply text to describe the
1083 event.  If the entry has more than one line, then the lines after the
1084 first must begin with whitespace to indicate they continue a previous
1085 entry.  Lines that do not begin with valid dates and do not continue a
1086 preceding entry are ignored.
1087
1088   You can inhibit the marking of certain diary entries in the calendar
1089 window; to do this, insert an ampersand (@samp{&}) at the beginning of
1090 the entry, before the date.  This has no effect on display of the entry
1091 in the diary window; it affects only marks on dates in the calendar
1092 window.  Nonmarking entries are especially useful for generic entries
1093 that would otherwise mark many different dates.
1094
1095   If the first line of a diary entry consists only of the date or day
1096 name with no following blanks or punctuation, then the diary window
1097 display doesn't include that line; only the continuation lines appear.
1098 For example, this entry:
1099
1100 @example
1101 02/11/1989
1102       Bill B. visits Princeton today
1103       2pm Cognitive Studies Committee meeting
1104       2:30-5:30 Liz at Lawrenceville
1105       4:00pm Dentist appt
1106       7:30pm Dinner at George's
1107       8:00-10:00pm concert
1108 @end example
1109
1110 @noindent
1111 appears in the diary window without the date line at the beginning.
1112 This style of entry looks neater when you display just a single day's
1113 entries, but can cause confusion if you ask for more than one day's
1114 entries.
1115
1116   You can edit the diary entries as they appear in the window, but it is
1117 important to remember that the buffer displayed contains the @emph{entire}
1118 diary file, with portions of it concealed from view.  This means, for
1119 instance, that the @kbd{C-f} (@code{forward-char}) command can put point
1120 at what appears to be the end of the line, but what is in reality the
1121 middle of some concealed line.  
1122
1123   @emph{Be careful when editing the diary entries!}  Inserting
1124 additional lines or adding/deleting characters in the middle of a
1125 visible line cannot cause problems, but editing at the end of a line may
1126 not do what you expect.  Deleting a line may delete other invisible
1127 entries that follow it.  Before editing the diary, it is best to display
1128 the entire file with @kbd{s} (@code{show-all-diary-entries}).
1129
1130 @node Date Formats,Adding to Diary ,Format of Diary File, Diary
1131 @subsection Date Formats
1132
1133   Here are some sample diary entries, illustrating different ways of
1134 formatting a date.  The examples all show dates in American order
1135 (month, day, year), but Calendar mode supports European order (day,
1136 month, year) as an option.
1137
1138 @example
1139 4/20/93  Switch-over to new tabulation system
1140 apr. 25  Start tabulating annual results
1141 4/30  Results for April are due
1142 */25  Monthly cycle finishes
1143 Friday  Don't leave without backing up files
1144 @end example
1145
1146   The first entry appears only once, on April 20, 1993.  The second and
1147 third appear every year on the specified dates, and the fourth uses a
1148 wildcard (asterisk) for the month, so it appears on the 25th of every
1149 month.  The final entry appears every week on Friday.
1150
1151   You can use just numbers to express a date, as in
1152 @samp{@var{month}/@var{day}} or @samp{@var{month}/@var{day}/@var{year}}.
1153 This must be followed by a nondigit.  In the date itself, @var{month}
1154 and @var{day} are numbers of one or two digits.  The optional @var{year}
1155 is also a number, and may be abbreviated to the last two digits; that
1156 is, you can use @samp{11/12/1989} or @samp{11/12/89}.
1157
1158   Dates can also have the form @samp{@var{monthname} @var{day}} or
1159 @samp{@var{monthname} @var{day}, @var{year}}, where the month's name can
1160 be spelled in full or abbreviated to three characters (with or without a
1161 period).  Case is not significant.
1162
1163   A date may be @dfn{generic}; that is, partially unspecified.  Then the
1164 entry applies to all dates that match the specification.  If the date
1165 does not contain a year, it is generic and applies to any year.
1166 Alternatively, @var{month}, @var{day}, or @var{year} can be a @samp{*};
1167 this matches any month, day, or year, respectively.  Thus, a diary entry
1168 @samp{3/*/*} matches any day in March of any year; so does @samp{march
1169 *}.
1170
1171 @vindex european-calendar-style
1172 @findex european-calendar
1173 @findex american-calendar
1174   If you prefer the European style of writing dates---in which the day
1175 comes before the month---type @kbd{M-x european-calendar} while in the
1176 calendar, or set the variable @code{european-calendar-style} to @code{t}
1177 @emph{before} using any calendar or diary command.  This mode interprets
1178 all dates in the diary in the European manner, and also uses European
1179 style for displaying diary dates.  (Note that there is no comma after
1180 the @var{monthname} in the European style.)  To go back to the (default)
1181 American style of writing dates, type @kbd{M-x american-calendar}.
1182  
1183   You can use the name of a day of the week as a generic date which
1184 applies to any date falling on that day of the week.  You can abbreviate
1185 the day of the week to three letters (with or without a period) or spell
1186 it in full; case is not significant.
1187
1188 @node Adding to Diary, Special Diary Entries, Date Formats, Diary
1189 @subsection Commands to Add to the Diary
1190
1191   While in the calendar, there are several commands to create diary
1192 entries:
1193
1194 @table @kbd
1195 @item i d
1196 Add a diary entry for the selected date (@code{insert-diary-entry}).
1197 @item i w
1198 Add a diary entry for the selected day of the week (@code{insert-weekly-diary-entry}).
1199 @item i m
1200 Add a diary entry for the selected day of the month (@code{insert-monthly-diary-entry}).
1201 @item i y
1202 Add a diary entry for the selected day of the year (@code{insert-yearly-diary-entry}).
1203 @end table
1204
1205 @kindex i d @r{(Calendar mode)}
1206 @findex insert-diary-entry
1207   You can make a diary entry for a specific date by selecting that date
1208 in the calendar window and typing the @kbd{i d} command.  This command
1209 displays the end of your diary file in another window and inserts the
1210 date; you can then type the rest of the diary entry.
1211
1212 @kindex i w @r{(Calendar mode)}
1213 @findex insert-weekly-diary-entry
1214 @kindex i m @r{(Calendar mode)}
1215 @findex insert-monthly-diary-entry
1216 @kindex i y @r{(Calendar mode)}
1217 @findex insert-yearly-diary-entry
1218   If you want to make a diary entry that applies to a specific day of
1219 the week, select that day of the week (any occurrence will do) and type
1220 @kbd{i w}.  This inserts the day-of-week as a generic date; you can then
1221 type the rest of the diary entry.  You can make a monthly diary entry in
1222 the same fashion.  Select the day of the month, use the @kbd{i m}
1223 command, and type rest of the entry.  Similarly, you can insert a yearly
1224 diary entry with the @kbd{i y} command.
1225
1226   All of the above commands make marking diary entries by default.  To
1227 make a nonmarking diary entry, give a numeric argument to the command.
1228 For example, @kbd{C-u i w} makes a nonmarking weekly diary entry.
1229
1230   When you modify the diary file, be sure to save the file before
1231 exiting Emacs.
1232  
1233 @node Special Diary Entries,, Adding to Diary, Diary
1234 @subsection Special Diary Entries
1235
1236   In addition to entries based on calendar dates, the diary file can
1237 contain @dfn{sexp entries} for regular events such as anniversaries.
1238 These entries are based on Lisp expressions (sexps) that Emacs evaluates
1239 as it scans the diary file.  Instead of a date, a sexp entry contains
1240 @samp{%%} followed by a Lisp expression which must begin and end with
1241 parentheses.  The Lisp expression determines which dates the entry
1242 applies to.
1243
1244   Calendar mode provides commands to insert certain commonly used
1245 sexp entries:
1246
1247 @table @kbd
1248 @item i a
1249 Add an anniversary diary entry for the selected date 
1250 (@code{insert-anniversary-diary-entry}).
1251 @item i b
1252 Add a block diary entry for the current region 
1253 (@code{insert-block-diary-entry}).
1254 @item i c
1255 Add a cyclic diary entry starting at the date 
1256 (@code{insert-cyclic-diary-entry}).
1257 @end table
1258
1259 @kindex i a @r{(Calendar mode)}
1260 @findex insert-anniversary-diary-entry
1261   If you want to make a diary entry that applies to the anniversary of a
1262 specific date, move point to that date and use the @kbd{i a} command.
1263 This displays the end of your diary file in another window and inserts
1264 the anniversary description; you can then type the rest of the diary
1265 entry. The entry looks like this:
1266
1267 @findex diary-anniversary
1268   The effect of @kbd{i a} is to add a @code{diary-anniversary} sexp to your
1269 diary file.  You can also add one manually, for instance:
1270
1271 @example
1272 %%(diary-anniversary 10 31 1948) Arthur's birthday
1273 @end example
1274
1275 @noindent
1276 This entry applies to October 31 in any year after 1948; @samp{10 31
1277 1948} specifies the date.  (If you are using the European calendar
1278 style, the month and day are interchanged.)  The reason this expression
1279 requires a beginning year is that advanced diary functions can use it to
1280 calculate the number of elapsed years.
1281
1282   A @dfn{block} diary entry applies to a specified range of consecutive
1283 dates.  Here is a block diary entry that applies to all dates from June
1284 24, 1990 through July 10, 1990:
1285
1286 @findex diary-block
1287 @example
1288 %%(diary-block 6 24 1990 7 10 1990) Vacation
1289 @end example
1290
1291 @noindent
1292 The @samp{6 24 1990} indicates the starting date and the @samp{7 10 1990}
1293 indicates the stopping date.  (Again, if you are using the European calendar
1294 style, the month and day are interchanged.)
1295
1296 @kindex i b @r{(Calendar mode)}
1297 @findex insert-block-diary-entry
1298   To insert a block entry, place point and the mark on the two
1299 dates that begin and end the range, and type @kbd{i b}.  This command
1300 displays the end of your diary file in another window and inserts the
1301 block description; you can then type the diary entry.
1302
1303 @kindex i c @r{(Calendar mode)}
1304 @findex insert-cyclic-diary-entry
1305    @dfn{Cyclic} diary entries repeat after a fixed interval of days.  To
1306 create one, select the starting date and use the @kbd{i c} command.  The
1307 command prompts for the length of interval, then inserts the entry,
1308 which looks like this:
1309
1310 @findex diary-cyclic
1311 @example
1312 %%(diary-cyclic 50 3 1 1990) Renew medication
1313 @end example
1314
1315 @noindent
1316 This entry applies to March 1, 1990 and every 50th day following;
1317 @samp{3 1 1990} specifies the starting date.  (If you are using the
1318 European calendar style, the month and day are interchanged.)
1319
1320   All three of these commands make marking diary entries.  To insert a
1321 nonmarking entry, give a numeric argument to the command.  For example,
1322 @kbd{C-u i a} makes a nonmarking anniversary diary entry.
1323
1324   Marking sexp diary entries in the calendar is @emph{extremely}
1325 time-consuming, since every date visible in the calendar window must be
1326 individually checked.  So it's a good idea to make sexp diary entries
1327 nonmarking (with @samp{&}) when possible.
1328
1329   Another sophisticated kind of sexp entry, a @dfn{floating} diary entry,
1330 specifies a regularly occurring event by offsets specified in days,
1331 weeks, and months.  It is comparable to a crontab entry interpreted by
1332 the @code{cron} utility.  Here is a nonmarking, floating diary entry
1333 that applies to the last Thursday in November:
1334  
1335 @findex diary-float
1336 @example
1337 &%%(diary-float 11 4 -1) American Thanksgiving
1338 @end example
1339
1340 @noindent
1341 The 11 specifies November (the eleventh month), the 4 specifies Thursday
1342 (the fourth day of the week, where Sunday is numbered zero), and the
1343 @minus{}1 specifies ``last'' (1 would mean ``first'', 2 would mean
1344 ``second'', @minus{}2 would mean ``second-to-last'', and so on).  The
1345 month can be a single month or a list of months.  Thus you could change
1346 the 11 above to @samp{'(1 2 3)} and have the entry apply to the last
1347 Thursday of January, February, and March.  If the month is @code{t}, the
1348 entry applies to all months of the year.@refill
1349
1350   The sexp feature of the diary allows you to specify diary entries
1351 based on any Emacs Lisp expression.  You can use the library of built-in
1352 functions or you can write your own functions.  The built-in functions
1353 include the ones shown in this section, plus a few others (@pxref{Sexp
1354 Diary Entries}).
1355
1356   The generality of sexps lets you specify any diary entry that you can
1357 describe algorithmically.  Suppose you get paid on the 21st of the month
1358 if it is a weekday, and to the Friday before if the 21st is on a
1359 weekend.  The diary entry
1360
1361 @example
1362 &%%(let ((dayname (calendar-day-of-week date))
1363          (day (car (cdr date))))
1364       (or (and (= day 21) (memq dayname '(1 2 3 4 5)))
1365           (and (memq day '(19 20)) (= dayname 5)))
1366          ) Pay check deposited
1367 @end example
1368
1369 @noindent
1370 to just those dates.  This example illustrates how the sexp can depend
1371 on the variable @code{date}; this variable is a list (@var{month}
1372 @var{day} @var{year}) that gives the Gregorian date for which the diary
1373 entries are being found.  If the value of the sexp is @code{t}, the
1374 entry applies to that date.  If the sexp evaluates to @code{nil}, the
1375 entry does @emph{not} apply to that date.
1376
1377
1378 @node Calendar Customization,,Diary, Calendar/Diary
1379 @subsection Customizing the Calendar and Diary
1380
1381   There are many customizations that you can use to make the calendar and
1382 diary suit your personal tastes.
1383
1384 @menu
1385 * Calendar Customizing::   Defaults you can set.
1386 * Holiday Customizing::    Defining your own holidays.
1387 * Date Display Format::    Changing the format.
1388 * Time Display Format::    Changing the format.
1389 * Daylight Savings::       Changing the default.
1390 * Diary Customizing::      Defaults you can set.
1391 * Hebrew/Islamic Entries:: How to obtain them.
1392 * Fancy Diary Display::    Enhancing the diary display, sorting entries.
1393 * Included Diary Files::   Sharing a common diary file.
1394 * Sexp Diary Entries::     Fancy things you can do.
1395 * Appt Customizing::       Customizing appointment reminders.
1396 @end menu
1397
1398 @node Calendar Customizing
1399 @subsubsection Customizing the Calendar
1400 @vindex view-diary-entries-initially
1401
1402   If you set the variable @code{view-diary-entries-initially} to
1403 @code{t}, calling up the calendar automatically displays the diary
1404 entries for the current date as well.  The diary dates appear only if
1405 the current date is visible.  If you add both of the following lines to
1406 your init file:@refill
1407
1408 @example
1409 (setq view-diary-entries-initially t)
1410 (calendar)
1411 @end example
1412
1413 @noindent
1414 this displays both the calendar and diary windows whenever you start
1415 Emacs.  @xref{Init File}.
1416
1417 @vindex view-calendar-holidays-initially
1418   Similarly, if you set the variable
1419 @code{view-calendar-holidays-initially} to @code{t}, entering the
1420 calendar automatically displays a list of holidays for the current
1421 three-month period.  The holiday list appears in a separate
1422 window.
1423  
1424 @vindex mark-diary-entries-in-calendar
1425   You can set the variable @code{mark-diary-entries-in-calendar} to
1426 @code{t} in order to mark any dates with diary entries.  This takes
1427 effect whenever the calendar window contents are recomputed.  There are
1428 two ways of marking these dates: by changing the face (@pxref{Faces}),
1429 if the display supports that, or by placing a plus sign (@samp{+})
1430 beside the date otherwise.
1431
1432 @vindex mark-holidays-in-calendar
1433   Similarly, setting the variable @code{mark-holidays-in-calendar} to
1434 @code{t} marks holiday dates, either with a change of face or with an
1435 asterisk (@samp{*}).
1436
1437 @vindex calendar-holiday-marker
1438 @vindex diary-entry-marker
1439   The variable @code{calendar-holiday-marker} specifies how to mark a
1440 date as being a holiday.  Its value may be a character to insert next to
1441 the date, or a face name to use for displaying the date.  Likewise, the
1442 variable @code{diary-entry-marker} specifies how to mark a date that has
1443 diary entries.  The calendar creates faces named @code{holiday-face} and
1444 @code{diary-face} for these purposes; those symbols are the default
1445 values of these variables, when Emacs supports multiple faces on your
1446 terminal.
1447
1448 @vindex calendar-load-hook
1449   The variable @code{calendar-load-hook} is a normal hook run when the
1450 calendar package is first loaded (before actually starting to display
1451 the calendar).
1452
1453 @vindex initial-calendar-window-hook
1454   Starting the calendar runs the normal hook
1455 @code{initial-calendar-window-hook}.  Recomputation of the calendar
1456 display does not run this hook.  But if you leave the calendar with the
1457 @kbd{q} command and reenter it, the hook runs again.@refill
1458
1459 @vindex today-visible-calendar-hook
1460   The variable @code{today-visible-calendar-hook} is a normal hook run
1461 after the calendar buffer has been prepared with the calendar when the
1462 current date is visible in the window.  One use of this hook is to
1463 replace today's date with asterisks; to do that, use the hook function
1464 @code{calendar-star-date}.
1465
1466 @findex calendar-star-date
1467 @example
1468 (add-hook 'today-visible-calendar-hook 'calendar-star-date)
1469 @end example
1470
1471 @noindent
1472 Another standard hook function marks the current date, either by
1473 changing its face or by adding an asterisk.  Here's how to use it:
1474
1475 @findex calendar-mark-today
1476 @example
1477 (add-hook 'today-visible-calendar-hook 'calendar-mark-today)
1478 @end example
1479
1480 @noindent
1481 @vindex calendar-today-marker
1482 The variable @code{calendar-today-marker} specifies how to mark today's
1483 date.  Its value should be a character to insert next to the date or a
1484 face name to use for displaying the date.  A face named
1485 @code{calendar-today-face} is provided for this purpose; that symbol is
1486 the default for this variable when Emacs supports multiple faces on your
1487 terminal.
1488
1489 @vindex today-invisible-calendar-hook
1490 @noindent
1491   A similar normal hook, @code{today-invisible-calendar-hook} is run if
1492 the current date is @emph{not} visible in the window.
1493
1494 @node Holiday Customizing
1495 @subsubsection Customizing the Holidays
1496
1497 @vindex calendar-holidays
1498 @vindex christian-holidays
1499 @vindex hebrew-holidays
1500 @vindex islamic-holidays
1501   Emacs knows about holidays defined by entries on one of several lists.
1502 You can customize these lists of holidays to your own needs, adding or
1503 deleting holidays.  The lists of holidays that Emacs uses are for
1504 general holidays (@code{general-holidays}), local holidays
1505 (@code{local-holidays}), Christian holidays (@code{christian-holidays}),
1506 Hebrew (Jewish) holidays (@code{hebrew-holidays}), Islamic (Moslem)
1507 holidays (@code{islamic-holidays}), and other holidays
1508 (@code{other-holidays}).
1509
1510 @vindex general-holidays
1511   The general holidays are, by default, holidays common throughout the
1512 United States.  To eliminate these holidays, set @code{general-holidays}
1513 to @code{nil}.
1514
1515 @vindex local-holidays
1516   There are no default local holidays (but sites may supply some).  You
1517 can set the variable @code{local-holidays} to any list of holidays, as
1518 described below.
1519
1520 @vindex all-christian-calendar-holidays
1521 @vindex all-hebrew-calendar-holidays
1522 @vindex all-islamic-calendar-holidays
1523   By default, Emacs does not include all the holidays of the religions
1524 that it knows, only those commonly found in secular calendars.  For a
1525 more extensive collection of religious holidays, you can set any (or
1526 all) of the variables @code{all-christian-calendar-holidays},
1527 @code{all-hebrew-calendar-holidays}, or
1528 @code{all-islamic-calendar-holidays} to @code{t}.  If you want to
1529 eliminate the religious holidays, set any or all of the corresponding
1530 variables @code{christian-holidays}, @code{hebrew-holidays}, and
1531 @code{islamic-holidays} to @code{nil}.@refill
1532
1533 @vindex other-holidays
1534   You can set the variable @code{other-holidays} to any list of
1535 holidays.  This list, normally empty, is intended for individual use.
1536
1537 @cindex holiday forms
1538   Each of the lists (@code{general-holidays}, @code{local-holidays},
1539 @code{christian-holidays}, @code{hebrew-holidays},
1540 @code{islamic-holidays}, and @code{other-holidays}) is a list of
1541 @dfn{holiday forms}, each holiday form describing a holiday (or
1542 sometimes a list of holidays).
1543
1544   Here is a table of the possible kinds of holiday form.  Day numbers
1545 and month numbers count starting from 1, but ``dayname'' numbers
1546 count Sunday as 0.  The element @var{string} is always the
1547 name of the holiday, as a string.
1548
1549 @table @code
1550 @item (holiday-fixed @var{month} @var{day} @var{string})
1551 A fixed date on the Gregorian calendar.  @var{month} and @var{day} are
1552 numbers, @var{string} is the name of the holiday.
1553
1554 @item (holiday-float @var{month} @var{dayname} @var{k} @var{string})
1555 The @var{k}th @var{dayname} in @var{month} on the Gregorian calendar
1556 (@var{dayname}=0 for Sunday, and so on); negative @var{k} means count back
1557 from the end of the month.  @var{string} is the name of the holiday.
1558
1559 @item (holiday-hebrew @var{month} @var{day} @var{string})
1560 A fixed date on the Hebrew calendar.  @var{month} and @var{day} are
1561 numbers, @var{string} is the name of the holiday.
1562
1563 @item (holiday-islamic @var{month} @var{day} @var{string})
1564 A fixed date on the Islamic calendar.  @var{month} and @var{day} are
1565 numbers, @var{string} is the name of the holiday.
1566
1567 @item (holiday-julian @var{month} @var{day} @var{string})
1568 A fixed date on the Julian calendar.  @var{month} and @var{day} are
1569 numbers, @var{string} is the name of the holiday.
1570
1571 @item (holiday-sexp @var{sexp} @var{string})
1572 A date calculated by the Lisp expression @var{sexp}.  The expression
1573 should use the variable @code{year} to compute and return the date of a
1574 holiday, or @code{nil} if the holiday doesn't happen this year.  The
1575 value of @var{sexp} must represent the date as a list of the form
1576 @code{(@var{month} @var{day} @var{year})}.  @var{string} is the name of
1577 the holiday.
1578
1579 @item (if @var{condition} @var{holiday-form} &optional @var{holiday-form})
1580 A holiday that happens only if @var{condition} is true.
1581
1582 @item (@var{function} @r{[}@var{args}@r{]})
1583 A list of dates calculated by the function @var{function}, called with
1584 arguments @var{args}.
1585 @end table
1586
1587   For example, suppose you want to add Bastille Day, celebrated in
1588 France on July 14.  You can do this by adding the following line
1589 to your init file:
1590
1591 @smallexample
1592 (setq other-holidays '((holiday-fixed 7 14 "Bastille Day")))
1593 @end smallexample
1594
1595 @xref{Init File}.
1596
1597 @noindent
1598 The holiday form @code{(holiday-fixed 7 14 "Bastille Day")} specifies the
1599 fourteenth day of the seventh month (July).
1600
1601   Many holidays occur on a specific day of the week, at a specific time
1602 of month.  Here is a holiday form describing Hurricane Supplication Day,
1603 celebrated in the Virgin Islands on the fourth Monday in August:
1604
1605 @smallexample
1606 (holiday-float 8 1 4 "Hurricane Supplication Day")
1607 @end smallexample
1608
1609 @noindent
1610 Here the 8 specifies August, the 1 specifies Monday (Sunday is 0,
1611 Tuesday is 2, and so on), and the 4 specifies the fourth occurrence in
1612 the month (1 specifies the first occurrence, 2 the second occurrence,
1613 @minus{}1 the last occurrence, @minus{}2 the second-to-last occurrence, and
1614 so on).
1615
1616   You can specify holidays that occur on fixed days of the Hebrew,
1617 Islamic, and Julian calendars too.  For example,
1618
1619 @smallexample
1620 (setq other-holidays
1621       '((holiday-hebrew 10 2 "Last day of Hanukkah")
1622         (holiday-islamic 3 12 "Mohammed's Birthday")
1623         (holiday-julian 4 2 "Jefferson's Birthday")))
1624 @end smallexample
1625
1626 @noindent
1627 adds the last day of Hanukkah (since the Hebrew months are numbered with
1628 1 starting from Nisan), the Islamic feast celebrating Mohammed's
1629 birthday (since the Islamic months are numbered from 1 starting with
1630 Muharram), and Thomas Jefferson's birthday, which is 2 April 1743 on the
1631 Julian calendar.
1632
1633   To include a holiday conditionally, use either Emacs Lisp's @code{if} or the
1634 @code{holiday-sexp} form.  For example, American presidential elections
1635 occur on the first Tuesday after the first Monday in November of years
1636 divisible by 4:
1637
1638 @smallexample
1639 (holiday-sexp (if (= 0 (% year 4))
1640                    (calendar-gregorian-from-absolute
1641                  (1+ (calendar-dayname-on-or-before
1642                        1 (+ 6 (calendar-absolute-from-gregorian
1643                                 (list 11 1 year))))))
1644               "US Presidential Election"))
1645 @end smallexample
1646
1647 @noindent
1648 or
1649
1650 @smallexample
1651 (if (= 0 (% displayed-year 4))
1652     (fixed 11
1653            (extract-calendar-day
1654              (calendar-gregorian-from-absolute
1655                (1+ (calendar-dayname-on-or-before
1656                      1 (+ 6 (calendar-absolute-from-gregorian
1657                               (list 11 1 displayed-year)))))))
1658            "US Presidential Election"))
1659 @end smallexample
1660
1661   Some holidays just don't fit into any of these forms because special
1662 calculations are involved in their determination.  In such cases you
1663 must write a Lisp function to do the calculation.  To include eclipses,
1664 for example, add @code{(eclipses)} to @code{other-holidays}
1665 and write an Emacs Lisp function @code{eclipses} that returns a
1666 (possibly empty) list of the relevant Gregorian dates among the range
1667 visible in the calendar window, with descriptive strings, like this:
1668
1669 @smallexample
1670 (((6 27 1991) "Lunar Eclipse") ((7 11 1991) "Solar Eclipse") ... )
1671 @end smallexample
1672
1673 @node Date Display Format
1674 @subsubsection Date Display Format
1675 @vindex calendar-date-display-form
1676
1677   You can customize the manner of displaying dates in the diary, in mode
1678 lines, and in messages by setting @code{calendar-date-display-form}.
1679 This variable holds a list of expressions that can involve the variables
1680 @code{month}, @code{day}, and @code{year}, which are all numbers in
1681 string form, and @code{monthname} and @code{dayname}, which are both
1682 alphabetic strings.  In the American style, the default value of this
1683 list is as follows:
1684
1685 @smallexample
1686 ((if dayname (concat dayname ", ")) monthname " " day ", " year)
1687 @end smallexample
1688
1689 @noindent
1690 while in the European style this value is the default:
1691
1692 @smallexample
1693 ((if dayname (concat dayname ", ")) day " " monthname " " year)
1694 @end smallexample
1695
1696 +@noindent
1697 The ISO standard date representation is this:
1698
1699 @smallexample
1700 (year "-" month "-" day)
1701 @end smallexample
1702
1703 @noindent
1704 This specifies a typical American format:
1705
1706 @smallexample
1707 (month "/" day "/" (substring year -2))
1708 @end smallexample
1709
1710 @node Time Display Format
1711 @subsubsection Time Display Format
1712 @vindex calendar-time-display-form
1713
1714   The calendar and diary by default display times of day in the
1715 conventional American style with the hours from 1 through 12, minutes,
1716 and either @samp{am} or @samp{pm}.  If you prefer the European style,
1717 also known in the US as military, in which the hours go from 00 to 23,
1718 you can alter the variable @code{calendar-time-display-form}.  This
1719 variable is a list of expressions that can involve the variables
1720 @code{12-hours}, @code{24-hours}, and @code{minutes}, which are all
1721 numbers in string form, and @code{am-pm} and @code{time-zone}, which are
1722 both alphabetic strings.  The default value of
1723 @code{calendar-time-display-form} is as follows:
1724
1725 @smallexample
1726 (12-hours ":" minutes am-pm
1727           (if time-zone " (") time-zone (if time-zone ")"))
1728 @end smallexample
1729
1730 @noindent
1731 Here is a value that provides European style times:
1732
1733 @smallexample
1734 (24-hours ":" minutes
1735           (if time-zone " (") time-zone (if time-zone ")"))
1736 @end smallexample
1737
1738 @noindent
1739 gives military-style times like @samp{21:07 (UT)} if time zone names are
1740 defined, and times like @samp{21:07} if they are not.
1741
1742 @node Daylight Savings
1743 @subsubsection Daylight Savings Time
1744 @cindex daylight savings time
1745
1746   Emacs understands the difference between standard time and daylight
1747 savings time---the times given for sunrise, sunset, solstices,
1748 equinoxes, and the phases of the moon take that into account.  The rules
1749 for daylight savings time vary from place to place and have also varied
1750 historically from year to year.  To do the job properly, Emacs needs to
1751 know which rules to use.
1752
1753   Some operating systems keep track of the rules that apply to the place
1754 where you are; on these systems, Emacs gets the information it needs
1755 from the system automatically.  If some or all of this information is
1756 missing, Emacs fills in the gaps with the rules currently used in
1757 Cambridge, Massachusetts.  If the resulting rules are not what you want,
1758 you can tell Emacs the rules to use by setting certain variables.
1759
1760 @vindex calendar-daylight-savings-starts
1761 @vindex calendar-daylight-savings-ends
1762   If the default choice of rules is not appropriate for your location,
1763 you can tell Emacs the rules to use by setting the variables
1764 @code{calendar-daylight-savings-starts} and
1765 @code{calendar-daylight-savings-ends}.  Their values should be Lisp
1766 expressions that refer to the variable @code{year}, and evaluate to the
1767 Gregorian date on which daylight savings time starts or (respectively)
1768 ends, in the form of a list @code{(@var{month} @var{day} @var{year})}.
1769 The values should be @code{nil} if your area does not use daylight
1770 savings time.
1771
1772   Emacs uses these expressions to determine the starting date of
1773 daylight savings time for the holiday list  and for correcting times of
1774 day in the solar and lunar calculations.
1775  
1776   The values for Cambridge, Massachusetts are as follows:
1777
1778 @example
1779 @group
1780 (calendar-nth-named-day 1 0 4 year)
1781 (calendar-nth-named-day -1 0 10 year)
1782 @end group
1783 @end example
1784
1785 @noindent
1786 That is, the first 0th day (Sunday) of the fourth month (April) in
1787 the year specified by @code{year}, and the last Sunday of the tenth month
1788 (October) of that year.  If daylight savings time were
1789 changed to start on October 1, you would set
1790 @code{calendar-daylight-savings-starts} to this:
1791
1792 @example
1793 (list 10 1 year)
1794 @end example
1795
1796   For a more complex example, suppose daylight savings time begins on
1797 the first of Nisan on the Hebrew calendar.  You should set
1798 @code{calendar-daylight-savings-starts} to this value:
1799
1800 @example
1801 (calendar-gregorian-from-absolute
1802   (calendar-absolute-from-hebrew
1803     (list 1 1 (+ year 3760))))
1804 @end example
1805
1806 @noindent
1807 because Nisan is the first month in the Hebrew calendar and the Hebrew
1808 year differs from the Gregorian year by 3760 at Nisan.
1809
1810   If there is no daylight savings time at your location, or if you want
1811 all times in standard time, set @code{calendar-daylight-savings-starts}
1812 and @code{calendar-daylight-savings-ends} to @code{nil}.
1813
1814 @vindex calendar-daylight-time-offset
1815   The variable @code{calendar-daylight-time-offset} specifies the
1816 difference between daylight savings time and standard time, measured in
1817 minutes.  The value for Cambridge, Massachusetts is 60.
1818
1819 @c @vindex calendar-daylight-savings-starts-time  too long!
1820 @vindex calendar-daylight-savings-ends-time
1821   The two variables @code{calendar-daylight-savings-starts-time} and
1822 @code{calendar-daylight-savings-ends-time} specify the number of minutes
1823 after midnight local time when the transition to and from daylight
1824 savings time should occur.  For Cambridge, Massachusetts both variables'
1825 values are 120.
1826  
1827 @node Diary Customizing
1828 @subsubsection Customizing the Diary
1829
1830 @vindex holidays-in-diary-buffer
1831   Ordinarily, the mode line of the diary buffer window indicates any
1832 holidays that fall on the date of the diary entries.  The process of
1833 checking for holidays can take several seconds, so including holiday
1834 information delays the display of the diary buffer noticeably.  If you'd
1835 prefer to have a faster display of the diary buffer but without the
1836 holiday information, set the variable @code{holidays-in-diary-buffer} to
1837 @code{nil}.@refill
1838
1839 @vindex number-of-diary-entries
1840   The variable @code{number-of-diary-entries} controls the number of
1841 days of diary entries to be displayed at one time.  It affects the
1842 initial display when @code{view-diary-entries-initially} is @code{t}, as
1843 well as the command @kbd{M-x diary}.  For example, the default value is
1844 1, which says to display only the current day's diary entries.  If the
1845 value is 2, both the current day's and the next day's entries are
1846 displayed.  The value can also be a vector of seven elements: for
1847 example, if the value is @code{[0 2 2 2 2 4 1]} then no diary entries
1848 appear on Sunday, the current date's and the next day's diary entries
1849 appear Monday through Thursday, Friday through Monday's entries appear
1850 on Friday, while on Saturday only that day's entries appear.
1851
1852 @vindex print-diary-entries-hook
1853 @findex print-diary-entries
1854   The variable @code{print-diary-entries-hook} is a normal hook run
1855 after preparation of a temporary buffer containing just the diary
1856 entries currently visible in the diary buffer.  (The other, irrelevant
1857 diary entries are really absent from the temporary buffer; in the diary
1858 buffer, they are merely hidden.)  The default value of this hook does
1859 the printing with the command @code{lpr-buffer}.  If you want to use a
1860 different command to do the printing, just change the value of this
1861 hook.  Other uses might include, for example, rearranging the lines into
1862 order by day and time.
1863
1864 @vindex diary-date-forms
1865   You can customize the form of dates in your diary file, if neither the
1866 standard American nor European styles suits your needs, by setting the
1867 variable @code{diary-date-forms}.  This variable is a list of patterns
1868 for recognizing a date.  Each date pattern is a list whose elements may
1869 be regular expressions (@pxref{Regexps}) or the symbols
1870 @code{month}, @code{day}, @code{year}, @code{monthname}, and
1871 @code{dayname}.  All these elements serve as patterns that match certain
1872 kinds of text in the diary file.  In order for the date pattern, as a
1873 whole, to match, all of its elements must match consecutively.
1874
1875   A regular expression in a date pattern matches in its usual fashion,
1876 using the standard syntax table altered so that @samp{*} is a word
1877 constituent.
1878
1879   The symbols @code{month}, @code{day}, @code{year}, @code{monthname},
1880 and @code{dayname} match the month number, day number, year number,
1881 month name, and day name of the date being considered.  The symbols that
1882 match numbers allow leading zeros; those that match names allow
1883 three-letter abbreviations and capitalization.  All the symbols can
1884 match @samp{*}; since @samp{*} in a diary entry means ``any day'', ``any
1885 month'', and so on, it should match regardless of the date being
1886 considered.
1887
1888   The default value of @code{diary-date-forms} in the American style is
1889 this:
1890
1891 @example
1892 ((month "/" day "[^/0-9]")
1893  (month "/" day "/" year "[^0-9]")
1894  (monthname " *" day "[^,0-9]")
1895  (monthname " *" day ", *" year "[^0-9]")
1896  (dayname "\\W"))
1897 @end example
1898
1899 @noindent
1900 Emacs matches of the diary entries with the date forms is done with the
1901 standard syntax table from Fundamental mode
1902 (@pxref{Syntax Tables,,,lispref,XEmacs Lisp Reference Manual}),
1903 but with the @samp{*} changed so that it is a word constituent.@refill
1904
1905   The date patterns in the list must be @emph{mutually exclusive} and
1906 must not match any portion of the diary entry itself, just the date and
1907 one character of whitespace.  If, to be mutually exclusive, the pattern
1908 must match a portion of the diary entry text---beyond the whitespace
1909 that ends the date---then the first element of the date pattern
1910 @emph{must} be @code{backup}.  This causes the date recognizer to back
1911 up to the beginning of the current word of the diary entry, after
1912 finishing the match.  Even if you use @code{backup}, the date pattern
1913 must absolutely not match more than a portion of the first word of the
1914 diary entry.  The default value of @code{diary-date-forms} in the
1915 European style is this list:
1916
1917 @example
1918 ((day "/" month "[^/0-9]")
1919  (day "/" month "/" year "[^0-9]")
1920  (backup day " *" monthname "\\W+\\<[^*0-9]")
1921  (day " *" monthname " *" year "[^0-9]")
1922  (dayname "\\W"))
1923 @end example
1924
1925 @noindent
1926 Notice the use of @code{backup} in the third pattern, because it needs
1927 to match part of a word beyond the date itself to distinguish it from
1928 the fourth pattern.
1929  
1930 @node Hebrew/Islamic Entries
1931 @subsubsection Hebrew- and Islamic-Date Diary Entries
1932
1933   Your diary file can have entries based on Hebrew or Islamic dates, as
1934 well as entries based on the world-standard Gregorian calendar.
1935 However, because recognition of such entries is time-consuming and most
1936 people don't use them, you must explicitly enable their use.  If you
1937 want the diary to recognize Hebrew-date diary entries, for example, 
1938 you must do this:
1939  
1940 @vindex nongregorian-diary-listing-hook
1941 @vindex nongregorian-diary-marking-hook
1942 @findex list-hebrew-diary-entries
1943 @findex mark-hebrew-diary-entries
1944 @smallexample
1945 (add-hook 'nongregorian-diary-listing-hook 'list-hebrew-diary-entries)
1946 (add-hook 'nongregorian-diary-marking-hook 'mark-hebrew-diary-entries)
1947 @end smallexample
1948
1949 @noindent
1950 If you want Islamic-date entries, do this:
1951
1952 @findex list-islamic-diary-entries
1953 @findex mark-islamic-diary-entries
1954 @smallexample
1955 (add-hook 'nongregorian-diary-listing-hook 'list-islamic-diary-entries)
1956 (add-hook 'nongregorian-diary-marking-hook 'mark-islamic-diary-entries)
1957 @end smallexample
1958
1959   Hebrew- and Islamic-date diary entries have the same formats as
1960 Gregorian-date diary entries, except that @samp{H} precedes a Hebrew
1961 date and @samp{I} precedes an Islamic date.  Moreover, because the
1962 Hebrew and Islamic month names are not uniquely specified by the first
1963 three letters, you may not abbreviate them.  For example, a diary entry
1964 for the Hebrew date Heshvan 25 could look like this:
1965
1966 @smallexample
1967 HHeshvan 25 Happy Hebrew birthday!
1968 @end smallexample
1969
1970 @noindent
1971 and would appear in the diary for any date that corresponds to Heshvan 25
1972 on the Hebrew calendar.  And here is  Islamic-date diary entry  that matches
1973 Dhu al-Qada 25:
1974
1975 @smallexample
1976 IDhu al-Qada 25 Happy Islamic birthday!
1977 @end smallexample
1978
1979 @noindent
1980 and would appear in the diary for any date that corresponds to Dhu al-Qada 25
1981 on the Islamic calendar.
1982
1983   As with Gregorian-date diary entries, Hebrew- and Islamic-date entries
1984 are nonmarking if they are preceded with an ampersand (@samp{&}).
1985
1986   Here is a table of commands used in the calendar to create diary entries
1987 that match the selected date and other dates that are similar in the Hebrew
1988 or Islamic calendar:
1989  
1990 @table @kbd
1991 @item i h d
1992 Add a diary entry for the Hebrew date corresponding to the selected date
1993 (@code{insert-hebrew-diary-entry}).
1994 @item i h m
1995 Add a diary entry for the day of the Hebrew month corresponding to the
1996 selected date (@code{insert-monthly-hebrew-diary-entry}).  This diary
1997 entry matches any date that has the same Hebrew day-within-month as the
1998 selected date.
1999 @item i h y
2000 Add a diary entry for the day of the Hebrew year corresponding to the
2001 selected date (@code{insert-yearly-hebrew-diary-entry}).  This diary 
2002 entry matches any date which has the same Hebrew month and day-within-month
2003 as the selected date.
2004 @item i i d
2005 Add a diary entry for the Islamic date corresponding to the selected date
2006 (@code{insert-islamic-diary-entry}).
2007 @item i i m
2008 Add a diary entry for the day of the Islamic month corresponding to the
2009 selected date (@code{insert-monthly-islamic-diary-entry}).
2010 @item i i y
2011 Add a diary entry for the day of the Islamic year corresponding to the
2012 selected date (@code{insert-yearly-islamic-diary-entry}).
2013 @end table
2014
2015 @findex insert-hebrew-diary-entry
2016 @findex insert-monthly-hebrew-diary-entry
2017 @findex insert-yearly-hebrew-diary-entry
2018 @findex insert-islamic-diary-entry
2019 @findex insert-monthly-islamic-diary-entry
2020 @findex insert-yearly-islamic-diary-entry
2021   These commands work much like the corresponding commands for ordinary
2022 diary entries: they apply to the date that point is on in the calendar
2023 window, and what they do is insert just the date portion of a diary entry
2024 at the end of your diary file.  You must then insert the rest of the 
2025 diary entry.
2026  
2027 @node Fancy Diary Display
2028 @subsubsection Fancy Diary Display
2029 @vindex diary-display-hook
2030 @findex simple-diary-display
2031
2032   Diary display works by preparing the diary buffer and then running the
2033 hook @code{diary-display-hook}.  The default value of this hook
2034 (@code{simple-diary-display}) hides the irrelevant diary entries and
2035 then displays the buffer.  However, if you specify the hook as follows,
2036  
2037 @cindex diary buffer
2038 @findex fancy-diary-display
2039 @example
2040 (add-hook 'diary-display-hook 'fancy-diary-display)
2041 @end example
2042
2043 @noindent
2044 this enables fancy diary display.  It displays diary entries and
2045 holidays by copying them into a special buffer that exists only for the
2046 sake of display.  Copying to a separate buffer provides an opportunity
2047 to change the displayed text to make it prettier---for example, to sort
2048 the entries by the dates they apply to.
2049
2050   As with simple diary display, you can print a hard copy of the buffer
2051 with @code{print-diary-entries}.  To print a hard copy of a day-by-day
2052 diary for a week by positioning point on Sunday of that week, type
2053 @kbd{7 d} and then do @kbd{M-x print-diary-entries}.  As usual, the
2054 inclusion of the holidays slows down the display slightly; you can speed
2055 things up by setting the variable @code{holidays-in-diary-buffer} to
2056 @code{nil}.
2057
2058 @vindex diary-list-include-blanks
2059   Ordinarily, the fancy diary buffer does not show days for which there are
2060 no diary entries, even if that day is a holiday.  If you want such days to be
2061 shown in the fancy diary buffer, set the variable
2062 @code{diary-list-include-blanks} to @code{t}.@refill
2063
2064 @cindex sorting diary entries
2065   If you use the fancy diary display, you can use the normal hook
2066 @code{list-diary-entries-hook} to sort each day's diary entries by their
2067 time of day.  Add this line to your init file:
2068
2069 @findex sort-diary-entries
2070 @example
2071 (add-hook 'list-diary-entries-hook 'sort-diary-entries t)
2072 @end example
2073
2074 @xref{Init File}.
2075
2076 @noindent
2077 For each day, this sorts diary entries that begin with a recognizable
2078 time of day according to their times.  Diary entries without times come
2079 first within each day.
2080
2081 @node Included Diary Files
2082 @subsubsection Included Diary Files
2083
2084   Fancy diary display also has the ability to process included diary
2085 files.  This permits a group of people to share a diary file for events
2086 that apply to all of them.  Lines in the diary file of this form:
2087  
2088 @smallexample
2089 #include "@var{filename}"
2090 @end smallexample
2091
2092 @noindent
2093 includes the diary entries from the file @var{filename} in the fancy
2094 diary buffer.  The include mechanism is recursive, so that included files
2095 can include other files, and so on; you must be careful not to have a
2096 cycle of inclusions, of course.  Here is how to enable the include
2097 facility:
2098
2099 @vindex list-diary-entries-hook
2100 @vindex mark-diary-entries-hook
2101 @findex include-other-diary-files
2102 @findex mark-included-diary-files
2103 @smallexample
2104 (add-hook 'list-diary-entries-hook 'include-other-diary-files)
2105 (add-hook 'mark-diary-entries-hook 'mark-included-diary-files)
2106 @end smallexample
2107
2108 The include mechanism works only with the fancy diary display, because
2109 ordinary diary display shows the entries directly from your diary file.
2110
2111 @node Sexp Diary Entries
2112 @subsubsection Sexp Entries and the Fancy Diary Display
2113 @cindex sexp diary entries
2114
2115   Sexp diary entries allow you to do more than just have complicated
2116 conditions under which a diary entry applies.  If you use the fancy
2117 diary display, sexp entries can generate the text of the entry depending
2118 on the date itself.  For example, an anniversary diary entry can insert
2119 the number of years since the anniversary date into the text of the
2120 diary entry.  Thus the @samp{%d} in this dairy entry:
2121
2122 @findex diary-anniversary
2123 @smallexample
2124 %%(diary-anniversary 10 31 1948) Arthur's birthday (%d years old)
2125 @end smallexample
2126
2127 @noindent
2128 gets replaced by the age, so on October 31, 1990 the entry appears in
2129 the fancy diary buffer like this:
2130
2131 @smallexample
2132 Arthur's birthday (42 years old)
2133 @end smallexample
2134
2135 @noindent
2136 If the diary file instead contains this entry:
2137
2138 @smallexample
2139 %%(diary-anniversary 10 31 1948) Arthur's %d%s birthday
2140 @end smallexample
2141
2142 @noindent
2143 the entry in the fancy diary buffer for October 31, 1990 appears like this:
2144
2145 @smallexample
2146 Arthur's 42nd birthday
2147 @end smallexample
2148
2149   Similarly, cyclic diary entries can interpolate the number of repetitions
2150 that have occurred:
2151
2152 @findex diary-cyclic
2153 @smallexample
2154 %%(diary-cyclic 50 1 1 1990) Renew medication (%d%s time)
2155 @end smallexample
2156
2157 @noindent
2158 looks like this:
2159
2160 @smallexample
2161 Renew medication (5th time)
2162 @end smallexample
2163
2164 @noindent
2165 in the fancy diary display on September 8, 1990.
2166
2167   The generality of sexp diary entries lets you specify any diary entry
2168 that you can describe algorithmically.  A sexp diary entry contains an
2169 expression that computes whether the entry applies to any given date.
2170 If its value is non-@code{nil}, the entry applies to that date;
2171 otherwise, it does not.  The expression can use the variable  @code{date}
2172 to find the date being considered; its value is a list (@var{month}
2173 @var{day} @var{year}) that refers to the Gregorian calendar.
2174
2175   Suppose you get paid on the 21st of the month if it is a weekday, and
2176 on the Friday before if the 21st is on a weekend.  Here is how to write
2177 a sexp diary entry that matches those dates:
2178
2179 @smallexample
2180 &%%(let ((dayname (calendar-day-of-week date))
2181          (day (car (cdr date))))
2182       (or (and (= day 21) (memq dayname '(1 2 3 4 5)))
2183           (and (memq day '(19 20)) (= dayname 5)))
2184          ) Pay check deposited
2185 @end smallexample
2186
2187 @noindent
2188 applies to just those dates.  This example illustrates how the sexp can
2189 depend on the variable @code{date}; this variable is a list (@var{month}
2190 @var{day} @var{year}) that gives the Gregorian date for which the diary
2191 entries are being found.  If the value of the expression is @code{t},
2192 the entry applies to that date.  If the expression evaluates to
2193 @code{nil}, the entry does @emph{not} apply to that date.
2194
2195   The following sexp diary entries take advantage of the ability (in the fancy
2196 diary display) to concoct diary entries whose text varies based on the date:
2197
2198 @findex diary-sunrise-sunset
2199 @findex diary-phases-of-moon
2200 @findex diary-day-of-year
2201 @findex diary-iso-date
2202 @findex diary-julian-date
2203 @findex diary-astro-day-number
2204 @findex diary-hebrew-date
2205 @findex diary-islamic-date
2206 @findex diary-french-date
2207 @findex diary-mayan-date
2208 @table @code
2209 @item %%(diary-sunrise-sunset)
2210 Make a diary entry for the local times of today's sunrise and sunset.
2211 @item %%(diary-phases-of-moon)
2212 Make a diary entry for the phases (quarters) of the moon.
2213 @item %%(diary-day-of-year)
2214 Make a diary entry with today's day number in the current year and the number
2215 of days remaining in the current year.
2216 @item %%(diary-iso-date)
2217 Make a diary entry with today's equivalent ISO commercial date.
2218 @item %%(diary-julian-date)
2219 Make a diary entry with today's equivalent date on the Julian calendar.
2220 @item %%(diary-astro-day-number)
2221 Make a diary entry with today's equivalent astronomical (Julian) day number.
2222 @item %%(diary-hebrew-date)
2223 Make a diary entry with today's equivalent date on the Hebrew calendar.
2224 @item %%(diary-islamic-date)
2225 Make a diary entry with today's equivalent date on the Islamic calendar.
2226 @item %%(diary-french-date)
2227 Make a diary entry with today's equivalent date on the French Revolutionary
2228 calendar.
2229 @item %%(diary-mayan-date)
2230 Make a diary entry with today's equivalent date on the Mayan calendar.
2231 @end table
2232
2233 @noindent
2234 Thus including the diary entry
2235
2236 @smallexample
2237 &%%(diary-hebrew-date)
2238 @end smallexample
2239
2240 @noindent
2241 causes every day's diary display to contain the equivalent date on the
2242 Hebrew calendar, if you are using the fancy diary display.  (With simple
2243 diary display, the line @samp{&%%(diary-hebrew-date)} appears in the
2244 diary for any date, but does nothing particularly useful.)
2245
2246   These functions can be used to construct sexp diary entries based on
2247 the Hebrew calendar in certain standard ways:
2248  
2249 @cindex rosh hodesh
2250 @findex diary-rosh-hodesh
2251 @cindex parasha, weekly
2252 @findex diary-parasha
2253 @cindex candle lighting times
2254 @findex diary-sabbath-candles
2255 @cindex omer count
2256 @findex diary-omer
2257 @cindex yahrzeits
2258 @findex diary-yahrzeit
2259 @table @code
2260 @item %%(diary-rosh-hodesh)
2261 Make a diary entry that tells the occurrence and ritual announcement of each
2262 new Hebrew month.
2263 @item %%(diary-parasha)
2264 Make a Saturday diary entry that tells the weekly synagogue scripture reading.
2265 @item %%(diary-sabbath-candles)
2266 Make a Friday diary entry that tells the @emph{local time} of Sabbath
2267 candle lighting.
2268 @item %%(diary-omer)
2269 Make a diary entry that gives the omer count, when appropriate.
2270 @item %%(diary-yahrzeit @var{month} @var{day} @var{year}) @var{name}
2271 Make a diary entry marking the anniversary of a date of death.  The date
2272 is the @emph{Gregorian} (civil) date of death.  The diary entry appears
2273 on the proper Hebrew calendar anniversary and on the day before.  (In
2274 the European style, the order of the parameters is changed to @var{day},
2275 @var{month}, @var{year}.)
2276 @end table
2277
2278 @node Appt Customizing
2279 @subsubsection Customizing Appointment Reminders
2280
2281   You can specify exactly how Emacs reminds you of an appointment, and
2282 how far in advance it begins doing so, by setting these variables:
2283
2284 @vindex appt-message-warning-time
2285 @vindex appt-audible
2286 @vindex appt-visible
2287 @vindex appt-display-mode-line
2288 @vindex appt-msg-window
2289 @vindex appt-display-duration
2290 @table @code
2291 @item appt-message-warning-time
2292 The time in minutes before an appointment that the reminder begins.  The
2293 default is 10 minutes.
2294 @item appt-audible
2295 If this is @code{t} (the default), Emacs rings the terminal bell for
2296 appointment reminders.
2297 @item appt-visible
2298 If this is @code{t} (the default), Emacs displays the appointment
2299 message in echo area.
2300 @item appt-display-mode-line
2301 If this is @code{t} (the default), Emacs displays the number of minutes
2302 to the appointment on the mode line.
2303 @item appt-msg-window
2304 If this is @code{t} (the default), Emacs displays the appointment
2305 message in another window.
2306 @item appt-display-duration
2307 The number of seconds an appointment message is displayed.  The default
2308 is 5 seconds.
2309 @end table