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, 2006 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
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
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
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 This chapter describes the basic calendar features.
28 @inforef{Advanced Calendar/Diary Usage,, emacs-xtra}, for information
29 about more specialized features.
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.
49 @section Movement in the Calendar
51 @cindex moving inside the calendar
52 Calendar mode provides commands to move through the calendar in
53 logical units of time such as days, weeks, months, and years. If you
54 move outside the three months originally displayed, the calendar
55 display ``scrolls'' automatically through time to make the selected
56 date visible. Moving to a date lets you view its holidays or diary
57 entries, or convert it to other calendars; moving by long time periods
58 is also useful simply to scroll the calendar.
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
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.
76 Move point one day forward (@code{calendar-forward-day}).
78 Move point one day backward (@code{calendar-backward-day}).
80 Move point one week forward (@code{calendar-forward-week}).
82 Move point one week backward (@code{calendar-backward-week}).
84 Move point one month forward (@code{calendar-forward-month}).
86 Move point one month backward (@code{calendar-backward-month}).
88 Move point one year forward (@code{calendar-forward-year}).
90 Move point one year backward (@code{calendar-backward-year}).
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. The year
121 commands @kbd{C-x ]} and @w{@kbd{C-x [}} move forward or backward a
124 The easiest way to remember these commands is to consider months and
125 years analogous to paragraphs and pages of text, respectively. But
126 the commands themselves are not quite analogous. The ordinary Emacs
127 paragraph commands move to the beginning or end of a paragraph,
128 whereas these month and year commands move by an entire month or an
129 entire year, keeping the same date within the 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
145 @kindex C-a @r{(Calendar mode)}
146 @findex calendar-beginning-of-week
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
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
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
160 Move point to end of month (@code{calendar-end-of-month}).
161 @kindex M-< @r{(Calendar mode)}
162 @findex calendar-beginning-of-year
164 Move point to start of year (@code{calendar-beginning-of-year}).
165 @kindex M-> @r{(Calendar mode)}
166 @findex calendar-end-of-year
168 Move point to end of year (@code{calendar-end-of-year}).
171 These commands also take numeric arguments as repeat counts, with the
172 repeat count indicating how many weeks, months, or years to move
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.
189 Move point to specified date (@code{calendar-goto-date}).
191 Move point to specified day of year (@code{calendar-goto-day-of-year}).
193 Move point to specified week of year (@code{calendar-goto-iso-week}).
195 Center calendar around specified month (@code{calendar-other-month}).
197 Move point to today's date (@code{calendar-goto-today}).
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.
239 Scroll calendar one month forward (@code{scroll-calendar-left}).
241 Scroll calendar one month backward (@code{scroll-calendar-right}).
244 Scroll calendar three months forward
245 (@code{scroll-calendar-left-three-months}).
248 Scroll calendar three months backward
249 (@code{scroll-calendar-right-three-months}).
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.
279 @section Counting Days
283 Display the number of days in the current region
284 (@code{calendar-count-days-region}).
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
294 @node General Calendar
295 @section Miscellaneous Calendar Commands
299 Display day-in-year (@code{calendar-print-day-of-year}).
301 Regenerate the calendar window (@code{redraw-calendar}).
303 Scroll the next window up (@code{scroll-other-window}).
305 Scroll the next window down (@code{scroll-other-window-down}).
307 Exit from calendar (@code{exit-calendar}).
310 @kindex p d @r{(Calendar mode)}
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 count of days elapsed includes the
317 selected date. The count of days remaining does not include that
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.)
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)}
350 Generate a one-month calendar (@code{cal-tex-cursor-month}).
352 Generate a sideways-printing one-month calendar
353 (@code{cal-tex-cursor-month-landscape}).
355 Generate a one-day calendar
356 (@code{cal-tex-cursor-day}).
358 Generate a one-page calendar for one week
359 (@code{cal-tex-cursor-week}).
361 Generate a two-page calendar for one week
362 (@code{cal-tex-cursor-week2}).
364 Generate an ISO-style calendar for one week
365 (@code{cal-tex-cursor-week-iso}).
367 Generate a calendar for one Monday-starting week
368 (@code{cal-tex-cursor-week-monday}).
370 Generate a Filofax-style two-weeks-at-a-glance calendar
371 (@code{cal-tex-cursor-filofax-2week}).
373 Generate a Filofax-style one-week-at-a-glance calendar
374 (@code{cal-tex-cursor-filofax-week}).
376 Generate a calendar for one year
377 (@code{cal-tex-cursor-year}).
379 Generate a sideways-printing calendar for one year
380 (@code{cal-tex-cursor-year-landscape}).
382 Generate a Filofax-style calendar for one year
383 (@code{cal-tex-cursor-filofax-year}).
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. You can use the variable
399 @code{cal-tex-preamble-extra} to insert extra LaTeX commands in the
400 preamble of the generated document if you need to.
406 The Emacs calendar knows about all major and many minor holidays,
407 and can display them.
411 Display holidays for the selected date
412 (@code{calendar-cursor-holidays}).
413 @item Mouse-2 Holidays
414 Display any holidays for the date you click on.
416 Mark holidays in the calendar window (@code{mark-calendar-holidays}).
418 Unmark calendar window (@code{calendar-unmark}).
420 List all holidays for the displayed three months in another window
421 (@code{list-calendar-holidays}).
423 List all holidays for three months around today's date in another
425 @item M-x list-holidays
426 List holidays in another window for a specified range of years.
429 @kindex h @r{(Calendar mode)}
430 @findex calendar-cursor-holidays
431 @vindex view-calendar-holidays-initially
432 To see if any holidays fall on a given date, position point on that
433 date in the calendar window and use the @kbd{h} command. Alternatively,
434 click on that date with @kbd{Mouse-2} and then choose @kbd{Holidays}
435 from the menu that appears. Either way, this displays the holidays for
436 that date, in the echo area if they fit there, otherwise in a separate
439 @kindex x @r{(Calendar mode)}
440 @findex mark-calendar-holidays
441 @kindex u @r{(Calendar mode)}
442 @findex calendar-unmark
443 @vindex mark-holidays-in-calendar
444 To view the distribution of holidays for all the dates shown in the
445 calendar, use the @kbd{x} command. This displays the dates that are
446 holidays in a different face (or places a @samp{*} after these dates, if
447 display with multiple faces is not available). @inforef{Calendar
448 Customizing, calendar-holiday-marker, emacs-xtra}. The command applies
449 both to the currently visible months and to other months that
450 subsequently become visible by scrolling. To turn marking off and erase
451 the current marks, type @kbd{u}, which also erases any diary marks
452 (@pxref{Diary}). If the variable @code{mark-holidays-in-calendar} is
453 non-@code{nil}, creating or updating the calendar marks holidays
456 @kindex a @r{(Calendar mode)}
457 @findex list-calendar-holidays
458 To get even more detailed information, use the @kbd{a} command, which
459 displays a separate buffer containing a list of all holidays in the
460 current three-month range. You can use @key{SPC} and @key{DEL} in the
461 calendar window to scroll that list up and down, respectively.
464 The command @kbd{M-x holidays} displays the list of holidays for the
465 current month and the preceding and succeeding months; this works even
466 if you don't have a calendar window. If the variable
467 @code{view-calendar-holidays-initially} is non-@code{nil}, creating
468 the calendar displays holidays in this way. If you want the list of
469 holidays centered around a different month, use @kbd{C-u M-x
470 holidays}, which prompts for the month and year.
472 The holidays known to Emacs include United States holidays and the
473 major Christian, Jewish, and Islamic holidays; also the solstices and
476 @findex list-holidays
477 The command @kbd{M-x list-holidays} displays the list of holidays for
478 a range of years. This function asks you for the starting and stopping
479 years, and allows you to choose all the holidays or one of several
480 categories of holidays. You can use this command even if you don't have
483 The dates used by Emacs for holidays are based on @emph{current
484 practice}, not historical fact. Historically, for instance, the start
485 of daylight savings time and even its existence have varied from year to
486 year, but present United States law mandates that daylight savings time
487 begins on the first Sunday in April. When the daylight savings rules
488 are set up for the United States, Emacs always uses the present
489 definition, even though it is wrong for some prior years.
492 @section Times of Sunrise and Sunset
493 @cindex sunrise and sunset
495 Special calendar commands can tell you, to within a minute or two, the
496 times of sunrise and sunset for any date.
500 Display times of sunrise and sunset for the selected date
501 (@code{calendar-sunrise-sunset}).
502 @item Mouse-2 Sunrise/sunset
503 Display times of sunrise and sunset for the date you click on.
504 @item M-x sunrise-sunset
505 Display times of sunrise and sunset for today's date.
506 @item C-u M-x sunrise-sunset
507 Display times of sunrise and sunset for a specified date.
510 @kindex S @r{(Calendar mode)}
511 @findex calendar-sunrise-sunset
512 @findex sunrise-sunset
513 Within the calendar, to display the @emph{local times} of sunrise and
514 sunset in the echo area, move point to the date you want, and type
515 @kbd{S}. Alternatively, click @kbd{Mouse-2} on the date, then choose
516 @samp{Sunrise/sunset} from the menu that appears. The command @kbd{M-x
517 sunrise-sunset} is available outside the calendar to display this
518 information for today's date or a specified date. To specify a date
519 other than today, use @kbd{C-u M-x sunrise-sunset}, which prompts for
520 the year, month, and day.
522 You can display the times of sunrise and sunset for any location and
523 any date with @kbd{C-u C-u M-x sunrise-sunset}. This asks you for a
524 longitude, latitude, number of minutes difference from Coordinated
525 Universal Time, and date, and then tells you the times of sunrise and
526 sunset for that location on that date.
528 Because the times of sunrise and sunset depend on the location on
529 earth, you need to tell Emacs your latitude, longitude, and location
530 name before using these commands. Here is an example of what to set:
532 @vindex calendar-location-name
533 @vindex calendar-longitude
534 @vindex calendar-latitude
536 (setq calendar-latitude 40.1)
537 (setq calendar-longitude -88.2)
538 (setq calendar-location-name "Urbana, IL")
542 Use one decimal place in the values of @code{calendar-latitude} and
543 @code{calendar-longitude}.
545 Your time zone also affects the local time of sunrise and sunset.
546 Emacs usually gets time zone information from the operating system, but
547 if these values are not what you want (or if the operating system does
548 not supply them), you must set them yourself. Here is an example:
550 @vindex calendar-time-zone
551 @vindex calendar-standard-time-zone-name
552 @vindex calendar-daylight-time-zone-name
554 (setq calendar-time-zone -360)
555 (setq calendar-standard-time-zone-name "CST")
556 (setq calendar-daylight-time-zone-name "CDT")
560 The value of @code{calendar-time-zone} is the number of minutes
561 difference between your local standard time and Coordinated Universal
562 Time (Greenwich time). The values of
563 @code{calendar-standard-time-zone-name} and
564 @code{calendar-daylight-time-zone-name} are the abbreviations used in
565 your time zone. Emacs displays the times of sunrise and sunset
566 @emph{corrected for daylight savings time}. @xref{Daylight Savings},
567 for how daylight savings time is determined.
569 As a user, you might find it convenient to set the calendar location
570 variables for your usual physical location in your @file{.emacs} file.
571 And when you install Emacs on a machine, you can create a
572 @file{default.el} file which sets them properly for the typical location
573 of most users of that machine. @xref{Init File}.
576 @section Phases of the Moon
577 @cindex phases of the moon
578 @cindex moon, phases of
580 These calendar commands display the dates and times of the phases of
581 the moon (new moon, first quarter, full moon, last quarter). This
582 feature is useful for debugging problems that ``depend on the phase of
587 Display the dates and times for all the quarters of the moon for the
588 three-month period shown (@code{calendar-phases-of-moon}).
589 @item M-x phases-of-moon
590 Display dates and times of the quarters of the moon for three months around
594 @kindex M @r{(Calendar mode)}
595 @findex calendar-phases-of-moon
596 Within the calendar, use the @kbd{M} command to display a separate
597 buffer of the phases of the moon for the current three-month range. The
598 dates and times listed are accurate to within a few minutes.
600 @findex phases-of-moon
601 Outside the calendar, use the command @kbd{M-x phases-of-moon} to
602 display the list of the phases of the moon for the current month and the
603 preceding and succeeding months. For information about a different
604 month, use @kbd{C-u M-x phases-of-moon}, which prompts for the month and
607 The dates and times given for the phases of the moon are given in
608 local time (corrected for daylight savings, when appropriate); but if
609 the variable @code{calendar-time-zone} is void, Coordinated Universal
610 Time (the Greenwich time zone) is used. @xref{Daylight Savings}.
612 @node Other Calendars
613 @section Conversion To and From Other Calendars
615 @cindex Gregorian calendar
616 The Emacs calendar displayed is @emph{always} the Gregorian calendar,
617 sometimes called the ``new style'' calendar, which is used in most of
618 the world today. However, this calendar did not exist before the
619 sixteenth century and was not widely used before the eighteenth century;
620 it did not fully displace the Julian calendar and gain universal
621 acceptance until the early twentieth century. The Emacs calendar can
622 display any month since January, year 1 of the current era, but the
623 calendar displayed is the Gregorian, even for a date at which the
624 Gregorian calendar did not exist.
626 While Emacs cannot display other calendars, it can convert dates to
627 and from several other calendars.
630 * Calendar Systems:: The calendars Emacs understands
631 (aside from Gregorian).
632 * To Other Calendar:: Converting the selected date to various calendars.
633 * From Other Calendar:: Moving to a date specified in another calendar.
634 * Mayan Calendar:: Moving to a date specified in a Mayan calendar.
637 @node Calendar Systems
638 @subsection Supported Calendar Systems
640 @cindex ISO commercial calendar
641 The ISO commercial calendar is used largely in Europe.
643 @cindex Julian calendar
644 The Julian calendar, named after Julius Caesar, was the one used in Europe
645 throughout medieval times, and in many countries up until the nineteenth
648 @cindex Julian day numbers
649 @cindex astronomical day numbers
650 Astronomers use a simple counting of days elapsed since noon, Monday,
651 January 1, 4713 B.C. on the Julian calendar. The number of days elapsed
652 is called the @dfn{Julian day number} or the @dfn{Astronomical day number}.
654 @cindex Hebrew calendar
655 The Hebrew calendar is used by tradition in the Jewish religion. The
656 Emacs calendar program uses the Hebrew calendar to determine the dates
657 of Jewish holidays. Hebrew calendar dates begin and end at sunset.
659 @cindex Islamic calendar
660 The Islamic calendar is used in many predominantly Islamic countries.
661 Emacs uses it to determine the dates of Islamic holidays. There is no
662 universal agreement in the Islamic world about the calendar; Emacs uses
663 a widely accepted version, but the precise dates of Islamic holidays
664 often depend on proclamation by religious authorities, not on
665 calculations. As a consequence, the actual dates of observance can vary
666 slightly from the dates computed by Emacs. Islamic calendar dates begin
669 @cindex French Revolutionary calendar
670 The French Revolutionary calendar was created by the Jacobins after the 1789
671 revolution, to represent a more secular and nature-based view of the annual
672 cycle, and to install a 10-day week in a rationalization measure similar to
673 the metric system. The French government officially abandoned this
674 calendar at the end of 1805.
676 @cindex Mayan calendar
677 The Maya of Central America used three separate, overlapping calendar
678 systems, the @emph{long count}, the @emph{tzolkin}, and the @emph{haab}.
679 Emacs knows about all three of these calendars. Experts dispute the
680 exact correlation between the Mayan calendar and our calendar; Emacs uses the
681 Goodman-Martinez-Thompson correlation in its calculations.
683 @cindex Coptic calendar
684 @cindex Ethiopic calendar
685 The Copts use a calendar based on the ancient Egyptian solar calendar.
686 Their calendar consists of twelve 30-day months followed by an extra
687 five-day period. Once every fourth year they add a leap day to this
688 extra period to make it six days. The Ethiopic calendar is identical in
689 structure, but has different year numbers and month names.
691 @cindex Persian calendar
692 The Persians use a solar calendar based on a design of Omar Khayyam.
693 Their calendar consists of twelve months of which the first six have 31
694 days, the next five have 30 days, and the last has 29 in ordinary years
695 and 30 in leap years. Leap years occur in a complicated pattern every
697 The calendar implemented here is the arithmetical Persian calendar
698 championed by Birashk, based on a 2,820-year cycle. It differs from
699 the astronomical Persian calendar, which is based on astronomical
700 events. As of this writing the first future discrepancy is projected
701 to occur on March 20, 2025. It is currently not clear what the
702 official calendar of Iran will be that far into the future.
704 @cindex Chinese calendar
705 The Chinese calendar is a complicated system of lunar months arranged
706 into solar years. The years go in cycles of sixty, each year containing
707 either twelve months in an ordinary year or thirteen months in a leap
708 year; each month has either 29 or 30 days. Years, ordinary months, and
709 days are named by combining one of ten ``celestial stems'' with one of
710 twelve ``terrestrial branches'' for a total of sixty names that are
711 repeated in a cycle of sixty.
713 @node To Other Calendar
714 @subsection Converting To Other Calendars
716 The following commands describe the selected date (the date at point)
717 in various other calendar systems:
720 @item Mouse-2 Other calendars
721 Display the date that you click on, expressed in various other calendars.
722 @kindex p @r{(Calendar mode)}
723 @findex calendar-print-iso-date
725 Display ISO commercial calendar equivalent for selected day
726 (@code{calendar-print-iso-date}).
727 @findex calendar-print-julian-date
729 Display Julian date for selected day (@code{calendar-print-julian-date}).
730 @findex calendar-print-astro-day-number
732 Display astronomical (Julian) day number for selected day
733 (@code{calendar-print-astro-day-number}).
734 @findex calendar-print-hebrew-date
736 Display Hebrew date for selected day (@code{calendar-print-hebrew-date}).
737 @findex calendar-print-islamic-date
739 Display Islamic date for selected day (@code{calendar-print-islamic-date}).
740 @findex calendar-print-french-date
742 Display French Revolutionary date for selected day
743 (@code{calendar-print-french-date}).
744 @findex calendar-print-chinese-date
746 Display Chinese date for selected day
747 (@code{calendar-print-chinese-date}).
748 @findex calendar-print-coptic-date
750 Display Coptic date for selected day
751 (@code{calendar-print-coptic-date}).
752 @findex calendar-print-ethiopic-date
754 Display Ethiopic date for selected day
755 (@code{calendar-print-ethiopic-date}).
756 @findex calendar-print-persian-date
758 Display Persian date for selected day
759 (@code{calendar-print-persian-date}).
760 @findex calendar-print-mayan-date
762 Display Mayan date for selected day (@code{calendar-print-mayan-date}).
765 If you are using X, the easiest way to translate a date into other
766 calendars is to click on it with @kbd{Mouse-2}, then choose @kbd{Other
767 calendars} from the menu that appears. This displays the equivalent
768 forms of the date in all the calendars Emacs understands, in the form of
769 a menu. (Choosing an alternative from this menu doesn't actually do
770 anything---the menu is used only for display.)
772 Otherwise, move point to the date you want to convert, then type the
773 appropriate command starting with @kbd{p} from the table above. The
774 prefix @kbd{p} is a mnemonic for ``print,'' since Emacs ``prints'' the
775 equivalent date in the echo area.
777 @node From Other Calendar
778 @subsection Converting From Other Calendars
780 You can use the other supported calendars to specify a date to move
781 to. This section describes the commands for doing this using calendars
782 other than Mayan; for the Mayan calendar, see the following section.
784 @kindex g @var{char} @r{(Calendar mode)}
785 @findex calendar-goto-iso-date
786 @findex calendar-goto-iso-week
787 @findex calendar-goto-julian-date
788 @findex calendar-goto-astro-day-number
789 @findex calendar-goto-hebrew-date
790 @findex calendar-goto-islamic-date
791 @findex calendar-goto-french-date
792 @findex calendar-goto-chinese-date
793 @findex calendar-goto-persian-date
794 @findex calendar-goto-coptic-date
795 @findex calendar-goto-ethiopic-date
798 Move to a date specified in the ISO commercial calendar
799 (@code{calendar-goto-iso-date}).
801 Move to a week specified in the ISO commercial calendar
802 (@code{calendar-goto-iso-week}).
804 Move to a date specified in the Julian calendar
805 (@code{calendar-goto-julian-date}).
807 Move to a date specified with an astronomical (Julian) day number
808 (@code{calendar-goto-astro-day-number}).
810 Move to a date specified in the Hebrew calendar
811 (@code{calendar-goto-hebrew-date}).
813 Move to a date specified in the Islamic calendar
814 (@code{calendar-goto-islamic-date}).
816 Move to a date specified in the French Revolutionary calendar
817 (@code{calendar-goto-french-date}).
819 Move to a date specified in the Chinese calendar
820 (@code{calendar-goto-chinese-date}).
822 Move to a date specified in the Persian calendar
823 (@code{calendar-goto-persian-date}).
825 Move to a date specified in the Coptic calendar
826 (@code{calendar-goto-coptic-date}).
828 Move to a date specified in the Ethiopic calendar
829 (@code{calendar-goto-ethiopic-date}).
832 These commands ask you for a date on the other calendar, move point to
833 the Gregorian calendar date equivalent to that date, and display the
834 other calendar's date in the echo area. Emacs uses strict completion
835 (@pxref{Completion}) whenever it asks you to type a month name, so you
836 don't have to worry about the spelling of Hebrew, Islamic, or French names.
838 @findex list-yahrzeit-dates
840 One common question concerning the Hebrew calendar is the computation
841 of the anniversary of a date of death, called a ``yahrzeit.'' The Emacs
842 calendar includes a facility for such calculations. If you are in the
843 calendar, the command @kbd{M-x list-yahrzeit-dates} asks you for a
844 range of years and then displays a list of the yahrzeit dates for those
845 years for the date given by point. If you are not in the calendar,
846 this command first asks you for the date of death and the range of
847 years, and then displays the list of yahrzeit dates.
850 @subsection Converting from the Mayan Calendar
852 Here are the commands to select dates based on the Mayan calendar:
856 Move to a date specified by the long count calendar
857 (@code{calendar-goto-mayan-long-count-date}).
859 Move to the next occurrence of a place in the
860 tzolkin calendar (@code{calendar-next-tzolkin-date}).
862 Move to the previous occurrence of a place in the
863 tzolkin calendar (@code{calendar-previous-tzolkin-date}).
865 Move to the next occurrence of a place in the
866 haab calendar (@code{calendar-next-haab-date}).
868 Move to the previous occurrence of a place in the
869 haab calendar (@code{calendar-previous-haab-date}).
871 Move to the next occurrence of a place in the
872 calendar round (@code{calendar-next-calendar-round-date}).
874 Move to the previous occurrence of a place in the
875 calendar round (@code{calendar-previous-calendar-round-date}).
878 @cindex Mayan long count
879 To understand these commands, you need to understand the Mayan calendars.
880 The @dfn{long count} is a counting of days with these units:
883 1 kin = 1 day@ @ @ 1 uinal = 20 kin@ @ @ 1 tun = 18 uinal
884 1 katun = 20 tun@ @ @ 1 baktun = 20 katun
887 @kindex g m @r{(Calendar mode)}
888 @findex calendar-goto-mayan-long-count-date
890 Thus, the long count date 12.16.11.16.6 means 12 baktun, 16 katun, 11
891 tun, 16 uinal, and 6 kin. The Emacs calendar can handle Mayan long
892 count dates as early as 7.17.18.13.3, but no earlier. When you use the
893 @kbd{g m l} command, type the Mayan long count date with the baktun,
894 katun, tun, uinal, and kin separated by periods.
896 @findex calendar-previous-tzolkin-date
897 @findex calendar-next-tzolkin-date
898 @cindex Mayan tzolkin calendar
899 The Mayan tzolkin calendar is a cycle of 260 days formed by a pair of
900 independent cycles of 13 and 20 days. Since this cycle repeats
901 endlessly, Emacs provides commands to move backward and forward to the
902 previous or next point in the cycle. Type @kbd{g m p t} to go to the
903 previous tzolkin date; Emacs asks you for a tzolkin date and moves point
904 to the previous occurrence of that date. Similarly, type @kbd{g m n t}
905 to go to the next occurrence of a tzolkin date.
907 @findex calendar-previous-haab-date
908 @findex calendar-next-haab-date
909 @cindex Mayan haab calendar
910 The Mayan haab calendar is a cycle of 365 days arranged as 18 months
911 of 20 days each, followed a 5-day monthless period. Like the tzolkin
912 cycle, this cycle repeats endlessly, and there are commands to move
913 backward and forward to the previous or next point in the cycle. Type
914 @kbd{g m p h} to go to the previous haab date; Emacs asks you for a haab
915 date and moves point to the previous occurrence of that date.
916 Similarly, type @kbd{g m n h} to go to the next occurrence of a haab
919 @c This is omitted because it is too long for smallbook format.
920 @c @findex calendar-previous-calendar-round-date
921 @findex calendar-next-calendar-round-date
922 @cindex Mayan calendar round
923 The Maya also used the combination of the tzolkin date and the haab
924 date. This combination is a cycle of about 52 years called a
925 @emph{calendar round}. If you type @kbd{g m p c}, Emacs asks you for
926 both a haab and a tzolkin date and then moves point to the previous
927 occurrence of that combination. Use @kbd{g m n c} to move point to the
928 next occurrence of a combination. These commands signal an error if the
929 haab/tzolkin date combination you have typed is impossible.
931 Emacs uses strict completion (@pxref{Strict Completion}) whenever it
932 asks you to type a Mayan name, so you don't have to worry about
939 The Emacs diary keeps track of appointments or other events on a daily
940 basis, in conjunction with the calendar. To use the diary feature, you
941 must first create a @dfn{diary file} containing a list of events and
942 their dates. Then Emacs can automatically pick out and display the
943 events for today, for the immediate future, or for any specified
946 The name of the diary file is specified by the variable
947 @code{diary-file}; @file{~/diary} is the default. A sample diary file
948 is (note that the file format is essentially the same as that used by
949 the external shell utility @samp{calendar}):
952 12/22/1988 Twentieth wedding anniversary!!
953 &1/1. Happy New Year!
954 10/22 Ruth's birthday.
956 Tuesday--weekly meeting with grad students at 10am
957 Supowit, Shen, Bitner, and Kapoor to attend.
958 1/13/89 Friday the thirteenth!!
959 &thu 4pm squash game with Lloyd.
960 mar 16 Dad's birthday
961 April 15, 1989 Income tax due.
962 &* 15 time cards due.
966 This example uses extra spaces to align the event descriptions of most
967 of the entries. Such formatting is purely a matter of taste.
969 Although you probably will start by creating a diary manually, Emacs
970 provides a number of commands to let you view, add, and change diary
974 * Displaying the Diary:: Viewing diary entries and associated calendar dates.
975 * Format of Diary File:: Entering events in your diary.
976 * Date Formats:: Various ways you can specify dates.
977 * Adding to Diary:: Commands to create diary entries.
978 * Special Diary Entries:: Anniversaries, blocks of dates, cyclic entries, etc.
981 @node Displaying the Diary
982 @subsection Displaying the Diary
984 Once you have created a diary file, you can use the calendar to view
985 it. You can also view today's events outside of Calendar mode.
989 Display all diary entries for the selected date
990 (@code{view-diary-entries}).
992 Display all diary entries for the date you click on.
994 Display the entire diary file (@code{show-all-diary-entries}).
996 Mark all visible dates that have diary entries
997 (@code{mark-diary-entries}).
999 Unmark the calendar window (@code{calendar-unmark}).
1000 @item M-x print-diary-entries
1001 Print hard copy of the diary display as it appears.
1003 Display all diary entries for today's date.
1004 @item M-x diary-mail-entries
1005 Mail yourself email reminders about upcoming diary entries.
1008 @kindex d @r{(Calendar mode)}
1009 @findex view-diary-entries
1010 @vindex view-diary-entries-initially
1011 Displaying the diary entries with @kbd{d} shows in a separate window
1012 the diary entries for the selected date in the calendar. The mode line
1013 of the new window shows the date of the diary entries and any holidays
1014 that fall on that date. If you specify a numeric argument with @kbd{d},
1015 it shows all the diary entries for that many successive days. Thus,
1016 @kbd{2 d} displays all the entries for the selected date and for the
1019 Another way to display the diary entries for a date is to click
1020 @kbd{Mouse-2} on the date, and then choose @kbd{Diary entries} from
1021 the menu that appears. If the variable
1022 @code{view-diary-entries-initially} is non-@code{nil}, creating the
1023 calendar lists the diary entries for the current date (provided the
1024 current date is visible).
1026 @kindex m @r{(Calendar mode)}
1027 @findex mark-diary-entries
1028 @vindex mark-diary-entries-in-calendar
1029 To get a broader view of which days are mentioned in the diary, use
1030 the @kbd{m} command. This displays the dates that have diary entries in
1031 a different face (or places a @samp{+} after these dates, if display
1032 with multiple faces is not available). @inforef{Calendar Customizing,
1033 diary-entry-marker, emacs-xtra}. The command applies both to the
1034 currently visible months and to other months that subsequently become
1035 visible by scrolling. To turn marking off and erase the current marks,
1036 type @kbd{u}, which also turns off holiday marks (@pxref{Holidays}).
1037 If the variable @code{mark-diary-entries-in-calendar} is
1038 non-@code{nil}, creating or updating the calendar marks diary dates
1041 @kindex s @r{(Calendar mode)}
1042 @findex show-all-diary-entries
1043 To see the full diary file, rather than just some of the entries, use
1044 the @kbd{s} command.
1046 Display of selected diary entries uses the selective display feature
1047 to hide entries that don't apply. The diary buffer as you see it is
1048 an illusion, so simply printing the buffer does not print what you see
1049 on your screen. There is a special command to print hard copy of the
1050 diary buffer @emph{as it appears}; this command is @kbd{M-x
1051 print-diary-entries}. It sends the data directly to the printer. You
1052 can customize it like @code{lpr-region} (@pxref{Printing}).
1055 The command @kbd{M-x diary} displays the diary entries for the current
1056 date, independently of the calendar display, and optionally for the next
1057 few days as well; the variable @code{number-of-diary-entries} specifies
1058 how many days to include. @inforef{Diary Customizing,, emacs-xtra}.
1060 If you put @code{(diary)} in your @file{.emacs} file, this
1061 automatically displays a window with the day's diary entries, when you
1062 enter Emacs. The mode line of the displayed window shows the date and
1063 any holidays that fall on that date.
1065 @findex diary-mail-entries
1066 @vindex diary-mail-days
1067 Many users like to receive notice of events in their diary as email.
1068 To send such mail to yourself, use the command @kbd{M-x
1069 diary-mail-entries}. A prefix argument specifies how many days
1070 (starting with today) to check; otherwise, the variable
1071 @code{diary-mail-days} says how many days.
1073 @node Format of Diary File
1074 @subsection The Diary File
1078 Your @dfn{diary file} is a file that records events associated with
1079 particular dates. The name of the diary file is specified by the
1080 variable @code{diary-file}; @file{~/diary} is the default. The
1081 @code{calendar} utility program supports a subset of the format allowed
1082 by the Emacs diary facilities, so you can use that utility to view the
1083 diary file, with reasonable results aside from the entries it cannot
1086 Each entry in the diary file describes one event and consists of one
1087 or more lines. An entry always begins with a date specification at the
1088 left margin. The rest of the entry is simply text to describe the
1089 event. If the entry has more than one line, then the lines after the
1090 first must begin with whitespace to indicate they continue a previous
1091 entry. Lines that do not begin with valid dates and do not continue a
1092 preceding entry are ignored.
1094 You can inhibit the marking of certain diary entries in the calendar
1095 window; to do this, insert an ampersand (@samp{&}) at the beginning of
1096 the entry, before the date. This has no effect on display of the entry
1097 in the diary window; it affects only marks on dates in the calendar
1098 window. Nonmarking entries are especially useful for generic entries
1099 that would otherwise mark many different dates.
1101 If the first line of a diary entry consists only of the date or day
1102 name with no following blanks or punctuation, then the diary window
1103 display doesn't include that line; only the continuation lines appear.
1104 For example, this entry:
1108 Bill B. visits Princeton today
1109 2pm Cognitive Studies Committee meeting
1110 2:30-5:30 Liz at Lawrenceville
1112 7:30pm Dinner at George's
1113 8:00-10:00pm concert
1117 appears in the diary window without the date line at the beginning.
1118 This style of entry looks neater when you display just a single day's
1119 entries, but can cause confusion if you ask for more than one day's
1122 You can edit the diary entries as they appear in the window, but it is
1123 important to remember that the buffer displayed contains the @emph{entire}
1124 diary file, with portions of it concealed from view. This means, for
1125 instance, that the @kbd{C-f} (@code{forward-char}) command can put point
1126 at what appears to be the end of the line, but what is in reality the
1127 middle of some concealed line.
1129 @emph{Be careful when editing the diary entries!} Inserting
1130 additional lines or adding/deleting characters in the middle of a
1131 visible line cannot cause problems, but editing at the end of a line may
1132 not do what you expect. Deleting a line may delete other invisible
1133 entries that follow it. Before editing the diary, it is best to display
1134 the entire file with @kbd{s} (@code{show-all-diary-entries}).
1137 @subsection Date Formats
1139 Here are some sample diary entries, illustrating different ways of
1140 formatting a date. The examples all show dates in American order
1141 (month, day, year), but Calendar mode supports European order (day,
1142 month, year) as an option.
1145 4/20/93 Switch-over to new tabulation system
1146 apr. 25 Start tabulating annual results
1147 4/30 Results for April are due
1148 */25 Monthly cycle finishes
1149 Friday Don't leave without backing up files
1152 The first entry appears only once, on April 20, 1993. The second and
1153 third appear every year on the specified dates, and the fourth uses a
1154 wildcard (asterisk) for the month, so it appears on the 25th of every
1155 month. The final entry appears every week on Friday.
1157 You can use just numbers to express a date, as in
1158 @samp{@var{month}/@var{day}} or @samp{@var{month}/@var{day}/@var{year}}.
1159 This must be followed by a nondigit. In the date itself, @var{month}
1160 and @var{day} are numbers of one or two digits. The optional @var{year}
1161 is also a number, and may be abbreviated to the last two digits; that
1162 is, you can use @samp{11/12/1989} or @samp{11/12/89}.
1164 Dates can also have the form @samp{@var{monthname} @var{day}} or
1165 @samp{@var{monthname} @var{day}, @var{year}}, where the month's name can
1166 be spelled in full or abbreviated (with or without a period). The
1167 preferred abbreviations can be controlled using the variables
1168 @code{calendar-abbrev-length}, @code{calendar-month-abbrev-array}, and
1169 @code{calendar-day-abbrev-array}. The default is to use the first three
1170 letters of a name as its abbreviation. Case is not significant.
1172 A date may be @dfn{generic}; that is, partially unspecified. Then the
1173 entry applies to all dates that match the specification. If the date
1174 does not contain a year, it is generic and applies to any year.
1175 Alternatively, @var{month}, @var{day}, or @var{year} can be a @samp{*};
1176 this matches any month, day, or year, respectively. Thus, a diary entry
1177 @samp{3/*/*} matches any day in March of any year; so does @samp{march
1180 @vindex european-calendar-style
1181 @findex european-calendar
1182 @findex american-calendar
1183 If you prefer the European style of writing dates---in which the day
1184 comes before the month---type @kbd{M-x european-calendar} while in the
1185 calendar, or set the variable @code{european-calendar-style} to @code{t}
1186 @emph{before} using any calendar or diary command. This mode interprets
1187 all dates in the diary in the European manner, and also uses European
1188 style for displaying diary dates. (Note that there is no comma after
1189 the @var{monthname} in the European style.) To go back to the (default)
1190 American style of writing dates, type @kbd{M-x american-calendar}.
1192 You can use the name of a day of the week as a generic date which
1193 applies to any date falling on that day of the week. You can abbreviate
1194 the day of the week to three letters (with or without a period) or spell
1195 it in full; case is not significant.
1197 @node Adding to Diary
1198 @subsection Commands to Add to the Diary
1200 While in the calendar, there are several commands to create diary
1205 Add a diary entry for the selected date (@code{insert-diary-entry}).
1207 Add a diary entry for the selected day of the week (@code{insert-weekly-diary-entry}).
1209 Add a diary entry for the selected day of the month (@code{insert-monthly-diary-entry}).
1211 Add a diary entry for the selected day of the year (@code{insert-yearly-diary-entry}).
1214 @kindex i d @r{(Calendar mode)}
1215 @findex insert-diary-entry
1216 You can make a diary entry for a specific date by selecting that date
1217 in the calendar window and typing the @kbd{i d} command. This command
1218 displays the end of your diary file in another window and inserts the
1219 date; you can then type the rest of the diary entry.
1221 @kindex i w @r{(Calendar mode)}
1222 @findex insert-weekly-diary-entry
1223 @kindex i m @r{(Calendar mode)}
1224 @findex insert-monthly-diary-entry
1225 @kindex i y @r{(Calendar mode)}
1226 @findex insert-yearly-diary-entry
1227 If you want to make a diary entry that applies to a specific day of
1228 the week, select that day of the week (any occurrence will do) and type
1229 @kbd{i w}. This inserts the day-of-week as a generic date; you can then
1230 type the rest of the diary entry. You can make a monthly diary entry in
1231 the same fashion: select the day of the month, use the @kbd{i m}
1232 command, and type the rest of the entry. Similarly, you can insert a
1233 yearly diary entry with the @kbd{i y} command.
1235 All of the above commands make marking diary entries by default. To
1236 make a nonmarking diary entry, give a numeric argument to the command.
1237 For example, @kbd{C-u i w} makes a nonmarking weekly diary entry.
1239 When you modify the diary file, be sure to save the file before
1240 exiting Emacs. Saving the diary file after using any of the above
1241 insertion commands will automatically update the diary marks in the
1242 calendar window, if appropriate. You can use the command
1243 @code{redraw-calendar} to force an update at any time.
1245 @node Special Diary Entries
1246 @subsection Special Diary Entries
1248 In addition to entries based on calendar dates, the diary file can
1249 contain @dfn{sexp entries} for regular events such as anniversaries.
1250 These entries are based on Lisp expressions (sexps) that Emacs evaluates
1251 as it scans the diary file. Instead of a date, a sexp entry contains
1252 @samp{%%} followed by a Lisp expression which must begin and end with
1253 parentheses. The Lisp expression determines which dates the entry
1256 Calendar mode provides commands to insert certain commonly used
1261 Add an anniversary diary entry for the selected date
1262 (@code{insert-anniversary-diary-entry}).
1264 Add a block diary entry for the current region
1265 (@code{insert-block-diary-entry}).
1267 Add a cyclic diary entry starting at the date
1268 (@code{insert-cyclic-diary-entry}).
1271 @kindex i a @r{(Calendar mode)}
1272 @findex insert-anniversary-diary-entry
1273 If you want to make a diary entry that applies to the anniversary of a
1274 specific date, move point to that date and use the @kbd{i a} command.
1275 This displays the end of your diary file in another window and inserts
1276 the anniversary description; you can then type the rest of the diary
1277 entry. The entry looks like this:
1279 @findex diary-anniversary
1281 %%(diary-anniversary 10 31 1948) Arthur's birthday
1285 This entry applies to October 31 in any year after 1948; @samp{10 31
1286 1948} specifies the date. (If you are using the European calendar
1287 style, the month and day are interchanged.) The reason this expression
1288 requires a beginning year is that advanced diary functions can use it to
1289 calculate the number of elapsed years.
1291 A @dfn{block} diary entry applies to a specified range of consecutive
1292 dates. Here is a block diary entry that applies to all dates from June
1293 24, 1990 through July 10, 1990:
1297 %%(diary-block 6 24 1990 7 10 1990) Vacation
1301 The @samp{6 24 1990} indicates the starting date and the @samp{7 10 1990}
1302 indicates the stopping date. (Again, if you are using the European calendar
1303 style, the month and day are interchanged.)
1305 @kindex i b @r{(Calendar mode)}
1306 @findex insert-block-diary-entry
1307 To insert a block entry, place point and the mark on the two
1308 dates that begin and end the range, and type @kbd{i b}. This command
1309 displays the end of your diary file in another window and inserts the
1310 block description; you can then type the diary entry.
1312 @kindex i c @r{(Calendar mode)}
1313 @findex insert-cyclic-diary-entry
1314 @dfn{Cyclic} diary entries repeat after a fixed interval of days. To
1315 create one, select the starting date and use the @kbd{i c} command. The
1316 command prompts for the length of interval, then inserts the entry,
1317 which looks like this:
1319 @findex diary-cyclic
1321 %%(diary-cyclic 50 3 1 1990) Renew medication
1325 This entry applies to March 1, 1990 and every 50th day following;
1326 @samp{3 1 1990} specifies the starting date. (If you are using the
1327 European calendar style, the month and day are interchanged.)
1329 All three of these commands make marking diary entries. To insert a
1330 nonmarking entry, give a numeric argument to the command. For example,
1331 @kbd{C-u i a} makes a nonmarking anniversary diary entry.
1333 Marking sexp diary entries in the calendar is @emph{extremely}
1334 time-consuming, since every date visible in the calendar window must be
1335 individually checked. So it's a good idea to make sexp diary entries
1336 nonmarking (with @samp{&}) when possible.
1338 Another sophisticated kind of sexp entry, a @dfn{floating} diary entry,
1339 specifies a regularly occurring event by offsets specified in days,
1340 weeks, and months. It is comparable to a crontab entry interpreted by
1341 the @code{cron} utility. Here is a nonmarking, floating diary entry
1342 that applies to the last Thursday in November:
1346 &%%(diary-float 11 4 -1) American Thanksgiving
1350 The 11 specifies November (the eleventh month), the 4 specifies Thursday
1351 (the fourth day of the week, where Sunday is numbered zero), and the
1352 @minus{}1 specifies ``last'' (1 would mean ``first,'' 2 would mean
1353 ``second,'' @minus{}2 would mean ``second-to-last,'' and so on). The
1354 month can be a single month or a list of months. Thus you could change
1355 the 11 above to @samp{'(1 2 3)} and have the entry apply to the last
1356 Thursday of January, February, and March. If the month is @code{t}, the
1357 entry applies to all months of the year.@refill
1359 Each of the standard sexp diary entries takes an optional parameter
1360 specifying the name of a face or a single-character string to use when
1361 marking the entry in the calendar. Most generally, sexp diary entries
1362 can perform arbitrary computations to determine when they apply.
1363 @inforef{Sexp Diary Entries,, emacs-xtra}.
1366 @section Appointments
1367 @cindex appointment notification
1369 @vindex appt-display-format
1370 @vindex appt-audible
1371 @vindex appt-display-mode-line
1372 If you have a diary entry for an appointment, and that diary entry
1373 begins with a recognizable time of day, Emacs can warn you several
1374 minutes beforehand that that appointment is pending. Emacs alerts you
1375 to the appointment by displaying a message in your chosen format, as
1376 specified by the variable @code{appt-display-format}. If the value of
1377 @code{appt-audible} is non-@code{nil}, the warning includes an audible
1378 reminder. In addition, if @code{appt-display-mode-line} is
1379 non-@code{nil}, Emacs displays the number of minutes to the
1380 appointment on the mode line.
1382 @vindex appt-display-duration
1383 @vindex appt-disp-window-function
1384 @vindex appt-delete-window-function
1385 If @code{appt-display-format} has the value @code{window}, then the
1386 variable @code{appt-display-duration} controls how long the reminder
1387 window is visible for; and the variables
1388 @code{appt-disp-window-function} and @code{appt-delete-window-function}
1389 give the names of functions used to create and destroy the window,
1392 @findex appt-activate
1393 To enable appointment notification, use the command @kbd{M-x
1394 appt-activate}. With a positive argument, it enables notification;
1395 with a negative argument, it disables notification; with no argument,
1396 it toggles. Enabling notification also sets up an appointment list
1397 for today from the diary file, giving all diary entries found with
1398 recognizable times of day, and reminds you just before each of them.
1400 For example, suppose the diary file contains these lines:
1408 @vindex appt-message-warning-time
1410 Then on Mondays, you will be reminded at around 9:20am about your
1411 coffee break and at around 11:50am about lunch. The variable
1412 @code{appt-message-warning-time} specifies how many minutes in advance
1413 to warn you; its default value is 12 (12 minutes).
1415 You can write times in am/pm style (with @samp{12:00am} standing
1416 for midnight and @samp{12:00pm} standing for noon), or 24-hour
1417 European/military style. You need not be consistent; your diary file
1418 can have a mixture of the two styles. Times must be at the beginning
1419 of lines if they are to be recognized.
1421 @vindex appt-display-diary
1422 Emacs updates the appointments list from the diary file
1423 automatically just after midnight. You can force an update at any
1424 time by re-enabling appointment notification. Both these actions also
1425 display the day's diary buffer, unless you set
1426 @code{appt-display-diary} to @code{nil}. The appointments list is
1427 also updated whenever the diary file is saved.
1432 You can also use the appointment notification facility like an alarm
1433 clock. The command @kbd{M-x appt-add} adds entries to the appointment
1434 list without affecting your diary file. You delete entries from the
1435 appointment list with @kbd{M-x appt-delete}.
1437 @node Importing Diary
1438 @section Importing and Exporting Diary Entries
1440 You can transfer diary entries between Emacs diary files and a
1441 variety of other formats.
1443 @vindex diary-outlook-formats
1444 You can import diary entries from Outlook-generated appointment
1445 messages. While viewing such a message in Rmail or Gnus, do @kbd{M-x
1446 diary-from-outlook} to import the entry. You can make this command
1447 recognize additional appointment message formats by customizing the
1448 variable @code{diary-outlook-formats}.
1450 @cindex iCalendar support
1451 The icalendar package allows you to transfer data between your Emacs
1452 diary file and iCalendar files, which are defined in ``RFC
1453 2445---Internet Calendaring and Scheduling Core Object Specification
1454 (iCalendar)'' (as well as the earlier vCalendar format).
1456 Importing works for ``ordinary'' (i.e. non-recurring) events, but
1457 (at present) may not work correctly (if at all) for recurring events.
1458 Exporting of diary files into iCalendar files should work correctly
1459 for most diary entries. This feature is a work in progress, so the
1460 commands may evolve in future.
1462 @findex icalendar-import-buffer
1463 The command @code{icalendar-import-buffer} extracts
1464 iCalendar data from the current buffer and adds it to your (default)
1465 diary file. This function is also suitable for automatic extraction of
1466 iCalendar data; for example with the Rmail mail client one could use:
1469 (add-hook 'rmail-show-message-hook 'icalendar-import-buffer)
1472 @findex icalendar-import-file
1473 The command @code{icalendar-import-file} imports an iCalendar file
1474 and adds the results to an Emacs diary file. For example:
1477 (icalendar-import-file "/here/is/calendar.ics" "/there/goes/ical-diary")
1481 You can use an @code{#include} directive to add the import file contents
1482 to the main diary file, if these are different files. @inforef{Fancy Diary
1483 Display,, emacs-xtra}.
1485 @findex icalendar-export-file, icalendar-export-region
1486 Use @code{icalendar-export-file} to interactively export an entire
1487 Emacs diary file to iCalendar format. To export only a part of a diary
1488 file, mark the relevant area, and call @code{icalendar-export-region}.
1489 In both cases the result is appended to the target file.
1491 @node Daylight Savings
1492 @section Daylight Savings Time
1493 @cindex daylight savings time
1495 Emacs understands the difference between standard time and daylight
1496 savings time---the times given for sunrise, sunset, solstices,
1497 equinoxes, and the phases of the moon take that into account. The rules
1498 for daylight savings time vary from place to place and have also varied
1499 historically from year to year. To do the job properly, Emacs needs to
1500 know which rules to use.
1502 @vindex calendar-daylight-savings-starts
1503 @vindex calendar-daylight-savings-ends
1504 Some operating systems keep track of the rules that apply to the place
1505 where you are; on these systems, Emacs gets the information it needs
1506 from the system automatically. If some or all of this information is
1507 missing, Emacs fills in the gaps with the rules currently used in
1508 Cambridge, Massachusetts. If the resulting rules are not what you want,
1509 you can tell Emacs the rules to use by setting certain variables:
1510 @code{calendar-daylight-savings-starts} and
1511 @code{calendar-daylight-savings-ends}.
1513 These values should be Lisp expressions that refer to the variable
1514 @code{year}, and evaluate to the Gregorian date on which daylight
1515 savings time starts or (respectively) ends, in the form of a list
1516 @code{(@var{month} @var{day} @var{year})}. The values should be
1517 @code{nil} if your area does not use daylight savings time.
1519 Emacs uses these expressions to determine the starting date of
1520 daylight savings time for the holiday list and for correcting times of
1521 day in the solar and lunar calculations.
1523 The values for Cambridge, Massachusetts are as follows:
1526 (calendar-nth-named-day 1 0 4 year)
1527 (calendar-nth-named-day -1 0 10 year)
1531 That is, the first 0th day (Sunday) of the fourth month (April) in
1532 the year specified by @code{year}, and the last Sunday of the tenth month
1533 (October) of that year. If daylight savings time were
1534 changed to start on October 1, you would set
1535 @code{calendar-daylight-savings-starts} to this:
1541 If there is no daylight savings time at your location, or if you want
1542 all times in standard time, set @code{calendar-daylight-savings-starts}
1543 and @code{calendar-daylight-savings-ends} to @code{nil}.
1545 @vindex calendar-daylight-time-offset
1546 The variable @code{calendar-daylight-time-offset} specifies the
1547 difference between daylight savings time and standard time, measured in
1548 minutes. The value for Cambridge, Massachusetts is 60.
1550 @c @vindex calendar-daylight-savings-starts-time too long!
1551 @vindex calendar-daylight-savings-ends-time
1552 The two variables @code{calendar-daylight-savings-starts-time} and
1553 @code{calendar-daylight-savings-ends-time} specify the number of minutes
1554 after midnight local time when the transition to and from daylight
1555 savings time should occur. For Cambridge, Massachusetts both variables'
1558 @node Time Intervals
1559 @section Summing Time Intervals
1560 @cindex time intervals, summing
1561 @cindex summing time intervals
1564 The timeclock feature adds up time intervals, so you can (for
1565 instance) keep track of how much time you spend working on particular
1568 @findex timeclock-in
1569 @findex timeclock-out
1570 @findex timeclock-change
1571 @findex timeclock-workday-remaining
1572 @findex timeclock-when-to-leave
1573 Use the @kbd{M-x timeclock-in} command when you start working on a
1574 project, and @kbd{M-x timeclock-out} command when you're done. Each
1575 time you do this, it adds one time interval to the record of the
1576 project. You can change to working on a different project with @kbd{M-x
1579 Once you've collected data from a number of time intervals, you can use
1580 @kbd{M-x timeclock-workday-remaining} to see how much time is left to
1581 work today (assuming a typical average of 8 hours a day), and @kbd{M-x
1582 timeclock-when-to-leave} which will calculate when you're ``done.''
1584 @vindex timeclock-modeline-display
1585 @findex timeclock-modeline-display
1586 If you want Emacs to display the amount of time ``left'' of your
1587 workday in the mode line, either customize the
1588 @code{timeclock-modeline-display} variable and set its value to
1589 @code{t}, or invoke the @kbd{M-x timeclock-modeline-display} command.
1591 @vindex timeclock-ask-before-exiting
1592 Terminating the current Emacs session might or might not mean that
1593 you have stopped working on the project and, by default, Emacs asks
1594 you. You can, however, set the value of the variable
1595 @code{timeclock-ask-before-exiting} to @code{nil} (via @kbd{M-x
1596 customize}) to avoid the question; then, only an explicit @kbd{M-x
1597 timeclock-out} or @kbd{M-x timeclock-change} will tell Emacs that the
1598 current interval is over.
1600 @cindex @file{.timelog} file
1601 @vindex timeclock-file
1602 @findex timeclock-reread-log
1603 The timeclock functions work by accumulating the data in a file
1604 called @file{.timelog} in your home directory. You can specify a
1605 different name for this file by customizing the variable
1606 @code{timeclock-file}. If you edit the timeclock file manually, or if
1607 you change the value of any of timeclock's customizable variables, you
1608 should run the command @kbd{M-x timeclock-reread-log} to update the
1609 data in Emacs from the file.
1612 arch-tag: 4531ef09-9df3-449d-9c52-2b5a4a337f92