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