(apropos-score-doc): Prevent division by zero.
[emacs.git] / man / calendar.texi
blobba4b582bbecaa4eaad2f825ed1f9154b33e2a11e
1 @c This is part of the Emacs manual.
2 @c Copyright (C) 1985,86,87,93,94,95,1997,2000,2001 Free Software Foundation, Inc.
3 @c See file emacs.texi for copying conditions.
4 @node Calendar/Diary, Gnus, Dired, Top
5 @chapter The Calendar and the Diary
6 @cindex calendar
7 @findex calendar
9   Emacs provides the functions of a desk calendar, with a diary of
10 planned or past events.  It also has facilities for managing your
11 appointments, and keeping track of how much time you spend working on
12 certain projects.
14   To enter the calendar, type @kbd{M-x calendar}; this displays a
15 three-month calendar centered on the current month, with point on the
16 current date.  With a numeric argument, as in @kbd{C-u M-x calendar}, it
17 prompts you for the month and year to be the center of the three-month
18 calendar.  The calendar uses its own buffer, whose major mode is
19 Calendar mode.
21   @kbd{Mouse-2} in the calendar brings up a menu of operations on a
22 particular date; @kbd{C-Mouse-3} brings up a menu of commonly used
23 calendar features that are independent of any particular date.  To exit
24 the calendar, type @kbd{q}.  @xref{Calendar, Customizing the Calendar
25 and Diary,, elisp, The Emacs Lisp Reference Manual}, for customization
26 information about the calendar and diary.
28 @menu
29 * Calendar Motion::     Moving through the calendar; selecting a date.
30 * Scroll Calendar::     Bringing earlier or later months onto the screen.
31 * Counting Days::       How many days are there between two dates?
32 * General Calendar::    Exiting or recomputing the calendar.
33 * LaTeX Calendar::      Print a calendar using LaTeX.
34 * Holidays::            Displaying dates of holidays.
35 * Sunrise/Sunset::      Displaying local times of sunrise and sunset.
36 * Lunar Phases::        Displaying phases of the moon.
37 * Other Calendars::     Converting dates to other calendar systems.
38 * Diary::               Displaying events from your diary.
39 * Appointments::        Reminders when it's time to do something.
40 * iCalendar::           Converting diary events to/from iCalendar format.
41 * Daylight Savings::    How to specify when daylight savings time is active.
42 * Time Intervals::      Keeping track of time intervals.
43 @end menu
45 @node Calendar Motion
46 @section Movement in the Calendar
48 @cindex moving inside the calendar
49   Calendar mode lets you move through the calendar in logical units of
50 time such as days, weeks, months, and years.  If you move outside the
51 three months originally displayed, the calendar display ``scrolls''
52 automatically through time to make the selected date visible.  Moving to
53 a date lets you view its holidays or diary entries, or convert it to other
54 calendars; moving longer time periods is also useful simply to scroll the
55 calendar.
57 @menu
58 * Calendar Unit Motion::      Moving by days, weeks, months, and years.
59 * Move to Beginning or End::  Moving to start/end of weeks, months, and years.
60 * Specified Dates::           Moving to the current date or another
61                                 specific date.
62 @end menu
64 @node Calendar Unit Motion
65 @subsection Motion by Standard Lengths of Time
67   The commands for movement in the calendar buffer parallel the
68 commands for movement in text.  You can move forward and backward by
69 days, weeks, months, and years.
71 @table @kbd
72 @item C-f
73 Move point one day forward (@code{calendar-forward-day}).
74 @item C-b
75 Move point one day backward (@code{calendar-backward-day}).
76 @item C-n
77 Move point one week forward (@code{calendar-forward-week}).
78 @item C-p
79 Move point one week backward (@code{calendar-backward-week}).
80 @item M-@}
81 Move point one month forward (@code{calendar-forward-month}).
82 @item M-@{
83 Move point one month backward (@code{calendar-backward-month}).
84 @item C-x ]
85 Move point one year forward (@code{calendar-forward-year}).
86 @item C-x [
87 Move point one year backward (@code{calendar-backward-year}).
88 @end table
90 @kindex C-f @r{(Calendar mode)}
91 @findex calendar-forward-day
92 @kindex C-b @r{(Calendar mode)}
93 @findex calendar-backward-day
94 @kindex C-n @r{(Calendar mode)}
95 @findex calendar-forward-week
96 @kindex C-p @r{(Calendar mode)}
97 @findex calendar-backward-week
98   The day and week commands are natural analogues of the usual Emacs
99 commands for moving by characters and by lines.  Just as @kbd{C-n}
100 usually moves to the same column in the following line, in Calendar
101 mode it moves to the same day in the following week.  And @kbd{C-p}
102 moves to the same day in the previous week.
104   The arrow keys are equivalent to @kbd{C-f}, @kbd{C-b}, @kbd{C-n} and
105 @kbd{C-p}, just as they normally are in other modes.
107 @kindex M-@} @r{(Calendar mode)}
108 @findex calendar-forward-month
109 @kindex M-@{ @r{(Calendar mode)}
110 @findex calendar-backward-month
111 @kindex C-x ] @r{(Calendar mode)}
112 @findex calendar-forward-year
113 @kindex C-x [ @r{(Calendar mode)}
114 @findex calendar-forward-year
115   The commands for motion by months and years work like those for
116 weeks, but move a larger distance.  The month commands @kbd{M-@}} and
117 @kbd{M-@{} move forward or backward by an entire month's time.  The
118 year commands @kbd{C-x ]} and @w{@kbd{C-x [}} move forward or backward a
119 whole year.
121   The easiest way to remember these commands is to consider months and
122 years analogous to paragraphs and pages of text, respectively.  But the
123 commands themselves are not quite analogous.  The ordinary Emacs paragraph
124 commands move to the beginning or end of a paragraph, whereas these month
125 and year commands move by an entire month or an entire year, which usually
126 involves skipping across the end of a month or year.
128   All these commands accept a numeric argument as a repeat count.
129 For convenience, the digit keys and the minus sign specify numeric
130 arguments in Calendar mode even without the Meta modifier.  For example,
131 @kbd{100 C-f} moves point 100 days forward from its present location.
133 @node Move to Beginning or End
134 @subsection Beginning or End of Week, Month or Year
136   A week (or month, or year) is not just a quantity of days; we think of
137 weeks (months, years) as starting on particular dates.  So Calendar mode
138 provides commands to move to the beginning or end of a week, month or
139 year:
141 @table @kbd
142 @kindex C-a @r{(Calendar mode)}
143 @findex calendar-beginning-of-week
144 @item C-a
145 Move point to start of week (@code{calendar-beginning-of-week}).
146 @kindex C-e @r{(Calendar mode)}
147 @findex calendar-end-of-week
148 @item C-e
149 Move point to end of week (@code{calendar-end-of-week}).
150 @kindex M-a @r{(Calendar mode)}
151 @findex calendar-beginning-of-month
152 @item M-a
153 Move point to start of month (@code{calendar-beginning-of-month}).
154 @kindex M-e @r{(Calendar mode)}
155 @findex calendar-end-of-month
156 @item M-e
157 Move point to end of month (@code{calendar-end-of-month}).
158 @kindex M-< @r{(Calendar mode)}
159 @findex calendar-beginning-of-year
160 @item M-<
161 Move point to start of year (@code{calendar-beginning-of-year}).
162 @kindex M-> @r{(Calendar mode)}
163 @findex calendar-end-of-year
164 @item M->
165 Move point to end of year (@code{calendar-end-of-year}).
166 @end table
168   These commands also take numeric arguments as repeat counts, with the
169 repeat count indicating how many weeks, months, or years to move
170 backward or forward.
172 @vindex calendar-week-start-day
173 @cindex weeks, which day they start on
174 @cindex calendar, first day of week
175   By default, weeks begin on Sunday.  To make them begin on Monday
176 instead, set the variable @code{calendar-week-start-day} to 1.
178 @node Specified Dates
179 @subsection Specified Dates
181   Calendar mode provides commands for moving to a particular date
182 specified in various ways.
184 @table @kbd
185 @item g d
186 Move point to specified date (@code{calendar-goto-date}).
187 @item g D
188 Move point to specified day of year (@code{calendar-goto-day-of-year}).
189 @item o
190 Center calendar around specified month (@code{calendar-other-month}).
191 @item .
192 Move point to today's date (@code{calendar-goto-today}).
193 @end table
195 @kindex g d @r{(Calendar mode)}
196 @findex calendar-goto-date
197   @kbd{g d} (@code{calendar-goto-date}) prompts for a year, a month, and a day
198 of the month, and then moves to that date.  Because the calendar includes all
199 dates from the beginning of the current era, you must type the year in its
200 entirety; that is, type @samp{1990}, not @samp{90}.
202 @kindex g D @r{(Calendar mode)}
203 @findex calendar-goto-day-of-year
204   @kbd{g D} (@code{calendar-goto-day-of-year}) prompts for a year and
205 day number, and moves to that date.  Negative day numbers count backward
206 from the end of the year.
208 @kindex o @r{(Calendar mode)}
209 @findex calendar-other-month
210   @kbd{o} (@code{calendar-other-month}) prompts for a month and year,
211 then centers the three-month calendar around that month.
213 @kindex . @r{(Calendar mode)}
214 @findex calendar-goto-today
215   You can return to today's date with @kbd{.}@:
216 (@code{calendar-goto-today}).
218 @node Scroll Calendar
219 @section Scrolling in the Calendar
221 @cindex scrolling in the calendar
222   The calendar display scrolls automatically through time when you
223 move out of the visible portion.  You can also scroll it manually.
224 Imagine that the calendar window contains a long strip of paper with
225 the months on it.  Scrolling the calendar means moving the strip
226 horizontally, so that new months become visible in the window.
228 @table @kbd
229 @item C-x <
230 Scroll calendar one month forward (@code{scroll-calendar-left}).
231 @item C-x >
232 Scroll calendar one month backward (@code{scroll-calendar-right}).
233 @item C-v
234 @itemx @key{NEXT}
235 Scroll calendar three months forward
236 (@code{scroll-calendar-left-three-months}).
237 @item M-v
238 @itemx @key{PRIOR}
239 Scroll calendar three months backward
240 (@code{scroll-calendar-right-three-months}).
241 @end table
243 @kindex C-x < @r{(Calendar mode)}
244 @findex scroll-calendar-left
245 @kindex C-x > @r{(Calendar mode)}
246 @findex scroll-calendar-right
247   The most basic calendar scroll commands scroll by one month at a
248 time.  This means that there are two months of overlap between the
249 display before the command and the display after.  @kbd{C-x <} scrolls
250 the calendar contents one month to the left; that is, it moves the
251 display forward in time.  @kbd{C-x >} scrolls the contents to the
252 right, which moves backwards in time.
254 @kindex C-v @r{(Calendar mode)}
255 @findex scroll-calendar-left-three-months
256 @kindex M-v @r{(Calendar mode)}
257 @findex scroll-calendar-right-three-months
258   The commands @kbd{C-v} and @kbd{M-v} scroll the calendar by an entire
259 ``screenful''---three months---in analogy with the usual meaning of
260 these commands.  @kbd{C-v} makes later dates visible and @kbd{M-v} makes
261 earlier dates visible.  These commands take a numeric argument as a
262 repeat count; in particular, since @kbd{C-u} multiplies the next command
263 by four, typing @kbd{C-u C-v} scrolls the calendar forward by a year and
264 typing @kbd{C-u M-v} scrolls the calendar backward by a year.
266   The function keys @key{NEXT} and @key{PRIOR} are equivalent to
267 @kbd{C-v} and @kbd{M-v}, just as they are in other modes.
269 @node Counting Days
270 @section Counting Days
272 @table @kbd
273 @item M-=
274 Display the number of days in the current region
275 (@code{calendar-count-days-region}).
276 @end table
278 @kindex M-= @r{(Calendar mode)}
279 @findex calendar-count-days-region
280   To determine the number of days in the region, type @kbd{M-=}
281 (@code{calendar-count-days-region}).  The numbers of days shown is
282 @emph{inclusive}; that is, it includes the days specified by mark and
283 point.
285 @node General Calendar
286 @section Miscellaneous Calendar Commands
288 @table @kbd
289 @item p d
290 Display day-in-year (@code{calendar-print-day-of-year}).
291 @item C-c C-l
292 Regenerate the calendar window (@code{redraw-calendar}).
293 @item SPC
294 Scroll the next window (@code{scroll-other-window}).
295 @item q
296 Exit from calendar (@code{exit-calendar}).
297 @end table
299 @kindex p d @r{(Calendar mode)}
300 @cindex day of year
301 @findex calendar-print-day-of-year
302   To display the number of days elapsed since the start of the year, or
303 the number of days remaining in the year, type the @kbd{p d} command
304 (@code{calendar-print-day-of-year}).  This displays both of those
305 numbers in the echo area.  The number of days elapsed includes the
306 selected date.  The number of days remaining does not include that
307 date.
309 @kindex C-c C-l @r{(Calendar mode)}
310 @findex redraw-calendar
311   If the calendar window text gets corrupted, type @kbd{C-c C-l}
312 (@code{redraw-calendar}) to redraw it.  (This can only happen if you use
313 non-Calendar-mode editing commands.)
315 @kindex SPC @r{(Calendar mode)}
316   In Calendar mode, you can use @kbd{SPC} (@code{scroll-other-window})
317 to scroll the other window.  This is handy when you display a list of
318 holidays or diary entries in another window.
320 @kindex q @r{(Calendar mode)}
321 @findex exit-calendar
322   To exit from the calendar, type @kbd{q} (@code{exit-calendar}).  This
323 buries all buffers related to the calendar, selecting other buffers.
324 (If a frame contains a dedicated calendar window, exiting from the
325 calendar iconifies that frame.)
327 @node LaTeX Calendar
328 @section LaTeX Calendar
329 @cindex calendar and La@TeX{}
331    The Calendar La@TeX{} commands produce a buffer of La@TeX{} code that
332 prints as a calendar.  Depending on the command you use, the printed
333 calendar covers the day, week, month or year that point is in.
335 @kindex t @r{(Calendar mode)}
336 @table @kbd
337 @item t m
338 Generate a one-month calendar (@code{cal-tex-cursor-month}).
339 @item t M
340 Generate a sideways-printing one-month calendar
341 (@code{cal-tex-cursor-month-landscape}).
342 @item t d
343 Generate a one-day calendar
344 (@code{cal-tex-cursor-day}).
345 @item t w 1
346 Generate a one-page calendar for one week
347 (@code{cal-tex-cursor-week}).
348 @item t w 2
349 Generate a two-page calendar for one week
350 (@code{cal-tex-cursor-week2}).
351 @item t w 3
352 Generate an ISO-style calendar for one week
353 (@code{cal-tex-cursor-week-iso}).
354 @item t w 4
355 Generate a calendar for one Monday-starting week
356 (@code{cal-tex-cursor-week-monday}).
357 @item t f w
358 Generate a Filofax-style two-weeks-at-a-glance calendar
359 (@code{cal-tex-cursor-filofax-2week}).
360 @item t f W
361 Generate a Filofax-style one-week-at-a-glance calendar
362 (@code{cal-tex-cursor-filofax-week}).
363 @item t y
364 Generate a calendar for one year
365 (@code{cal-tex-cursor-year}).
366 @item t Y
367 Generate a sideways-printing calendar for one year
368 (@code{cal-tex-cursor-year-landscape}).
369 @item t f y
370 Generate a Filofax-style calendar for one year
371 (@code{cal-tex-cursor-filofax-year}).
372 @end table
374   Some of these commands print the calendar sideways (in ``landscape
375 mode''), so it can be wider than it is long.  Some of them use Filofax
376 paper size (3.75in x 6.75in).  All of these commands accept a prefix
377 argument which specifies how many days, weeks, months or years to print
378 (starting always with the selected one).
380   If the variable @code{cal-tex-holidays} is non-@code{nil} (the default),
381 then the printed calendars show the holidays in @code{calendar-holidays}.
382 If the variable @code{cal-tex-diary} is non-@code{nil} (the default is
383 @code{nil}), diary entries are included also (in weekly and monthly
384 calendars only).  If the variable @code{cal-tex-rules} is non-@code{nil}
385 (the default is @code{nil}), the calendar displays ruled pages
386 in styles that have sufficient room.
388 @node Holidays
389 @section Holidays
390 @cindex holidays
392   The Emacs calendar knows about all major and many minor holidays,
393 and can display them.
395 @table @kbd
396 @item h
397 Display holidays for the selected date
398 (@code{calendar-cursor-holidays}).
399 @item Mouse-2 Holidays
400 Display any holidays for the date you click on.
401 @item x
402 Mark holidays in the calendar window (@code{mark-calendar-holidays}).
403 @item u
404 Unmark calendar window (@code{calendar-unmark}).
405 @item a
406 List all holidays for the displayed three months in another window
407 (@code{list-calendar-holidays}).
408 @item M-x holidays
409 List all holidays for three months around today's date in another
410 window.
411 @item M-x list-holidays
412 List holidays in another window for a specified range of years.
413 @end table
415 @kindex h @r{(Calendar mode)}
416 @findex calendar-cursor-holidays
417   To see if any holidays fall on a given date, position point on that
418 date in the calendar window and use the @kbd{h} command.  Alternatively,
419 click on that date with @kbd{Mouse-2} and then choose @kbd{Holidays}
420 from the menu that appears.  Either way, this displays the holidays for
421 that date, in the echo area if they fit there, otherwise in a separate
422 window.
424 @kindex x @r{(Calendar mode)}
425 @findex mark-calendar-holidays
426 @kindex u @r{(Calendar mode)}
427 @findex calendar-unmark
428   To view the distribution of holidays for all the dates shown in the
429 calendar, use the @kbd{x} command.  This displays the dates that are
430 holidays in a different face (or places a @samp{*} after these dates, if
431 display with multiple faces is not available).  The command applies both
432 to the currently visible months and to other months that subsequently
433 become visible by scrolling.  To turn marking off and erase the current
434 marks, type @kbd{u}, which also erases any diary marks (@pxref{Diary}).
436 @kindex a @r{(Calendar mode)}
437 @findex list-calendar-holidays
438   To get even more detailed information, use the @kbd{a} command, which
439 displays a separate buffer containing a list of all holidays in the
440 current three-month range.  You can use @key{SPC} in the calendar window
441 to scroll that list.
443 @findex holidays
444   The command @kbd{M-x holidays} displays the list of holidays for the
445 current month and the preceding and succeeding months; this works even
446 if you don't have a calendar window.  If you want the list of holidays
447 centered around a different month, use @kbd{C-u M-x holidays}, which
448 prompts for the month and year.
450   The holidays known to Emacs include United States holidays and the
451 major Christian, Jewish, and Islamic holidays; also the solstices and
452 equinoxes.
454 @findex list-holidays
455    The command @kbd{M-x list-holidays} displays the list of holidays for
456 a range of years.  This function asks you for the starting and stopping
457 years, and allows you to choose all the holidays or one of several
458 categories of holidays.  You can use this command even if you don't have
459 a calendar window.
461   The dates used by Emacs for holidays are based on @emph{current
462 practice}, not historical fact.  Historically, for instance, the start
463 of daylight savings time and even its existence have varied from year to
464 year, but present United States law mandates that daylight savings time
465 begins on the first Sunday in April.  When the daylight savings rules
466 are set up for the United States, Emacs always uses the present
467 definition, even though it is wrong for some prior years.
469 @node Sunrise/Sunset
470 @section Times of Sunrise and Sunset
471 @cindex sunrise and sunset
473   Special calendar commands can tell you, to within a minute or two, the
474 times of sunrise and sunset for any date.
476 @table @kbd
477 @item S
478 Display times of sunrise and sunset for the selected date
479 (@code{calendar-sunrise-sunset}).
480 @item Mouse-2 Sunrise/sunset
481 Display times of sunrise and sunset for the date you click on.
482 @item M-x sunrise-sunset
483 Display times of sunrise and sunset for today's date.
484 @item C-u M-x sunrise-sunset
485 Display times of sunrise and sunset for a specified date.
486 @end table
488 @kindex S @r{(Calendar mode)}
489 @findex calendar-sunrise-sunset
490 @findex sunrise-sunset
491   Within the calendar, to display the @emph{local times} of sunrise and
492 sunset in the echo area, move point to the date you want, and type
493 @kbd{S}.  Alternatively, click @kbd{Mouse-2} on the date, then choose
494 @samp{Sunrise/sunset} from the menu that appears.  The command @kbd{M-x
495 sunrise-sunset} is available outside the calendar to display this
496 information for today's date or a specified date.  To specify a date
497 other than today, use @kbd{C-u M-x sunrise-sunset}, which prompts for
498 the year, month, and day.
500   You can display the times of sunrise and sunset for any location and
501 any date with @kbd{C-u C-u M-x sunrise-sunset}.  This asks you for a
502 longitude, latitude, number of minutes difference from Coordinated
503 Universal Time, and date, and then tells you the times of sunrise and
504 sunset for that location on that date.
506   Because the times of sunrise and sunset depend on the location on
507 earth, you need to tell Emacs your latitude, longitude, and location
508 name before using these commands.  Here is an example of what to set:
510 @vindex calendar-location-name
511 @vindex calendar-longitude
512 @vindex calendar-latitude
513 @example
514 (setq calendar-latitude 40.1)
515 (setq calendar-longitude -88.2)
516 (setq calendar-location-name "Urbana, IL")
517 @end example
519 @noindent
520 Use one decimal place in the values of @code{calendar-latitude} and
521 @code{calendar-longitude}.
523   Your time zone also affects the local time of sunrise and sunset.
524 Emacs usually gets time zone information from the operating system, but
525 if these values are not what you want (or if the operating system does
526 not supply them), you must set them yourself.  Here is an example:
528 @vindex calendar-time-zone
529 @vindex calendar-standard-time-zone-name
530 @vindex calendar-daylight-time-zone-name
531 @example
532 (setq calendar-time-zone -360)
533 (setq calendar-standard-time-zone-name "CST")
534 (setq calendar-daylight-time-zone-name "CDT")
535 @end example
537 @noindent
538 The value of @code{calendar-time-zone} is the number of minutes
539 difference between your local standard time and Coordinated Universal
540 Time (Greenwich time).  The values of
541 @code{calendar-standard-time-zone-name} and
542 @code{calendar-daylight-time-zone-name} are the abbreviations used in
543 your time zone.  Emacs displays the times of sunrise and sunset
544 @emph{corrected for daylight savings time}.  @xref{Daylight Savings},
545 for how daylight savings time is determined.
547   As a user, you might find it convenient to set the calendar location
548 variables for your usual physical location in your @file{.emacs} file.
549 And when you install Emacs on a machine, you can create a
550 @file{default.el} file which sets them properly for the typical location
551 of most users of that machine.  @xref{Init File}.
553 @node Lunar Phases
554 @section Phases of the Moon
555 @cindex phases of the moon
556 @cindex moon, phases of
558   These calendar commands display the dates and times of the phases of
559 the moon (new moon, first quarter, full moon, last quarter).  This
560 feature is useful for debugging problems that ``depend on the phase of
561 the moon.''
563 @table @kbd
564 @item M
565 Display the dates and times for all the quarters of the moon for the
566 three-month period shown (@code{calendar-phases-of-moon}).
567 @item M-x phases-of-moon
568 Display dates and times of the quarters of the moon for three months around
569 today's date.
570 @end table
572 @kindex M @r{(Calendar mode)}
573 @findex calendar-phases-of-moon
574   Within the calendar, use the @kbd{M} command to display a separate
575 buffer of the phases of the moon for the current three-month range.  The
576 dates and times listed are accurate to within a few minutes.
578 @findex phases-of-moon
579   Outside the calendar, use the command @kbd{M-x phases-of-moon} to
580 display the list of the phases of the moon for the current month and the
581 preceding and succeeding months.  For information about a different
582 month, use @kbd{C-u M-x phases-of-moon}, which prompts for the month and
583 year.
585   The dates and times given for the phases of the moon are given in
586 local time (corrected for daylight savings, when appropriate); but if
587 the variable @code{calendar-time-zone} is void, Coordinated Universal
588 Time (the Greenwich time zone) is used.  @xref{Daylight Savings}.
590 @node Other Calendars
591 @section Conversion To and From Other Calendars
593 @cindex Gregorian calendar
594   The Emacs calendar displayed is @emph{always} the Gregorian calendar,
595 sometimes called the ``new style'' calendar, which is used in most of
596 the world today.  However, this calendar did not exist before the
597 sixteenth century and was not widely used before the eighteenth century;
598 it did not fully displace the Julian calendar and gain universal
599 acceptance until the early twentieth century.  The Emacs calendar can
600 display any month since January, year 1 of the current era, but the
601 calendar displayed is the Gregorian, even for a date at which the
602 Gregorian calendar did not exist.
604   While Emacs cannot display other calendars, it can convert dates to
605 and from several other calendars.
607 @menu
608 * Calendar Systems::       The calendars Emacs understands
609                              (aside from Gregorian).
610 * To Other Calendar::      Converting the selected date to various calendars.
611 * From Other Calendar::    Moving to a date specified in another calendar.
612 * Mayan Calendar::         Moving to a date specified in a Mayan calendar.
613 @end menu
615 @node Calendar Systems
616 @subsection Supported Calendar Systems
618 @cindex ISO commercial calendar
619   The ISO commercial calendar is used largely in Europe.
621 @cindex Julian calendar
622   The Julian calendar, named after Julius Caesar, was the one used in Europe
623 throughout medieval times, and in many countries up until the nineteenth
624 century.
626 @cindex Julian day numbers
627 @cindex astronomical day numbers
628   Astronomers use a simple counting of days elapsed since noon, Monday,
629 January 1, 4713 B.C. on the Julian calendar.  The number of days elapsed
630 is called the @dfn{Julian day number} or the @dfn{Astronomical day number}.
632 @cindex Hebrew calendar
633   The Hebrew calendar is used by tradition in the Jewish religion.  The
634 Emacs calendar program uses the Hebrew calendar to determine the dates
635 of Jewish holidays.  Hebrew calendar dates begin and end at sunset.
637 @cindex Islamic calendar
638   The Islamic calendar is used in many predominantly Islamic countries.
639 Emacs uses it to determine the dates of Islamic holidays.  There is no
640 universal agreement in the Islamic world about the calendar; Emacs uses
641 a widely accepted version, but the precise dates of Islamic holidays
642 often depend on proclamation by religious authorities, not on
643 calculations.  As a consequence, the actual dates of observance can vary
644 slightly from the dates computed by Emacs.  Islamic calendar dates begin
645 and end at sunset.
647 @cindex French Revolutionary calendar
648   The French Revolutionary calendar was created by the Jacobins after the 1789
649 revolution, to represent a more secular and nature-based view of the annual
650 cycle, and to install a 10-day week in a rationalization measure similar to
651 the metric system.  The French government officially abandoned this
652 calendar at the end of 1805.
654 @cindex Mayan calendar
655   The Maya of Central America used three separate, overlapping calendar
656 systems, the @emph{long count}, the @emph{tzolkin}, and the @emph{haab}.
657 Emacs knows about all three of these calendars.  Experts dispute the
658 exact correlation between the Mayan calendar and our calendar; Emacs uses the
659 Goodman-Martinez-Thompson correlation in its calculations.
661 @cindex Coptic calendar
662 @cindex Ethiopic calendar
663   The Copts use a calendar based on the ancient Egyptian solar calendar.
664 Their calendar consists of twelve 30-day months followed by an extra
665 five-day period.  Once every fourth year they add a leap day to this
666 extra period to make it six days.  The Ethiopic calendar is identical in
667 structure, but has different year numbers and month names.
669 @cindex Persian calendar
670   The Persians use a solar calendar based on a design of Omar Khayyam.
671 Their calendar consists of twelve months of which the first six have 31
672 days, the next five have 30 days, and the last has 29 in ordinary years
673 and 30 in leap years.  Leap years occur in a complicated pattern every
674 four or five years.
676 @cindex Chinese calendar
677   The Chinese calendar is a complicated system of lunar months arranged
678 into solar years.  The years go in cycles of sixty, each year containing
679 either twelve months in an ordinary year or thirteen months in a leap
680 year; each month has either 29 or 30 days.  Years, ordinary months, and
681 days are named by combining one of ten ``celestial stems'' with one of
682 twelve ``terrestrial branches'' for a total of sixty names that are
683 repeated in a cycle of sixty.
685 @node To Other Calendar
686 @subsection Converting To Other Calendars
688   The following commands describe the selected date (the date at point)
689 in various other calendar systems:
691 @table @kbd
692 @item Mouse-2  Other calendars
693 Display the date that you click on, expressed in various other calendars.
694 @kindex p @r{(Calendar mode)}
695 @findex calendar-print-iso-date
696 @item p c
697 Display ISO commercial calendar equivalent for selected day
698 (@code{calendar-print-iso-date}).
699 @findex calendar-print-julian-date
700 @item p j
701 Display Julian date for selected day (@code{calendar-print-julian-date}).
702 @findex calendar-print-astro-day-number
703 @item p a
704 Display astronomical (Julian) day number for selected day
705 (@code{calendar-print-astro-day-number}).
706 @findex calendar-print-hebrew-date
707 @item p h
708 Display Hebrew date for selected day (@code{calendar-print-hebrew-date}).
709 @findex calendar-print-islamic-date
710 @item p i
711 Display Islamic date for selected day (@code{calendar-print-islamic-date}).
712 @findex calendar-print-french-date
713 @item p f
714 Display French Revolutionary date for selected day
715 (@code{calendar-print-french-date}).
716 @findex calendar-print-chinese-date
717 @item p C
718 Display Chinese date for selected day
719 (@code{calendar-print-chinese-date}).
720 @findex calendar-print-coptic-date
721 @item p k
722 Display Coptic date for selected day
723 (@code{calendar-print-coptic-date}).
724 @findex calendar-print-ethiopic-date
725 @item p e
726 Display Ethiopic date for selected day
727 (@code{calendar-print-ethiopic-date}).
728 @findex calendar-print-persian-date
729 @item p p
730 Display Persian date for selected day
731 (@code{calendar-print-persian-date}).
732 @findex calendar-print-mayan-date
733 @item p m
734 Display Mayan date for selected day (@code{calendar-print-mayan-date}).
735 @end table
737   If you are using X, the easiest way to translate a date into other
738 calendars is to click on it with @kbd{Mouse-2}, then choose @kbd{Other
739 calendars} from the menu that appears.  This displays the equivalent
740 forms of the date in all the calendars Emacs understands, in the form of
741 a menu.  (Choosing an alternative from this menu doesn't actually do
742 anything---the menu is used only for display.)
744   Otherwise, move point to the date you want to convert, then type the
745 appropriate command starting with @kbd{p} from the table above.  The
746 prefix @kbd{p} is a mnemonic for ``print,'' since Emacs ``prints'' the
747 equivalent date in the echo area.
749 @node From Other Calendar
750 @subsection Converting From Other Calendars
752   You can use the other supported calendars to specify a date to move
753 to.  This section describes the commands for doing this using calendars
754 other than Mayan; for the Mayan calendar, see the following section.
756 @kindex g @var{char} @r{(Calendar mode)}
757 @findex calendar-goto-iso-date
758 @findex calendar-goto-iso-week
759 @findex calendar-goto-julian-date
760 @findex calendar-goto-astro-day-number
761 @findex calendar-goto-hebrew-date
762 @findex calendar-goto-islamic-date
763 @findex calendar-goto-french-date
764 @findex calendar-goto-chinese-date
765 @findex calendar-goto-persian-date
766 @findex calendar-goto-coptic-date
767 @findex calendar-goto-ethiopic-date
768 @table @kbd
769 @item g c
770 Move to a date specified in the ISO commercial calendar
771 (@code{calendar-goto-iso-date}).
772 @item g w
773 Move to a week specified in the ISO commercial calendar
774 (@code{calendar-goto-iso-week}).
775 @item g j
776 Move to a date specified in the Julian calendar
777 (@code{calendar-goto-julian-date}).
778 @item g a
779 Move to a date specified with an astronomical (Julian) day number
780 (@code{calendar-goto-astro-day-number}).
781 @item g h
782 Move to a date specified in the Hebrew calendar
783 (@code{calendar-goto-hebrew-date}).
784 @item g i
785 Move to a date specified in the Islamic calendar
786 (@code{calendar-goto-islamic-date}).
787 @item g f
788 Move to a date specified in the French Revolutionary calendar
789 (@code{calendar-goto-french-date}).
790 @item g C
791 Move to a date specified in the Chinese calendar
792 (@code{calendar-goto-chinese-date}).
793 @item g p
794 Move to a date specified in the Persian calendar
795 (@code{calendar-goto-persian-date}).
796 @item g k
797 Move to a date specified in the Coptic calendar
798 (@code{calendar-goto-coptic-date}).
799 @item g e
800 Move to a date specified in the Ethiopic calendar
801 (@code{calendar-goto-ethiopic-date}).
802 @end table
804   These commands ask you for a date on the other calendar, move point to
805 the Gregorian calendar date equivalent to that date, and display the
806 other calendar's date in the echo area.  Emacs uses strict completion
807 (@pxref{Completion}) whenever it asks you to type a month name, so you
808 don't have to worry about the spelling of Hebrew, Islamic, or French names.
810 @findex list-yahrzeit-dates
811 @cindex yahrzeits
812   One common question concerning the Hebrew calendar is the computation
813 of the anniversary of a date of death, called a ``yahrzeit.''  The Emacs
814 calendar includes a facility for such calculations.  If you are in the
815 calendar, the command @kbd{M-x list-yahrzeit-dates} asks you for a
816 range of years and then displays a list of the yahrzeit dates for those
817 years for the date given by point.  If you are not in the calendar,
818 this command first asks you for the date of death and the range of
819 years, and then displays the list of yahrzeit dates.
821 @node Mayan Calendar
822 @subsection Converting from the Mayan Calendar
824   Here are the commands to select dates based on the Mayan calendar:
826 @table @kbd
827 @item g m l
828 Move to a date specified by the long count calendar
829 (@code{calendar-goto-mayan-long-count-date}).
830 @item g m n t
831 Move to the next occurrence of a place in the
832 tzolkin calendar (@code{calendar-next-tzolkin-date}).
833 @item g m p t
834 Move to the previous occurrence of a place in the
835 tzolkin calendar (@code{calendar-previous-tzolkin-date}).
836 @item g m n h
837 Move to the next occurrence of a place in the
838 haab calendar (@code{calendar-next-haab-date}).
839 @item g m p h
840 Move to the previous occurrence of a place in the
841 haab calendar (@code{calendar-previous-haab-date}).
842 @item g m n c
843 Move to the next occurrence of a place in the
844 calendar round (@code{calendar-next-calendar-round-date}).
845 @item g m p c
846 Move to the previous occurrence of a place in the
847 calendar round (@code{calendar-previous-calendar-round-date}).
848 @end table
850 @cindex Mayan long count
851   To understand these commands, you need to understand the Mayan calendars.
852 The @dfn{long count} is a counting of days with these units:
854 @display
855 1 kin = 1 day@ @ @ 1 uinal = 20 kin@ @ @ 1 tun = 18 uinal
856 1 katun = 20 tun@ @ @ 1 baktun = 20 katun
857 @end display
859 @kindex g m @r{(Calendar mode)}
860 @findex calendar-goto-mayan-long-count-date
861 @noindent
862 Thus, the long count date 12.16.11.16.6 means 12 baktun, 16 katun, 11
863 tun, 16 uinal, and 6 kin.  The Emacs calendar can handle Mayan long
864 count dates as early as 7.17.18.13.1, but no earlier.  When you use the
865 @kbd{g m l} command, type the Mayan long count date with the baktun,
866 katun, tun, uinal, and kin separated by periods.
868 @findex calendar-previous-tzolkin-date
869 @findex calendar-next-tzolkin-date
870 @cindex Mayan tzolkin calendar
871   The Mayan tzolkin calendar is a cycle of 260 days formed by a pair of
872 independent cycles of 13 and 20 days.  Since this cycle repeats
873 endlessly, Emacs provides commands to move backward and forward to the
874 previous or next point in the cycle.  Type @kbd{g m p t} to go to the
875 previous tzolkin date; Emacs asks you for a tzolkin date and moves point
876 to the previous occurrence of that date.  Similarly, type @kbd{g m n t}
877 to go to the next occurrence of a tzolkin date.
879 @findex calendar-previous-haab-date
880 @findex calendar-next-haab-date
881 @cindex Mayan haab calendar
882   The Mayan haab calendar is a cycle of 365 days arranged as 18 months
883 of 20 days each, followed a 5-day monthless period.  Like the tzolkin
884 cycle, this cycle repeats endlessly, and there are commands to move
885 backward and forward to the previous or next point in the cycle.  Type
886 @kbd{g m p h} to go to the previous haab date; Emacs asks you for a haab
887 date and moves point to the previous occurrence of that date.
888 Similarly, type @kbd{g m n h} to go to the next occurrence of a haab
889 date.
891 @c This is omitted because it is too long for smallbook format.
892 @c @findex calendar-previous-calendar-round-date
893 @findex calendar-next-calendar-round-date
894 @cindex Mayan calendar round
895   The Maya also used the combination of the tzolkin date and the haab
896 date.  This combination is a cycle of about 52 years called a
897 @emph{calendar round}.  If you type @kbd{g m p c}, Emacs asks you for
898 both a haab and a tzolkin date and then moves point to the previous
899 occurrence of that combination.  Use @kbd{g m n c} to move point to the
900 next occurrence of a combination.  These commands signal an error if the
901 haab/tzolkin date combination you have typed is impossible.
903   Emacs uses strict completion (@pxref{Strict Completion}) whenever it
904 asks you to type a Mayan name, so you don't have to worry about
905 spelling.
907 @node Diary
908 @section The Diary
909 @cindex diary
911   The Emacs diary keeps track of appointments or other events on a daily
912 basis, in conjunction with the calendar.  To use the diary feature, you
913 must first create a @dfn{diary file} containing a list of events and
914 their dates.  Then Emacs can automatically pick out and display the
915 events for today, for the immediate future, or for any specified
916 date.
918   By default, Emacs uses @file{~/diary} as the diary file.  This is the
919 same file that the @code{calendar} utility uses.  A sample
920 @file{~/diary} file is:
922 @example
923 12/22/1988  Twentieth wedding anniversary!!
924 &1/1.       Happy New Year!
925 10/22       Ruth's birthday.
926 * 21, *:    Payday
927 Tuesday--weekly meeting with grad students at 10am
928          Supowit, Shen, Bitner, and Kapoor to attend.
929 1/13/89     Friday the thirteenth!!
930 &thu 4pm    squash game with Lloyd.
931 mar 16      Dad's birthday
932 April 15, 1989 Income tax due.
933 &* 15       time cards due.
934 @end example
936 @noindent
937 This example uses extra spaces to align the event descriptions of most
938 of the entries.  Such formatting is purely a matter of taste.
940   Although you probably will start by creating a diary manually, Emacs
941 provides a number of commands to let you view, add, and change diary
942 entries.
944 @menu
945 * Diary Commands::         Viewing diary entries and associated calendar dates.
946 * Format of Diary File::   Entering events in your diary.
947 * Date Formats::           Various ways you can specify dates.
948 * Adding to Diary::        Commands to create diary entries.
949 * Special Diary Entries::  Anniversaries, blocks of dates, cyclic entries, etc.
950 @end menu
952 @node Diary Commands
953 @subsection Commands Displaying Diary Entries
955   Once you have created a @file{~/diary} file, you can use the calendar
956 to view it.  You can also view today's events outside of Calendar mode.
958 @table @kbd
959 @item d
960 Display all diary entries for the selected date
961 (@code{view-diary-entries}).
962 @item Mouse-2 Diary
963 Display all diary entries for the date you click on.
964 @item s
965 Display the entire diary file (@code{show-all-diary-entries}).
966 @item m
967 Mark all visible dates that have diary entries
968 (@code{mark-diary-entries}).
969 @item u
970 Unmark the calendar window (@code{calendar-unmark}).
971 @item M-x print-diary-entries
972 Print hard copy of the diary display as it appears.
973 @item M-x diary
974 Display all diary entries for today's date.
975 @item M-x diary-mail-entries
976 Mail yourself email reminders about upcoming diary entries.
977 @end table
979 @kindex d @r{(Calendar mode)}
980 @findex view-diary-entries
981   Displaying the diary entries with @kbd{d} shows in a separate window
982 the diary entries for the selected date in the calendar.  The mode line
983 of the new window shows the date of the diary entries and any holidays
984 that fall on that date.  If you specify a numeric argument with @kbd{d},
985 it shows all the diary entries for that many successive days.  Thus,
986 @kbd{2 d} displays all the entries for the selected date and for the
987 following day.
989   Another way to display the diary entries for a date is to click
990 @kbd{Mouse-2} on the date, and then choose @kbd{Diary entries} from
991 the menu that appears.
993 @kindex m @r{(Calendar mode)}
994 @findex mark-diary-entries
995   To get a broader view of which days are mentioned in the diary, use
996 the @kbd{m} command.  This displays the dates that have diary entries
997 in a different face (or places a @samp{+} after these dates, if
998 display with multiple faces is not available).  The command applies both
999 to the currently visible months and to other months that subsequently
1000 become visible by scrolling.  To turn marking off and erase the current
1001 marks, type @kbd{u}, which also turns off holiday marks
1002 (@pxref{Holidays}).
1004 @kindex s @r{(Calendar mode)}
1005 @findex show-all-diary-entries
1006   To see the full diary file, rather than just some of the entries, use
1007 the @kbd{s} command.
1009   Display of selected diary entries uses the selective display feature
1010 to hide entries that don't apply.
1012   The diary buffer as you see it is an illusion, so simply printing the
1013 buffer does not print what you see on your screen.  There is a special
1014 command to print hard copy of the diary buffer @emph{as it appears};
1015 this command is @kbd{M-x print-diary-entries}.  It sends the data
1016 directly to the printer.  You can customize it like @code{lpr-region}
1017 (@pxref{Hardcopy}).
1019 @findex diary
1020   The command @kbd{M-x diary} displays the diary entries for the current
1021 date, independently of the calendar display, and optionally for the next
1022 few days as well; the variable @code{number-of-diary-entries} specifies
1023 how many days to include.  @xref{Calendar, Customizing the Calendar
1024 and Diary,, elisp, The Emacs Lisp Reference Manual}.
1026   If you put @code{(diary)} in your @file{.emacs} file, this
1027 automatically displays a window with the day's diary entries, when you
1028 enter Emacs.  The mode line of the displayed window shows the date and
1029 any holidays that fall on that date.
1031 @findex diary-mail-entries
1032 @vindex diary-mail-days
1033   Many users like to receive notice of events in their diary as email.
1034 To send such mail to yourself, use the command @kbd{M-x
1035 diary-mail-entries}.  A prefix argument specifies how many days
1036 (starting with today) to check; otherwise, the variable
1037 @code{diary-mail-days} says how many days.
1039 @node Format of Diary File
1040 @subsection The Diary File
1041 @cindex diary file
1043 @vindex diary-file
1044   Your @dfn{diary file} is a file that records events associated with
1045 particular dates.  The name of the diary file is specified by the
1046 variable @code{diary-file}; @file{~/diary} is the default.  The
1047 @code{calendar} utility program supports a subset of the format allowed
1048 by the Emacs diary facilities, so you can use that utility to view the
1049 diary file, with reasonable results aside from the entries it cannot
1050 understand.
1052   Each entry in the diary file describes one event and consists of one
1053 or more lines.  An entry always begins with a date specification at the
1054 left margin.  The rest of the entry is simply text to describe the
1055 event.  If the entry has more than one line, then the lines after the
1056 first must begin with whitespace to indicate they continue a previous
1057 entry.  Lines that do not begin with valid dates and do not continue a
1058 preceding entry are ignored.
1060   You can inhibit the marking of certain diary entries in the calendar
1061 window; to do this, insert an ampersand (@samp{&}) at the beginning of
1062 the entry, before the date.  This has no effect on display of the entry
1063 in the diary window; it affects only marks on dates in the calendar
1064 window.  Nonmarking entries are especially useful for generic entries
1065 that would otherwise mark many different dates.
1067   If the first line of a diary entry consists only of the date or day
1068 name with no following blanks or punctuation, then the diary window
1069 display doesn't include that line; only the continuation lines appear.
1070 For example, this entry:
1072 @example
1073 02/11/1989
1074       Bill B. visits Princeton today
1075       2pm Cognitive Studies Committee meeting
1076       2:30-5:30 Liz at Lawrenceville
1077       4:00pm Dentist appt
1078       7:30pm Dinner at George's
1079       8:00-10:00pm concert
1080 @end example
1082 @noindent
1083 appears in the diary window without the date line at the beginning.
1084 This style of entry looks neater when you display just a single day's
1085 entries, but can cause confusion if you ask for more than one day's
1086 entries.
1088   You can edit the diary entries as they appear in the window, but it is
1089 important to remember that the buffer displayed contains the @emph{entire}
1090 diary file, with portions of it concealed from view.  This means, for
1091 instance, that the @kbd{C-f} (@code{forward-char}) command can put point
1092 at what appears to be the end of the line, but what is in reality the
1093 middle of some concealed line.
1095   @emph{Be careful when editing the diary entries!}  Inserting
1096 additional lines or adding/deleting characters in the middle of a
1097 visible line cannot cause problems, but editing at the end of a line may
1098 not do what you expect.  Deleting a line may delete other invisible
1099 entries that follow it.  Before editing the diary, it is best to display
1100 the entire file with @kbd{s} (@code{show-all-diary-entries}).
1102 @node Date Formats
1103 @subsection Date Formats
1105   Here are some sample diary entries, illustrating different ways of
1106 formatting a date.  The examples all show dates in American order
1107 (month, day, year), but Calendar mode supports European order (day,
1108 month, year) as an option.
1110 @example
1111 4/20/93  Switch-over to new tabulation system
1112 apr. 25  Start tabulating annual results
1113 4/30  Results for April are due
1114 */25  Monthly cycle finishes
1115 Friday  Don't leave without backing up files
1116 @end example
1118   The first entry appears only once, on April 20, 1993.  The second and
1119 third appear every year on the specified dates, and the fourth uses a
1120 wildcard (asterisk) for the month, so it appears on the 25th of every
1121 month.  The final entry appears every week on Friday.
1123   You can use just numbers to express a date, as in
1124 @samp{@var{month}/@var{day}} or @samp{@var{month}/@var{day}/@var{year}}.
1125 This must be followed by a nondigit.  In the date itself, @var{month}
1126 and @var{day} are numbers of one or two digits.  The optional @var{year}
1127 is also a number, and may be abbreviated to the last two digits; that
1128 is, you can use @samp{11/12/1989} or @samp{11/12/89}.
1130   Dates can also have the form @samp{@var{monthname} @var{day}} or
1131 @samp{@var{monthname} @var{day}, @var{year}}, where the month's name can
1132 be spelled in full or abbreviated (with or without a period).  The
1133 preferred abbreviations can be controlled using the variables
1134 @code{calendar-abbrev-length}, @code{calendar-month-abbrev-array}, and
1135 @code{calendar-day-abbrev-array}.  The default is to use the first three
1136 letters of a name as its abbreviation.  Case is not significant.
1138   A date may be @dfn{generic}; that is, partially unspecified.  Then the
1139 entry applies to all dates that match the specification.  If the date
1140 does not contain a year, it is generic and applies to any year.
1141 Alternatively, @var{month}, @var{day}, or @var{year} can be a @samp{*};
1142 this matches any month, day, or year, respectively.  Thus, a diary entry
1143 @samp{3/*/*} matches any day in March of any year; so does @samp{march
1146 @vindex european-calendar-style
1147 @findex european-calendar
1148 @findex american-calendar
1149   If you prefer the European style of writing dates---in which the day
1150 comes before the month---type @kbd{M-x european-calendar} while in the
1151 calendar, or set the variable @code{european-calendar-style} to @code{t}
1152 @emph{before} using any calendar or diary command.  This mode interprets
1153 all dates in the diary in the European manner, and also uses European
1154 style for displaying diary dates.  (Note that there is no comma after
1155 the @var{monthname} in the European style.)  To go back to the (default)
1156 American style of writing dates, type @kbd{M-x american-calendar}.
1158   You can use the name of a day of the week as a generic date which
1159 applies to any date falling on that day of the week.  You can abbreviate
1160 the day of the week to three letters (with or without a period) or spell
1161 it in full; case is not significant.
1163 @node Adding to Diary
1164 @subsection Commands to Add to the Diary
1166   While in the calendar, there are several commands to create diary
1167 entries:
1169 @table @kbd
1170 @item i d
1171 Add a diary entry for the selected date (@code{insert-diary-entry}).
1172 @item i w
1173 Add a diary entry for the selected day of the week (@code{insert-weekly-diary-entry}).
1174 @item i m
1175 Add a diary entry for the selected day of the month (@code{insert-monthly-diary-entry}).
1176 @item i y
1177 Add a diary entry for the selected day of the year (@code{insert-yearly-diary-entry}).
1178 @end table
1180 @kindex i d @r{(Calendar mode)}
1181 @findex insert-diary-entry
1182   You can make a diary entry for a specific date by selecting that date
1183 in the calendar window and typing the @kbd{i d} command.  This command
1184 displays the end of your diary file in another window and inserts the
1185 date; you can then type the rest of the diary entry.
1187 @kindex i w @r{(Calendar mode)}
1188 @findex insert-weekly-diary-entry
1189 @kindex i m @r{(Calendar mode)}
1190 @findex insert-monthly-diary-entry
1191 @kindex i y @r{(Calendar mode)}
1192 @findex insert-yearly-diary-entry
1193   If you want to make a diary entry that applies to a specific day of
1194 the week, select that day of the week (any occurrence will do) and type
1195 @kbd{i w}.  This inserts the day-of-week as a generic date; you can then
1196 type the rest of the diary entry.  You can make a monthly diary entry in
1197 the same fashion: select the day of the month, use the @kbd{i m}
1198 command, and type the rest of the entry.  Similarly, you can insert a
1199 yearly diary entry with the @kbd{i y} command.
1201   All of the above commands make marking diary entries by default.  To
1202 make a nonmarking diary entry, give a numeric argument to the command.
1203 For example, @kbd{C-u i w} makes a nonmarking weekly diary entry.
1205   When you modify the diary file, be sure to save the file before
1206 exiting Emacs.
1208 @node Special Diary Entries
1209 @subsection Special Diary Entries
1211   In addition to entries based on calendar dates, the diary file can
1212 contain @dfn{sexp entries} for regular events such as anniversaries.
1213 These entries are based on Lisp expressions (sexps) that Emacs evaluates
1214 as it scans the diary file.  Instead of a date, a sexp entry contains
1215 @samp{%%} followed by a Lisp expression which must begin and end with
1216 parentheses.  The Lisp expression determines which dates the entry
1217 applies to.
1219   Calendar mode provides commands to insert certain commonly used
1220 sexp entries:
1222 @table @kbd
1223 @item i a
1224 Add an anniversary diary entry for the selected date
1225 (@code{insert-anniversary-diary-entry}).
1226 @item i b
1227 Add a block diary entry for the current region
1228 (@code{insert-block-diary-entry}).
1229 @item i c
1230 Add a cyclic diary entry starting at the date
1231 (@code{insert-cyclic-diary-entry}).
1232 @end table
1234 @kindex i a @r{(Calendar mode)}
1235 @findex insert-anniversary-diary-entry
1236   If you want to make a diary entry that applies to the anniversary of a
1237 specific date, move point to that date and use the @kbd{i a} command.
1238 This displays the end of your diary file in another window and inserts
1239 the anniversary description; you can then type the rest of the diary
1240 entry.  The entry looks like this:
1242 @findex diary-anniversary
1243 @example
1244 %%(diary-anniversary 10 31 1948) Arthur's birthday
1245 @end example
1247 @noindent
1248 This entry applies to October 31 in any year after 1948; @samp{10 31
1249 1948} specifies the date.  (If you are using the European calendar
1250 style, the month and day are interchanged.)  The reason this expression
1251 requires a beginning year is that advanced diary functions can use it to
1252 calculate the number of elapsed years.
1254   A @dfn{block} diary entry applies to a specified range of consecutive
1255 dates.  Here is a block diary entry that applies to all dates from June
1256 24, 1990 through July 10, 1990:
1258 @findex diary-block
1259 @example
1260 %%(diary-block 6 24 1990 7 10 1990) Vacation
1261 @end example
1263 @noindent
1264 The @samp{6 24 1990} indicates the starting date and the @samp{7 10 1990}
1265 indicates the stopping date.  (Again, if you are using the European calendar
1266 style, the month and day are interchanged.)
1268 @kindex i b @r{(Calendar mode)}
1269 @findex insert-block-diary-entry
1270   To insert a block entry, place point and the mark on the two
1271 dates that begin and end the range, and type @kbd{i b}.  This command
1272 displays the end of your diary file in another window and inserts the
1273 block description; you can then type the diary entry.
1275 @kindex i c @r{(Calendar mode)}
1276 @findex insert-cyclic-diary-entry
1277    @dfn{Cyclic} diary entries repeat after a fixed interval of days.  To
1278 create one, select the starting date and use the @kbd{i c} command.  The
1279 command prompts for the length of interval, then inserts the entry,
1280 which looks like this:
1282 @findex diary-cyclic
1283 @example
1284 %%(diary-cyclic 50 3 1 1990) Renew medication
1285 @end example
1287 @noindent
1288 This entry applies to March 1, 1990 and every 50th day following;
1289 @samp{3 1 1990} specifies the starting date.  (If you are using the
1290 European calendar style, the month and day are interchanged.)
1292   All three of these commands make marking diary entries.  To insert a
1293 nonmarking entry, give a numeric argument to the command.  For example,
1294 @kbd{C-u i a} makes a nonmarking anniversary diary entry.
1296   Marking sexp diary entries in the calendar is @emph{extremely}
1297 time-consuming, since every date visible in the calendar window must be
1298 individually checked.  So it's a good idea to make sexp diary entries
1299 nonmarking (with @samp{&}) when possible.
1301   Another sophisticated kind of sexp entry, a @dfn{floating} diary entry,
1302 specifies a regularly occurring event by offsets specified in days,
1303 weeks, and months.  It is comparable to a crontab entry interpreted by
1304 the @code{cron} utility.  Here is a nonmarking, floating diary entry
1305 that applies to the last Thursday in November:
1307 @findex diary-float
1308 @example
1309 &%%(diary-float 11 4 -1) American Thanksgiving
1310 @end example
1312 @noindent
1313 The 11 specifies November (the eleventh month), the 4 specifies Thursday
1314 (the fourth day of the week, where Sunday is numbered zero), and the
1315 @minus{}1 specifies ``last'' (1 would mean ``first,'' 2 would mean
1316 ``second,'' @minus{}2 would mean ``second-to-last,'' and so on).  The
1317 month can be a single month or a list of months.  Thus you could change
1318 the 11 above to @samp{'(1 2 3)} and have the entry apply to the last
1319 Thursday of January, February, and March.  If the month is @code{t}, the
1320 entry applies to all months of the year.@refill
1322   Each of the standard sexp diary entries takes an optional parameter
1323 specifying the name of a face or a single-character string to use when
1324 marking the entry in the calendar.  Most generally, sexp diary entries
1325 can perform arbitrary computations to determine when they apply.
1326 @xref{Sexp Diary Entries,, Sexp Diary Entries, elisp, The Emacs Lisp
1327 Reference Manual}.
1329 @node Appointments
1330 @section Appointments
1331 @cindex appointment notification
1333 @vindex appt-display-format
1334 @vindex appt-audible
1335   If you have a diary entry for an appointment, and that diary entry
1336 begins with a recognizable time of day, Emacs can warn you several
1337 minutes beforehand that that appointment is pending.  Emacs alerts you
1338 to the appointment by displaying a message in your chosen format, as
1339 specified by the variable @code{appt-display-format}.  If the value
1340 of @code{appt-audible} is non-@code{nil}, an audible reminder is also given.
1342 @findex appt-activate
1343   To enable appointment notification, call the function
1344 @code{appt-activate} with a positive argument. This sets up an
1345 appointment list for today from the diary file, giving all diary entries
1346 found with recognizable times of day, and reminds you just before each
1347 of them. Calling @code{appt-activate} with a negative argument disables
1348 the appointment package.
1350   For example, suppose the diary file contains these lines:
1352 @example
1353 Monday
1354   9:30am Coffee break
1355  12:00pm Lunch
1356 @end example
1358 @vindex appt-message-warning-time
1359 @noindent
1360 Then on Mondays, you will be reminded at around 9:20am about your coffee
1361 break and at around 11:50am about lunch. How many minutes in advance you
1362 are first warned is determined by the value of
1363 @code{appt-message-warning-time}.
1365   You can write times in am/pm style (with @samp{12:00am} standing
1366 for midnight and @samp{12:00pm} standing for noon), or 24-hour
1367 European/military style.  You need not be consistent; your diary file
1368 can have a mixture of the two styles.  Times must be at the beginning
1369 of lines if they are to be recognized.
1371 @vindex appt-display-diary
1372   Emacs updates the appointments list from the diary file automatically
1373 just after midnight.  An update can be forced at any time by
1374 re-activating the appointment package.  Both these actions also display
1375 the day's diary buffer, unless you set @code{appt-display-diary} to
1376 @code{nil}.  The appointments list is also updated whenever the
1377 diary file is saved.
1379 @findex appt-add
1380 @findex appt-delete
1381 @cindex alarm clock
1382   You can also use the appointment notification facility like an alarm
1383 clock.  The command @kbd{M-x appt-add} adds entries to the appointment
1384 list without affecting your diary file.  You delete entries from the
1385 appointment list with @kbd{M-x appt-delete}.
1387 @node iCalendar
1388 @section iCalendar
1389 @cindex iCalendar support
1391   The icalendar package aims at providing an implementation of the
1392 iCalendar standard, as defined in ``RFC 2445 -- Internet Calendaring and
1393 Scheduling Core Object Specification (iCalendar)''.  It provides a means
1394 for importing iCalendar (and the earlier vCalendar format) data into
1395 Emacs diary files and vice versa.
1397   Importing works for ``ordinary'' (i.e. non-recurring) events, but (at
1398 present) may not work correctly (if at all) for recurring events.
1399 Exporting of diary files into iCalendar files should work correctly for
1400 most diary entries.  Please note that @file{icalendar.el} is work in
1401 progress, so usage may evolve in future.
1403   To activate the package, use @code{(require 'icalendar)}.
1405 @findex icalendar-import-buffer
1406   The command @code{icalendar-import-buffer} extracts
1407 iCalendar data from the current buffer and adds it to your (default)
1408 diary file.  This function is also suitable for automatic extraction of
1409 iCalendar data; for example with the Rmail mail client one could use:
1411 @example
1412 (add-hook 'rmail-show-message-hook 'icalendar-import-buffer)
1413 @end example
1415 @findex icalendar-import-file
1416   The command @code{icalendar-import-file} imports an iCalendar file
1417 and adds the results to an Emacs diary file.  For example:
1419 @example
1420 (icalendar-import-file "/here/is/calendar.ics" "/there/goes/ical-diary")
1421 @end example
1423 @noindent
1424 You can use an @code{#include} directive to add the import file contents
1425 to the main diary file, if these are distinct.  @xref{Fancy Diary
1426 Display,,, elisp, The Emacs Lisp Reference Manual}.
1428 @findex icalendar-export-file, icalendar-export-region
1429   Use @code{icalendar-export-file} to interactively export an entire
1430 Emacs diary file to iCalendar format.  To export only a part of a diary
1431 file, mark the relevant area, and call @code{icalendar-export-region}.
1432 In both cases the result is appended to the target file.
1435 @node Daylight Savings
1436 @section Daylight Savings Time
1437 @cindex daylight savings time
1439   Emacs understands the difference between standard time and daylight
1440 savings time---the times given for sunrise, sunset, solstices,
1441 equinoxes, and the phases of the moon take that into account.  The rules
1442 for daylight savings time vary from place to place and have also varied
1443 historically from year to year.  To do the job properly, Emacs needs to
1444 know which rules to use.
1446 @vindex calendar-daylight-savings-starts
1447 @vindex calendar-daylight-savings-ends
1448   Some operating systems keep track of the rules that apply to the place
1449 where you are; on these systems, Emacs gets the information it needs
1450 from the system automatically.  If some or all of this information is
1451 missing, Emacs fills in the gaps with the rules currently used in
1452 Cambridge, Massachusetts.  If the resulting rules are not what you want,
1453 you can tell Emacs the rules to use by setting certain variables:
1454 @code{calendar-daylight-savings-starts} and
1455 @code{calendar-daylight-savings-ends}.
1457   These values should be Lisp expressions that refer to the variable
1458 @code{year}, and evaluate to the Gregorian date on which daylight
1459 savings time starts or (respectively) ends, in the form of a list
1460 @code{(@var{month} @var{day} @var{year})}.  The values should be
1461 @code{nil} if your area does not use daylight savings time.
1463   Emacs uses these expressions to determine the starting date of
1464 daylight savings time for the holiday list and for correcting times of
1465 day in the solar and lunar calculations.
1467   The values for Cambridge, Massachusetts are as follows:
1469 @example
1470 (calendar-nth-named-day 1 0 4 year)
1471 (calendar-nth-named-day -1 0 10 year)
1472 @end example
1474 @noindent
1475 That is, the first 0th day (Sunday) of the fourth month (April) in
1476 the year specified by @code{year}, and the last Sunday of the tenth month
1477 (October) of that year.  If daylight savings time were
1478 changed to start on October 1, you would set
1479 @code{calendar-daylight-savings-starts} to this:
1481 @example
1482 (list 10 1 year)
1483 @end example
1485   If there is no daylight savings time at your location, or if you want
1486 all times in standard time, set @code{calendar-daylight-savings-starts}
1487 and @code{calendar-daylight-savings-ends} to @code{nil}.
1489 @vindex calendar-daylight-time-offset
1490   The variable @code{calendar-daylight-time-offset} specifies the
1491 difference between daylight savings time and standard time, measured in
1492 minutes.  The value for Cambridge, Massachusetts is 60.
1494 @c @vindex calendar-daylight-savings-starts-time  too long!
1495 @vindex calendar-daylight-savings-ends-time
1496   The two variables @code{calendar-daylight-savings-starts-time} and
1497 @code{calendar-daylight-savings-ends-time} specify the number of minutes
1498 after midnight local time when the transition to and from daylight
1499 savings time should occur.  For Cambridge, Massachusetts both variables'
1500 values are 120.
1502 @node Time Intervals
1503 @section Summing Time Intervals
1504 @cindex time intervals, summing
1505 @cindex summing time intervals
1506 @cindex timeclock
1508   The timeclock feature adds up time intervals, so you can (for
1509 instance) keep track of how much time you spend working.
1511 @findex timeclock-in
1512 @findex timeclock-out
1513 @findex timeclock-workday-remaining
1514 @findex timeclock-when-to-leave
1515   Use the @kbd{M-x timeclock-in} command when you start working on a
1516 project, and @kbd{M-x timeclock-out} command when you're done.  Each
1517 time you do this, it adds one time interval to the record of the project.
1519   Once you've collected data from a number of time intervals, you can use
1520 @kbd{M-x timeclock-workday-remaining} to see how much time is left to
1521 work today (assuming a typical average of 8 hours a day), and @kbd{M-x
1522 timeclock-when-to-leave} which will calculate when you're ``done.''
1524 @vindex timeclock-modeline-display
1525 @findex timeclock-modeline-display
1526   If you want Emacs to display the amount of time ``left'' of your
1527 workday in the mode line, either customize the
1528 @code{timeclock-modeline-display} variable and set its value to
1529 @code{t}, or invoke the @kbd{M-x timeclock-modeline-display} command.
1531 @vindex timeclock-ask-before-exiting
1532   Terminating the current Emacs session might or might not mean that
1533 you have stopped working on the project.  If you'd like Emacs to ask
1534 you about this, set the value of the variable
1535 @code{timeclock-ask-before-exiting} to @code{t} (via @kbd{M-x
1536 customize}).  By default, only an explicit @kbd{M-x timeclock-out}
1537 tells Emacs that the current interval is over.
1539 @cindex @file{.timelog} file
1540 @vindex timeclock-file
1541 @findex timeclock-reread-log
1542   The timeclock functions work by accumulating the data in a file
1543 called @file{.timelog} in your home directory.  You can specify a
1544 different name for this file by customizing the variable
1545 @code{timeclock-file}.  If you edit the timeclock file manually, or if
1546 you change the value of any of timeclock's customizable variables, you
1547 should run the command @kbd{M-x timeclock-reread-log} to update the
1548 data in Emacs from the file.
1550 @ignore
1551    arch-tag: 4531ef09-9df3-449d-9c52-2b5a4a337f92
1552 @end ignore