comparison lispref/calendar.texi @ 6387:b06d5c68be5a

Initial revision
author Richard M. Stallman <rms@gnu.org>
date Thu, 17 Mar 1994 19:28:09 +0000
parents
children afe506bf7264
comparison
equal deleted inserted replaced
6386:1eabdff45c61 6387:b06d5c68be5a
1 @c -*-texinfo-*-
2 @c This is part of the GNU Emacs Lisp Reference Manual.
3 @c Copyright (C) 1990, 1991, 1992, 1993 Free Software Foundation, Inc.
4 @c See the file elisp.texi for copying conditions.
5 @node Calendar, Tips, Display, Top
6 @chapter Customizing the Calendar and Diary
7
8 There are many customizations that you can use to make the calendar and
9 diary suit your personal tastes.
10
11 @menu
12 * Calendar Customizing:: Defaults you can set.
13 * Holiday Customizing:: Defining your own holidays.
14 * Date Display Format:: Changing the format.
15 * Time Display Format:: Changing the format.
16 * Daylight Savings:: Changing the default.
17 * Diary Customizing:: Defaults you can set.
18 * Hebrew/Islamic Entries:: How to obtain them.
19 * Fancy Diary Display:: Enhancing the diary display, sorting entries.
20 * Included Diary Files:: Sharing a common diary file.
21 * Sexp Diary Entries:: Fancy things you can do.
22 * Appt Customizing:: Customizing appointment reminders.
23 @end menu
24
25 @node Calendar Customizing
26 @section Customizing the Calendar
27 @vindex view-diary-entries-initially
28
29 If you set the variable @code{view-diary-entries-initially} to
30 @code{t}, calling up the calendar automatically displays the diary
31 entries for the current date as well. The diary dates appear only if
32 the current date is visible. If you add both of the following lines to
33 your @file{.emacs} file:@refill
34
35 @example
36 (setq view-diary-entries-initially t)
37 (calendar)
38 @end example
39
40 @noindent
41 they display both the calendar and diary windows whenever you start Emacs.
42
43 @vindex view-calendar-holidays-initially
44 Similarly, if you set the variable
45 @code{view-calendar-holidays-initially} to @code{t}, entering the
46 calendar automatically displays a list of holidays for the current three
47 month period. The holiday list appears in a separate window.@refill
48
49 @vindex mark-diary-entries-in-calendar
50 You can set the variable @code{mark-diary-entries-in-calendar} to @code{t}
51 in order to place a plus sign (@samp{+}) beside any dates with diary entries.
52 Whenever the calendar window is displayed or redisplayed, the diary entries
53 are automatically marked for holidays.
54
55 @vindex mark-holidays-in-calendar
56 Similarly, setting the variable @code{mark-holidays-in-calendar} to
57 @code{t} places an asterisk (@samp{*}) after all holiday dates visible
58 in the calendar window.
59
60 @vindex calendar-load-hook
61 There are many customizations that you can make with the hooks
62 provided. For example, the variable @code{calendar-load-hook}, whose
63 default value is @code{nil}, is a normal hook run when the calendar
64 package is first loaded (before actually starting to display the
65 calendar).
66
67 @vindex initial-calendar-window-hook
68 The variable @code{initial-calendar-window-hook}, whose default value
69 is @code{nil}, is a normal hook run the first time the calendar window
70 is displayed. The function is invoked only when you first enter
71 Calendar mode, not when you redisplay an existing Calendar window. But
72 if you leave the calendar with the @kbd{q} command and reenter it, the
73 hook runs again.@refill
74
75 @vindex today-visible-calendar-hook
76 The variable @code{today-visible-calendar-hook}, whose default value
77 is @code{nil}, is a normal hook run after the calendar buffer has been
78 prepared with the calendar when the current date is visible in the
79 window. One use of this hook is to replace today's date with asterisks;
80 a function @code{calendar-star-date} is included for this purpose. In
81 your @file{.emacs} file, put:@refill
82
83 @findex calendar-star-date
84 @example
85 (setq today-visible-calendar-hook 'calendar-star-date)
86 @end example
87
88 @noindent
89 Another standard hook function adds asterisks around the current date.
90 Here's how to use it:
91
92 @findex calendar-mark-today
93 @example
94 (setq today-visible-calendar-hook 'calendar-mark-today)
95 @end example
96
97 @vindex today-invisible-calendar-hook
98 @noindent
99 A corresponding variable, @code{today-invisible-calendar-hook}, whose
100 default value is @code{nil}, is a normal hook run after the calendar
101 buffer text has been prepared, if the current date is @emph{not} visible
102 in the window.@refill
103
104 @node Holiday Customizing
105 @section Customizing the Holidays
106
107 @vindex calendar-holidays
108 @vindex christian-holidays
109 @vindex hebrew-holidays
110 @vindex islamic-holidays
111 Emacs knows about holidays defined by entries on one of several lists.
112 You can customize theses lists of holidays to your own needs, adding
113 holidays or deleting lists of holidays. The lists of holidays that
114 Emacs uses are for general holidays (@code{general-holidays}), local
115 holidays (@code{local-holidays}), Christian holidays
116 (@code{christian-holidays}), Hebrew (Jewish) holidays
117 (@code{hebrew-holidays}), Islamic (Moslem) holidays
118 (@code{islamic-holidays}), and other holidays (@code{other-holidays}).
119
120 @vindex general-holidays
121 The general holidays are, by default, holidays common throughout the
122 United States. To eliminate these holidays, set @code{general-holidays}
123 to @code{nil}.
124
125 @vindex local-holidays
126 There are no default local holidays (but sites may supply some). You
127 can set the variable @code{local-holidays} to any list of holidays, as
128 described below.
129
130 @vindex all-christian-calendar-holidays
131 @vindex all-hebrew-calendar-holidays
132 @vindex all-islamic-calendar-holidays
133 By default, Emacs does not consider all the holidays of these
134 religions, only those commonly found in secular calendars. For a more
135 extensive collection of religious holidays, you can set any (or all) of
136 the variables @code{all-christian-calendar-holidays},
137 @code{all-hebrew-calendar-holidays}, or
138 @code{all-islamic-calendar-holidays} to @code{t}. If you want to
139 eliminate the religious holidays, set any or all of the corresponding
140 variables @code{christian-holidays}, @code{hebrew-holidays}, and
141 @code{islamic-holidays} to @code{nil}.@refill
142
143 @vindex other-holidays
144 You can set the variable @code{other-holidays} to any list of
145 holidays. This list, normally empty, is intended for your use.
146
147 @cindex holiday forms
148 Each of the lists (@code{general-holidays}, @code{local-holidays},
149 @code{christian-holidays}, @code{hebrew-holidays},
150 @code{islamic-holidays}, and @code{other-holidays}) is a list of
151 @dfn{holiday forms}, each holiday form describing a holiday (or
152 sometimes a list of holidays). Holiday forms may have the following
153 formats:
154
155 @table @code
156 @item (holiday-fixed @var{month} @var{day} @var{string})
157 A fixed date on the Gregorian calendar. @var{month} and @var{day} are
158 numbers, @var{string} is the name of the holiday.
159
160 @item (holiday-float @var{month} @var{dayname} @var{k} @var{string})
161 The @var{k}th @var{dayname} in @var{month} on the Gregorian calendar
162 (@var{dayname}=0 for Sunday, and so on); negative @var{k} means count back
163 from the end of the month. @var{string} is the name of the holiday.
164
165 @item (holiday-hebrew @var{month} @var{day} @var{string})
166 A fixed date on the Hebrew calendar. @var{month} and @var{day} are
167 numbers, @var{string} is the name of the holiday.
168
169 @item (holiday-islamic @var{month} @var{day} @var{string})
170 A fixed date on the Islamic calendar. @var{month} and @var{day} are
171 numbers, @var{string} is the name of the holiday.
172
173 @item (holiday-julian @var{month} @var{day} @var{string})
174 A fixed date on the Julian calendar. @var{month} and @var{day} are
175 numbers, @var{string} is the name of the holiday.
176
177 @item (holiday-sexp @var{sexp} @var{string})
178 @var{sexp} is a Lisp expression that should use the variable @code{year}
179 to compute the date of a holiday, or @code{nil} if the holiday doesn't
180 happen this year. The value represents the date as a list of the form
181 @code{(@var{month} @var{day} @var{year})}. @var{string} is the name of
182 the holiday.
183
184 @item (if @var{boolean} @var{holiday-form} &optional @var{holiday-form})
185 A choice between two holidays based on the value of @var{boolean}.
186
187 @item (@var{function} &optional @var{args})
188 Dates requiring special computation; @var{args}, if any, are passed in
189 a list to the function @code{calendar-holiday-function-@var{function}}.
190 @end table
191
192 For example, suppose you want to add Bastille Day, celebrated in
193 France on July 14. You can do this by adding the following line
194 to your @file{.emacs} file:
195
196 @smallexample
197 (setq other-holidays '((holiday-fixed 7 14 "Bastille Day")))
198 @end smallexample
199
200 @noindent
201 The holiday form @code{(holiday-fixed 7 14 "Bastille Day")} specifies the
202 fourteenth day of the seventh month (July).
203
204 Many holidays occur on a specific day of the week, at a specific time
205 of month. Here is a holiday form describing Hurricane Supplication Day,
206 celebrated in the Virgin Islands on the fourth Monday in August:
207
208 @smallexample
209 (holiday-float 8 1 4 "Hurricane Supplication Day")
210 @end smallexample
211
212 @noindent
213 Here the 8 specifies August, the 1 specifies Monday (Sunday is 0,
214 Tuesday is 2, and so on), and the 4 specifies the fourth occurrence in
215 the month (1 specifies the first occurrence, 2 the second occurrence,
216 @minus{}1 the last occurrence, @minus{}2 the second-to-last occurrence, and
217 so on).
218
219 You can specify holidays that occur on fixed days of the Hebrew,
220 Islamic, and Julian calendars too. For example,
221
222 @smallexample
223 (setq other-holidays
224 '((holiday-hebrew 10 2 "Last day of Hanukkah")
225 (holiday-islamic 3 12 "Mohammed's Birthday")
226 (holiday-julian 4 2 "Jefferson's Birthday")))
227 @end smallexample
228
229 @noindent
230 adds the last day of Hanukkah (since the Hebrew months are numbered with
231 1 starting from Nisan), the Islamic feast celebrating Mohammed's
232 birthday (since the Islamic months are numbered from 1 starting with
233 Muharram), and Thomas Jefferson's birthday, which is 2 April 1743 on the
234 Julian calendar.
235
236 To include a holiday conditionally, use either the @samp{if} or the
237 @samp{sexp} form. For example, American presidential elections occur on
238 the first Tuesday after the first Monday in November of years divisible
239 by 4:
240
241 @smallexample
242 (holiday-sexp (if (= 0 (% year 4))
243 (calendar-gregorian-from-absolute
244 (1+ (calendar-dayname-on-or-before
245 1 (+ 6 (calendar-absolute-from-gregorian
246 (list 11 1 year))))))
247 "US Presidential Election"))
248 @end smallexample
249
250 @noindent
251 or
252
253 @smallexample
254 (if (= 0 (% displayed-year 4))
255 (fixed 11
256 (extract-calendar-day
257 (calendar-gregorian-from-absolute
258 (1+ (calendar-dayname-on-or-before
259 1 (+ 6 (calendar-absolute-from-gregorian
260 (list 11 1 displayed-year)))))))
261 "US Presidential Election"))
262 @end smallexample
263
264 Some holidays just don't fit into any of these forms because special
265 calculations are involved in their determination. In such cases you
266 must write a Lisp function to do the calculation. To include
267 eclipses of the sun, for example, add @code{(eclipses)} to
268 @code{other-holidays} and write an Emacs Lisp function
269 @code{eclipses} that returns a (possibly
270 empty) list of the relevant Gregorian dates among the
271 range visible in the calendar window, with descriptive strings, like
272 this:
273
274 @smallexample
275 (((6 27 1991) "Lunar Eclipse") ((7 11 1991) "Solar Eclipse") ... )
276 @end smallexample
277
278 @node Date Display Format
279 @section Date Display Format
280 @vindex calendar-date-display-form
281
282 You can customize the manner of displaying dates in the diary,
283 in mode lines, and in messages by setting
284 @code{calendar-date-display-form}. This variable is a list of
285 expressions that can involve the variables @code{month}, @code{day}, and
286 @code{year}, all numbers in string form, and @code{monthname} and
287 @code{dayname}, both alphabetic strings. In the American style, the
288 default value of this list is as follows:
289
290 @smallexample
291 ((if dayname (concat dayname ", ")) monthname " " day ", " year)
292 @end smallexample
293
294 @noindent
295 while in the European style this value is the default:
296
297 @smallexample
298 ((if dayname (concat dayname ", ")) day " " monthname " " year)
299 @end smallexample
300
301 The ISO standard date representation is this:
302
303 @smallexample
304 (year "-" month "-" day)
305 @end smallexample
306
307 @noindent
308 This specifies a typical American format:
309
310 @smallexample
311 (month "/" day "/" (substring year -2))
312 @end smallexample
313
314 @node Time Display Format
315 @section Time Display Format
316 @vindex calendar-time-display-form
317
318 In the calendar, diary, and related buffers, Emacs displays times of
319 day in the conventional American style with the hours from 1 through 12,
320 minutes, and either @samp{am} or @samp{pm}. If you prefer the
321 ``military'' (European) style of writing times---in which the hours go
322 from 00 to 23---you can alter the variable
323 @code{calendar-time-display-form}. This variable is a list of
324 expressions that can involve the variables @code{12-hours},
325 @code{24-hours}, and @code{minutes}, all numbers in string form, and
326 @code{am-pm} and @code{time-zone}, both alphabetic strings. The default
327 definition of @code{calendar-time-display-form} is as follows:
328
329 @smallexample
330 (12-hours ":" minutes am-pm
331 (if time-zone " (") time-zone (if time-zone ")"))
332 @end smallexample
333
334 Setting @code{calendar-time-display-form} to
335
336 @smallexample
337 (24-hours ":" minutes
338 (if time-zone " (") time-zone (if time-zone ")"))
339 @end smallexample
340
341 @noindent
342 gives military-style times like @samp{21:07 (UT)} if time zone names are
343 defined, and times like @samp{21:07} if they are not.
344
345 @node Daylight Savings
346 @section Daylight Savings Time
347 @cindex daylight savings time
348
349 Emacs understands the difference between standard time and daylight
350 savings time---the times given for sunrise, sunset, solstices,
351 equinoxes, and the phases of the moon take that into account. The rules
352 for daylight savings time vary from place to place and have also varied
353 historically from year to year. To do the job properly, Emacs needs to
354 know which rules to use.
355
356 Some operating systems keep track of the rules that apply to the place
357 where you are; on these systems, Emacs gets the information it needs
358 from the system automatically. If some or all of this information is
359 missing, Emacs fills in the gaps with the rules currently used in
360 Cambridge, Massachusetts. If the default choice of rules is not
361 appropriate for your location, you can tell Emacs the rules to use by
362 setting certain variables.
363
364 @vindex calendar-daylight-savings-starts
365 @vindex calendar-daylight-savings-ends
366 These variables are @code{calendar-daylight-savings-starts} together
367 with @code{calendar-daylight-savings-ends}. Their values should be Lisp
368 expressions that refer to the variable @code{year}, and evaluate to the
369 Gregorian date on which daylight savings time starts or (respectively)
370 ends, in the form of a list @code{(@var{month} @var{day} @var{year})}.
371 The values should be @code{nil} if your area does not use daylight
372 savings time.
373
374 Emacs uses these expressions to determine the starting date of
375 daylight savings time for the holiday list and for correcting times of
376 day in the solar and lunar calculations.
377
378 The values for Cambridge, Massachusetts are as follows:
379
380 @example
381 @group
382 (calendar-nth-named-day 1 0 4 year)
383 (calendar-nth-named-day -1 0 10 year)
384 @end group
385 @end example
386
387 @noindent
388 i.e., the first 0th day (Sunday) of the fourth month (April) in
389 the year specified by @code{year}, and the last Sunday of the tenth month
390 (October) of that year. If daylight savings time were
391 changed to start on October 1, you would set
392 @code{calendar-daylight-savings-starts} to this:
393
394 @example
395 (list 10 1 year)
396 @end example
397
398 For a more complex example, suppose daylight savings time begins on
399 the first of Nisan on the Hebrew calendar. You would set
400 @code{calendar-daylight-savings-starts} as follows:
401
402 @example
403 (calendar-gregorian-from-absolute
404 (calendar-absolute-from-hebrew
405 (list 1 1 (+ year 3760))))
406 @end example
407
408 @noindent
409 because Nisan is the first month in the Hebrew calendar and the Hebrew
410 year differs from the Gregorian year by 3760 at Nisan.
411
412 If there is no daylight savings time at your location, or if you want
413 all times in standard time, set @code{calendar-daylight-savings-starts}
414 and @code{calendar-daylight-savings-ends} to @code{nil}.
415
416 @vindex calendar-daylight-time-offset
417 This variable specifies the difference between daylight savings time and
418 standard time, measured in minutes. The value for Cambridge is 60.
419
420 @vindex calendar-daylight-savings-starts-time
421 @vindex calendar-daylight-savings-ends-time
422 These variables specify is the number of minutes after midnight local time
423 when the transition to and from daylight savings time should occur. For
424 Cambridge, both variables' values are 120.
425
426 @node Diary Customizing
427 @section Customizing the Diary
428
429 @vindex holidays-in-diary-buffer
430 Ordinarily, the mode line of the diary buffer window indicates any
431 holidays that fall on the date of the diary entries. The process of
432 checking for holidays can take several seconds, so including holiday
433 information delays the display of the diary buffer noticeably. If you'd
434 prefer to have a faster display of the diary buffer but without the
435 holiday information, set the variable @code{holidays-in-diary-buffer} to
436 @code{nil}.@refill
437
438 @vindex number-of-diary-entries
439 The variable @code{number-of-diary-entries} controls the number of
440 days of diary entries to be displayed at one time. It affects the
441 initial display when @code{view-diary-entries-initially} is @code{t}, as
442 well as the command @kbd{M-x diary}. For example, the default value is
443 1, which says to display only the current day's diary entries. If the
444 value is 2, both the current day's and the next day's entries are
445 displayed. The value can also be a vector of seven elements: if the
446 value is @code{[0 2 2 2 2 4 1]} then no diary entries appear on Sunday,
447 the current date's and the next day's diary entries appear Monday
448 through Thursday, Friday through Monday's entries appear on Friday,
449 while on Saturday only that day's entries appear.
450
451 @vindex print-diary-entries-hook
452 @findex print-diary-entries
453 The variable @code{print-diary-entries-hook} is a normal hook run
454 after preparation of a temporary buffer containing just the diary
455 entries currently visible in the diary buffer. (The other, irrelevant
456 diary entries are really absent from the temporary buffer; in the diary
457 buffer, they are merely hidden.) The default value of this hook does
458 the printing with the command @code{lpr-buffer}. If you want to use a
459 different command to do the printing, just change the value of this
460 hook. Other uses might include, for example, rearranging the lines into
461 order by day and time.
462
463 @vindex diary-date-forms
464 You can customize the form of dates in your diary file, if neither the
465 standard American nor European styles suits your needs, by setting the
466 variable @code{diary-date-forms}. This variable is a list of forms of
467 dates recognized in the diary file. Each form is a list of regular
468 expressions (@pxref{Regular Expressions}) and the variables
469 @code{month}, @code{day}, @code{year}, @code{monthname}, and
470 @code{dayname}. The variable @code{monthname} matches the name of the
471 month, capitalized or not, or its three-letter abbreviation, followed by
472 a period or not; it matches @samp{*}. Similarly, @code{dayname} matches
473 the name of the day, capitalized or not, or its three-letter
474 abbreviation, followed by a period or not. The variables @code{month},
475 @code{day}, and @code{year} match those numerical values, preceded by
476 arbitrarily many zeros; they also match @samp{*}. The default value of
477 @code{diary-date-forms} in the American style is
478
479 @example
480 ((month "/" day "[^/0-9]")
481 (month "/" day "/" year "[^0-9]")
482 (monthname " *" day "[^,0-9]")
483 (monthname " *" day ", *" year "[^0-9]")
484 (dayname "\\W"))
485 @end example
486
487 @noindent
488 Emacs matches of the diary entries with the date forms is done with the
489 standard syntax table from Fundamental mode (@pxref{Syntax Tables}), but
490 with the @samp{*} changed so that it is a word constituent.
491
492 The forms on the list must be @emph{mutually exclusive} and must not
493 match any portion of the diary entry itself, just the date. If, to be
494 mutually exclusive, the pattern must match a portion of the diary entry
495 itself, the first element of the form @emph{must} be @code{backup}.
496 This causes the date recognizer to back up to the beginning of the
497 current word of the diary entry. Even if you use @code{backup}, the
498 form must absolutely not match more than a portion of the first word of
499 the diary entry. The default value of @code{diary-date-forms} in the
500 European style is this list:
501
502 @example
503 ((day "/" month "[^/0-9]")
504 (day "/" month "/" year "[^0-9]")
505 (backup day " *" monthname "\\W+\\<[^*0-9]")
506 (day " *" monthname " *" year "[^0-9]")
507 (dayname "\\W"))
508 @end example
509
510 @noindent
511 Notice the use of @code{backup} in the middle form because part of the
512 diary entry must be matched to distinguish this form from the following one.
513
514 @node Hebrew/Islamic Entries
515 @section Hebrew- and Islamic-Date Diary Entries
516
517 Your diary file can have entries based on Hebrew or Islamic dates, as
518 well as entries based on our usual Gregorian calendar. However, because
519 the processing of such entries is time-consuming and most people don't
520 need them, you must customize the processing of your diary file to
521 specify that you want such entries recognized. If you want Hebrew-date
522 diary entries, for example, you must include these lines in your
523 @file{.emacs} file:
524
525 @vindex nongregorian-diary-listing-hook
526 @vindex nongregorian-diary-marking-hook
527 @findex list-hebrew-diary-entries
528 @findex mark-hebrew-diary-entries
529 @smallexample
530 (setq nongregorian-diary-listing-hook 'list-hebrew-diary-entries)
531 (setq nongregorian-diary-marking-hook 'mark-hebrew-diary-entries)
532 @end smallexample
533
534 @noindent
535 If you want Islamic-date entries, include these lines in your
536 @file{.emacs} file:
537
538 @findex list-islamic-diary-entries
539 @findex mark-islamic-diary-entries
540 @smallexample
541 (setq nongregorian-diary-listing-hook 'list-islamic-diary-entries)
542 (setq nongregorian-diary-marking-hook 'mark-islamic-diary-entries)
543 @end smallexample
544
545 @noindent
546 If you want both Hebrew- and Islamic-date entries, include these lines:
547
548 @smallexample
549 (setq nongregorian-diary-listing-hook
550 '(list-hebrew-diary-entries list-islamic-diary-entries))
551 (setq nongregorian-diary-marking-hook
552 '(mark-hebrew-diary-entries mark-islamic-diary-entries))
553 @end smallexample
554
555 Hebrew- and Islamic-date diary entries have the same formats as
556 Gregorian-date diary entries, except that the date must be preceded with
557 an @samp{H} for Hebrew dates and an @samp{I} for Islamic dates.
558 Moreover, because the Hebrew and Islamic month names are not uniquely
559 specified by the first three letters, you may not abbreviate them. For
560 example, a diary entry for the Hebrew date Heshvan 25 could look like
561
562 @smallexample
563 HHeshvan 25 Happy Hebrew birthday!
564 @end smallexample
565
566 @noindent
567 and would appear in the diary for any date that corresponds to Heshvan 25
568 on the Hebrew calendar. Similarly, an Islamic-date diary entry might be
569
570 @smallexample
571 IDhu al-Qada 25 Happy Islamic birthday!
572 @end smallexample
573
574 @noindent
575 and would appear in the diary for any date that corresponds to Dhu al-Qada 25
576 on the Islamic calendar.
577
578 As with Gregorian-date diary entries, Hebrew- and Islamic-date entries
579 are nonmarking if they are preceded with an ampersand (@samp{&}).
580
581 There are commands to help you in making Hebrew- and Islamic-date
582 entries to your diary:
583
584 @table @kbd
585 @item i h d
586 Add a diary entry for the Hebrew date corresponding to the selected date
587 (@code{insert-hebrew-diary-entry}).
588 @item i h m
589 Add a diary entry for the day of the Hebrew month corresponding to the
590 selected date (@code{insert-monthly-hebrew-diary-entry}).
591 @item i h y
592 Add a diary entry for the day of the Hebrew year corresponding to the
593 selected date (@code{insert-yearly-hebrew-diary-entry}).
594 @item i i d
595 Add a diary entry for the Islamic date corresponding to the selected date
596 (@code{insert-islamic-diary-entry}).
597 @item i i m
598 Add a diary entry for the day of the Islamic month corresponding to the
599 selected date (@code{insert-monthly-islamic-diary-entry}).
600 @item i i y
601 Add a diary entry for the day of the Islamic year corresponding to the
602 selected date (@code{insert-yearly-islamic-diary-entry}).
603 @end table
604
605 @findex insert-hebrew-diary-entry
606 @findex insert-monthly-hebrew-diary-entry
607 @findex insert-yearly-hebrew-diary-entry
608 @findex insert-islamic-diary-entry
609 @findex insert-monthly-islamic-diary-entry
610 @findex insert-yearly-islamic-diary-entry
611 These commands work exactly like the corresponding commands for ordinary
612 diary entries: Move point to a date in the calendar window and the above
613 commands insert the Hebrew or Islamic date (corresponding to the date
614 indicated by point) at the end of your diary file and you can then type the
615 diary entry. If you want the diary entry to be nonmarking, give a numeric
616 argument to the command.
617
618 @node Fancy Diary Display
619 @section Fancy Diary Display
620 @vindex diary-display-hook
621 @findex simple-diary-display
622
623 Diary display works by preparing the diary buffer and then running the
624 hook @code{diary-display-hook}. The default value of this hook hides
625 the irrelevant diary entries and then displays the buffer
626 (@code{simple-diary-display}). However, if you specify the hook as
627 follows,
628
629 @cindex diary buffer
630 @findex fancy-diary-display
631 @example
632 (add-hook 'diary-display-hook 'fancy-diary-display)
633 @end example
634
635 @noindent
636 then fancy mode displays diary entries and holidays by copying them into
637 a special buffer that exists only for display. Copying provides an
638 opportunity to change the displayed text to make it prettier---for
639 example, to sort the entries by the dates they apply to.
640
641 As with simple diary display, you can print a hard copy of the buffer
642 with @code{print-diary-entries}. To print a hard copy of a day-by-day
643 diary for a week by positioning point on Sunday of that week, type
644 @kbd{7 d} and then do @kbd{M-x print-diary-entries}. As usual, the
645 inclusion of the holidays slows down the display slightly; you can speed
646 things up by setting the variable @code{holidays-in-diary-buffer} to
647 @code{nil}.
648
649 @vindex diary-list-include-blanks
650 Ordinarily, the fancy diary buffer does not show days for which there are
651 no diary entries, even if that day is a holiday. If you want such days to be
652 shown in the fancy diary buffer, set the variable
653 @code{diary-list-include-blanks} to @code{t}.@refill
654
655 @cindex sorting diary entries
656 If you use the fancy diary display, you can use the normal hook
657 @code{list-diary-entries-hook} to sort each day's diary entries by their
658 time of day. Add this line to your @file{.emacs} file:
659
660 @findex sort-diary-entries
661 @example
662 (add-hook 'list-diary-entries-hook 'sort-diary-entries)
663 @end example
664
665 @noindent
666 For each day, this sorts diary entries that begin with a recognizable
667 time of day according to their times. Diary entries without times come
668 first within each day.
669
670 @node Included Diary Files
671 @section Included Diary Files
672
673 If you use the fancy diary display, you can have diary entries from other
674 files included with your own by an ``include'' mechanism. This facility makes
675 possible the sharing of common diary files among groups of users. Lines in
676 the diary file of this form:
677
678 @smallexample
679 #include "@var{filename}"
680 @end smallexample
681
682 @noindent
683 includes the diary entries from the file @var{filename} in the fancy
684 diary buffer (because the ordinary diary buffer is just the buffer
685 associated with your diary file, you cannot use the include mechanism
686 unless you use the fancy diary buffer). The include mechanism is
687 recursive, by the way, so that included files can include other files,
688 and so on; you must be careful not to have a cycle of inclusions, of
689 course. To enable the include facility, add lines as follows to your
690 @file{.emacs} file:
691
692 @vindex list-diary-entries-hook
693 @vindex mark-diary-entries-hook
694 @findex include-other-diary-files
695 @findex mark-included-diary-files
696 @smallexample
697 (add-hook 'list-diary-entries-hook 'include-other-diary-files)
698 (add-hook 'mark-diary-entries-hook 'mark-included-diary-files)
699 @end smallexample
700
701 @node Sexp Diary Entries
702 @section Sexp Entries and the Fancy Diary Display
703 @cindex sexp diary entries
704
705 Sexp diary entries allow you to do more than just have complicated
706 conditions under which a diary entry applies. If you use the fancy
707 diary display, sexp entries can generate the text of the entry depending
708 on the date itself. For example, an anniversary diary entry can insert
709 the number of years since the anniversary date into the text of the
710 diary entry. Thus the @samp{%d} in this dairy entry:
711
712 @findex diary-anniversary
713 @smallexample
714 %%(diary-anniversary 10 31 1948) Arthur's birthday (%d years old)
715 @end smallexample
716
717 @noindent
718 gets replaced by the age, so on October 31, 1990 the entry appears in
719 the fancy diary buffer like this:
720
721 @smallexample
722 Arthur's birthday (42 years old)
723 @end smallexample
724
725 @noindent
726 If the diary file instead contains this entry:
727
728 @smallexample
729 %%(diary-anniversary 10 31 1948) Arthur's %d%s birthday
730 @end smallexample
731
732 @noindent
733 the entry in the fancy diary buffer for October 31, 1990 appears like this:
734
735 @smallexample
736 Arthur's 42nd birthday
737 @end smallexample
738
739 Similarly, cyclic diary entries can interpolate the number of repetitions
740 that have occurred:
741
742 @findex diary-cyclic
743 @smallexample
744 %%(diary-cyclic 50 1 1 1990) Renew medication (%d%s time)
745 @end smallexample
746
747 @noindent
748 looks like this:
749
750 @smallexample
751 Renew medication (5th time)
752 @end smallexample
753
754 @noindent
755 in the fancy diary display on September 8, 1990.
756
757 The generality of sexp diary entries lets you specify any diary entry
758 that you can describe algorithmically. Suppose you get paid on the 21st
759 of the month if it is a weekday, and to the Friday before if the 21st is
760 on a weekend. The diary entry
761
762 @smallexample
763 &%%(let ((dayname (calendar-day-of-week date))
764 (day (car (cdr date))))
765 (or (and (= day 21) (memq dayname '(1 2 3 4 5)))
766 (and (memq day '(19 20)) (= dayname 5)))
767 ) Pay check deposited
768 @end smallexample
769
770 @noindent
771 applies to just those dates. This example illustrates how the sexp can
772 depend on the variable @code{date}; this variable is a list (@var{month}
773 @var{day} @var{year}) that gives the Gregorian date for which the diary
774 entries are being found. If the value of the expression is @code{t},
775 the entry applies to that date. If the expression evaluates to
776 @code{nil}, the entry does @emph{not} apply to that date.
777
778 The following sexp diary entries take advantage of the ability (in the fancy
779 diary display) to concoct diary entries based on the date:
780
781 @findex diary-sunrise-sunset
782 @findex diary-phases-of-moon
783 @findex diary-day-of-year
784 @findex diary-iso-date
785 @findex diary-julian-date
786 @findex diary-astro-day-number
787 @findex diary-hebrew-date
788 @findex diary-islamic-date
789 @findex diary-french-date
790 @findex diary-mayan-date
791 @table @code
792 @item %%(diary-sunrise-sunset)
793 Make a diary entry for the local times of today's sunrise and sunset.
794 @item %%(diary-phases-of-moon)
795 Make a diary entry for the phases (quarters) of the moon.
796 @item %%(diary-day-of-year)
797 Make a diary entry with today's day number in the current year and the number
798 of days remaining in the current year.
799 @item %%(diary-iso-date)
800 Make a diary entry with today's equivalent ISO commercial date.
801 @item %%(diary-julian-date)
802 Make a diary entry with today's equivalent date on the Julian calendar.
803 @item %%(diary-astro-day-number)
804 Make a diary entry with today's equivalent astronomical (Julian) day number.
805 @item %%(diary-hebrew-date)
806 Make a diary entry with today's equivalent date on the Hebrew calendar.
807 @item %%(diary-islamic-date)
808 Make a diary entry with today's equivalent date on the Islamic calendar.
809 @item %%(diary-french-date)
810 Make a diary entry with today's equivalent date on the French Revolutionary
811 calendar.
812 @item %%(diary-mayan-date)
813 Make a diary entry with today's equivalent date on the Mayan calendar.
814 @end table
815
816 @noindent
817 Thus including the diary entry
818
819 @smallexample
820 &%%(diary-hebrew-date)
821 @end smallexample
822
823 @noindent
824 causes every day's diary display to contain the equivalent date on the
825 Hebrew calendar, if you are using the fancy diary display. (With simple
826 diary display, the line @samp{&%%(diary-hebrew-date)} appears in the
827 diary for any date, but does nothing particularly useful.)
828
829 There are a number of other available sexp diary entries that are important
830 to those who follow the Hebrew calendar:
831
832 @cindex rosh hodesh
833 @findex diary-rosh-hodesh
834 @cindex parasha, weekly
835 @findex diary-parasha
836 @cindex candle lighting times
837 @findex diary-sabbath-candles
838 @cindex omer count
839 @findex diary-omer
840 @cindex yahrzeits
841 @findex diary-yahrzeit
842 @table @code
843 @item %%(diary-rosh-hodesh)
844 Make a diary entry that tells the occurrence and ritual announcement of each
845 new Hebrew month.
846 @item %%(diary-parasha)
847 Make a Saturday diary entry that tells the weekly synagogue scripture reading.
848 @item %%(diary-sabbath-candles)
849 Make a Friday diary entry that tells the @emph{local time} of Sabbath
850 candle lighting.
851 @item %%(diary-omer)
852 Make a diary entry that gives the omer count, when appropriate.
853 @item %%(diary-yahrzeit @var{month} @var{day} @var{year}) @var{name}
854 Make a diary entry marking the anniversary of a date of death. The date
855 is the @emph{Gregorian} (civil) date of death. The diary entry appears
856 on the proper Hebrew calendar anniversary and on the day before. (In
857 the European style, the order of the parameters is changed to @var{day},
858 @var{month}, @var{year}.)
859 @end table
860
861 @node Appt Customizing
862 @section Customizing Appointment Reminders
863
864 You can specify exactly how Emacs reminds you of an appointment and
865 how far in advance it begins doing so. Here are the variables that you
866 can set:
867
868 @vindex appt-message-warning-time
869 @vindex appt-audible
870 @vindex appt-visible
871 @vindex appt-display-mode-line
872 @vindex appt-msg-window
873 @vindex appt-display-duration
874 @table @code
875 @item appt-message-warning-time
876 The time in minutes before an appointment that the reminder begins. The
877 default is 10 minutes.
878 @item appt-audible
879 If this is @code{t} (the default), Emacs rings the terminal bell for
880 appointment reminders.
881 @item appt-visible
882 If this is @code{t} (the default), Emacs displays the appointment
883 message in echo area.
884 @item appt-display-mode-line
885 If this is @code{t} (the default), Emacs displays the number of minutes
886 to the appointment on the mode line.
887 @item appt-msg-window
888 If this is @code{t} (the default), Emacs displays the appointment
889 message in another window.
890 @item appt-display-duration
891 The number of seconds an appointment message is displayed. The default
892 is 5 seconds.
893 @end table