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}.
28 This chapter describes the basic calendar features.
29 @xref{Advanced Calendar/Diary Usage,,, emacs-xtra, Specialized Emacs
30 Features}, for information about more specialized features.
34 * Calendar Motion:: Moving through the calendar; selecting a date.
35 * Scroll Calendar:: Bringing earlier or later months onto the screen.
36 * Counting Days:: How many days are there between two dates?
37 * General Calendar:: Exiting or recomputing the calendar.
38 * LaTeX Calendar:: Print a calendar using LaTeX.
39 * Holidays:: Displaying dates of holidays.
40 * Sunrise/Sunset:: Displaying local times of sunrise and sunset.
41 * Lunar Phases:: Displaying phases of the moon.
42 * Other Calendars:: Converting dates to other calendar systems.
43 * Diary:: Displaying events from your diary.
44 * Appointments:: Reminders when it's time to do something.
45 * Importing Diary:: Converting diary events to/from other formats.
46 * Daylight Savings:: How to specify when daylight savings time is active.
47 * Time Intervals:: Keeping track of time intervals.
49 * Advanced Calendar/Diary Usage:: Advanced Calendar/Diary customization.
54 @section Movement in the Calendar
56 @cindex moving inside the calendar
57 Calendar mode provides commands to move through the calendar in
58 logical units of time such as days, weeks, months, and years. If you
59 move outside the three months originally displayed, the calendar
60 display ``scrolls'' automatically through time to make the selected
61 date visible. Moving to a date lets you view its holidays or diary
62 entries, or convert it to other calendars; moving by long time periods
63 is also useful simply to scroll the calendar.
66 * Calendar Unit Motion:: Moving by days, weeks, months, and years.
67 * Move to Beginning or End:: Moving to start/end of weeks, months, and years.
68 * Specified Dates:: Moving to the current date or another
72 @node Calendar Unit Motion
73 @subsection Motion by Standard Lengths of Time
75 The commands for movement in the calendar buffer parallel the
76 commands for movement in text. You can move forward and backward by
77 days, weeks, months, and years.
81 Move point one day forward (@code{calendar-forward-day}).
83 Move point one day backward (@code{calendar-backward-day}).
85 Move point one week forward (@code{calendar-forward-week}).
87 Move point one week backward (@code{calendar-backward-week}).
89 Move point one month forward (@code{calendar-forward-month}).
91 Move point one month backward (@code{calendar-backward-month}).
93 Move point one year forward (@code{calendar-forward-year}).
95 Move point one year backward (@code{calendar-backward-year}).
98 @kindex C-f @r{(Calendar mode)}
99 @findex calendar-forward-day
100 @kindex C-b @r{(Calendar mode)}
101 @findex calendar-backward-day
102 @kindex C-n @r{(Calendar mode)}
103 @findex calendar-forward-week
104 @kindex C-p @r{(Calendar mode)}
105 @findex calendar-backward-week
106 The day and week commands are natural analogues of the usual Emacs
107 commands for moving by characters and by lines. Just as @kbd{C-n}
108 usually moves to the same column in the following line, in Calendar
109 mode it moves to the same day in the following week. And @kbd{C-p}
110 moves to the same day in the previous week.
112 The arrow keys are equivalent to @kbd{C-f}, @kbd{C-b}, @kbd{C-n} and
113 @kbd{C-p}, just as they normally are in other modes.
115 @kindex M-@} @r{(Calendar mode)}
116 @findex calendar-forward-month
117 @kindex M-@{ @r{(Calendar mode)}
118 @findex calendar-backward-month
119 @kindex C-x ] @r{(Calendar mode)}
120 @findex calendar-forward-year
121 @kindex C-x [ @r{(Calendar mode)}
122 @findex calendar-forward-year
123 The commands for motion by months and years work like those for
124 weeks, but move a larger distance. The month commands @kbd{M-@}} and
125 @kbd{M-@{} move forward or backward by an entire month. The year
126 commands @kbd{C-x ]} and @w{@kbd{C-x [}} move forward or backward a
129 The easiest way to remember these commands is to consider months and
130 years analogous to paragraphs and pages of text, respectively. But
131 the commands themselves are not quite analogous. The ordinary Emacs
132 paragraph commands move to the beginning or end of a paragraph,
133 whereas these month and year commands move by an entire month or an
134 entire year, keeping the same date within the month or year.
136 All these commands accept a numeric argument as a repeat count.
137 For convenience, the digit keys and the minus sign specify numeric
138 arguments in Calendar mode even without the Meta modifier. For example,
139 @kbd{100 C-f} moves point 100 days forward from its present location.
141 @node Move to Beginning or End
142 @subsection Beginning or End of Week, Month or Year
144 A week (or month, or year) is not just a quantity of days; we think of
145 weeks (months, years) as starting on particular dates. So Calendar mode
146 provides commands to move to the beginning or end of a week, month or
150 @kindex C-a @r{(Calendar mode)}
151 @findex calendar-beginning-of-week
153 Move point to start of week (@code{calendar-beginning-of-week}).
154 @kindex C-e @r{(Calendar mode)}
155 @findex calendar-end-of-week
157 Move point to end of week (@code{calendar-end-of-week}).
158 @kindex M-a @r{(Calendar mode)}
159 @findex calendar-beginning-of-month
161 Move point to start of month (@code{calendar-beginning-of-month}).
162 @kindex M-e @r{(Calendar mode)}
163 @findex calendar-end-of-month
165 Move point to end of month (@code{calendar-end-of-month}).
166 @kindex M-< @r{(Calendar mode)}
167 @findex calendar-beginning-of-year
169 Move point to start of year (@code{calendar-beginning-of-year}).
170 @kindex M-> @r{(Calendar mode)}
171 @findex calendar-end-of-year
173 Move point to end of year (@code{calendar-end-of-year}).
176 These commands also take numeric arguments as repeat counts, with the
177 repeat count indicating how many weeks, months, or years to move
180 @vindex calendar-week-start-day
181 @cindex weeks, which day they start on
182 @cindex calendar, first day of week
183 By default, weeks begin on Sunday. To make them begin on Monday
184 instead, set the variable @code{calendar-week-start-day} to 1.
186 @node Specified Dates
187 @subsection Specified Dates
189 Calendar mode provides commands for moving to a particular date
190 specified in various ways.
194 Move point to specified date (@code{calendar-goto-date}).
196 Move point to specified day of year (@code{calendar-goto-day-of-year}).
198 Move point to specified week of year (@code{calendar-goto-iso-week}).
200 Center calendar around specified month (@code{calendar-other-month}).
202 Move point to today's date (@code{calendar-goto-today}).
205 @kindex g d @r{(Calendar mode)}
206 @findex calendar-goto-date
207 @kbd{g d} (@code{calendar-goto-date}) prompts for a year, a month, and a day
208 of the month, and then moves to that date. Because the calendar includes all
209 dates from the beginning of the current era, you must type the year in its
210 entirety; that is, type @samp{1990}, not @samp{90}.
212 @kindex g D @r{(Calendar mode)}
213 @findex calendar-goto-day-of-year
214 @kindex g w @r{(Calendar mode)}
215 @findex calendar-goto-iso-week
216 @kbd{g D} (@code{calendar-goto-day-of-year}) prompts for a year and
217 day number, and moves to that date. Negative day numbers count
218 backward from the end of the year. @kbd{g w}
219 (@code{calendar-goto-iso-week}) prompts for a year and week number,
220 and moves to that week.
222 @kindex o @r{(Calendar mode)}
223 @findex calendar-other-month
224 @kbd{o} (@code{calendar-other-month}) prompts for a month and year,
225 then centers the three-month calendar around that month.
227 @kindex . @r{(Calendar mode)}
228 @findex calendar-goto-today
229 You can return to today's date with @kbd{.}@:
230 (@code{calendar-goto-today}).
232 @node Scroll Calendar
233 @section Scrolling in the Calendar
235 @cindex scrolling in the calendar
236 The calendar display scrolls automatically through time when you
237 move out of the visible portion. You can also scroll it manually.
238 Imagine that the calendar window contains a long strip of paper with
239 the months on it. Scrolling the calendar means moving the strip
240 horizontally, so that new months become visible in the window.
244 Scroll calendar one month forward (@code{scroll-calendar-left}).
246 Scroll calendar one month backward (@code{scroll-calendar-right}).
249 Scroll calendar three months forward
250 (@code{scroll-calendar-left-three-months}).
253 Scroll calendar three months backward
254 (@code{scroll-calendar-right-three-months}).
257 @kindex < @r{(Calendar mode)}
258 @findex scroll-calendar-left
259 @kindex > @r{(Calendar mode)}
260 @findex scroll-calendar-right
261 The most basic calendar scroll commands scroll by one month at a
262 time. This means that there are two months of overlap between the
263 display before the command and the display after. @kbd{<} scrolls
264 the calendar contents one month to the left; that is, it moves the
265 display forward in time. @kbd{>} scrolls the contents to the
266 right, which moves backwards in time.
268 @kindex C-v @r{(Calendar mode)}
269 @findex scroll-calendar-left-three-months
270 @kindex M-v @r{(Calendar mode)}
271 @findex scroll-calendar-right-three-months
272 The commands @kbd{C-v} and @kbd{M-v} scroll the calendar by an entire
273 ``screenful''---three months---in analogy with the usual meaning of
274 these commands. @kbd{C-v} makes later dates visible and @kbd{M-v} makes
275 earlier dates visible. These commands take a numeric argument as a
276 repeat count; in particular, since @kbd{C-u} multiplies the next command
277 by four, typing @kbd{C-u C-v} scrolls the calendar forward by a year and
278 typing @kbd{C-u M-v} scrolls the calendar backward by a year.
280 The function keys @key{NEXT} and @key{PRIOR} are equivalent to
281 @kbd{C-v} and @kbd{M-v}, just as they are in other modes.
284 @section Counting Days
288 Display the number of days in the current region
289 (@code{calendar-count-days-region}).
292 @kindex M-= @r{(Calendar mode)}
293 @findex calendar-count-days-region
294 To determine the number of days in the region, type @kbd{M-=}
295 (@code{calendar-count-days-region}). The numbers of days shown is
296 @emph{inclusive}; that is, it includes the days specified by mark and
299 @node General Calendar
300 @section Miscellaneous Calendar Commands
304 Display day-in-year (@code{calendar-print-day-of-year}).
306 Regenerate the calendar window (@code{redraw-calendar}).
308 Scroll the next window up (@code{scroll-other-window}).
310 Scroll the next window down (@code{scroll-other-window-down}).
312 Exit from calendar (@code{exit-calendar}).
315 @kindex p d @r{(Calendar mode)}
317 @findex calendar-print-day-of-year
318 To display the number of days elapsed since the start of the year, or
319 the number of days remaining in the year, type the @kbd{p d} command
320 (@code{calendar-print-day-of-year}). This displays both of those
321 numbers in the echo area. The count of days elapsed includes the
322 selected date. The count of days remaining does not include that
325 @kindex C-c C-l @r{(Calendar mode)}
326 @findex redraw-calendar
327 If the calendar window text gets corrupted, type @kbd{C-c C-l}
328 (@code{redraw-calendar}) to redraw it. (This can only happen if you use
329 non-Calendar-mode editing commands.)
331 @kindex SPC @r{(Calendar mode)}
332 In Calendar mode, you can use @kbd{SPC} (@code{scroll-other-window})
333 and @kbd{DEL} (@code{scroll-other-window-down}) to scroll the other
334 window up or down, respectively. This is handy when you display a list
335 of holidays or diary entries in another window.
337 @kindex q @r{(Calendar mode)}
338 @findex exit-calendar
339 To exit from the calendar, type @kbd{q} (@code{exit-calendar}). This
340 buries all buffers related to the calendar, selecting other buffers.
341 (If a frame contains a dedicated calendar window, exiting from the
342 calendar iconifies that frame.)
345 @section LaTeX Calendar
346 @cindex calendar and La@TeX{}
348 The Calendar La@TeX{} commands produce a buffer of La@TeX{} code that
349 prints as a calendar. Depending on the command you use, the printed
350 calendar covers the day, week, month or year that point is in.
352 @kindex t @r{(Calendar mode)}
355 Generate a one-month calendar (@code{cal-tex-cursor-month}).
357 Generate a sideways-printing one-month calendar
358 (@code{cal-tex-cursor-month-landscape}).
360 Generate a one-day calendar
361 (@code{cal-tex-cursor-day}).
363 Generate a one-page calendar for one week
364 (@code{cal-tex-cursor-week}).
366 Generate a two-page calendar for one week
367 (@code{cal-tex-cursor-week2}).
369 Generate an ISO-style calendar for one week
370 (@code{cal-tex-cursor-week-iso}).
372 Generate a calendar for one Monday-starting week
373 (@code{cal-tex-cursor-week-monday}).
375 Generate a Filofax-style two-weeks-at-a-glance calendar
376 (@code{cal-tex-cursor-filofax-2week}).
378 Generate a Filofax-style one-week-at-a-glance calendar
379 (@code{cal-tex-cursor-filofax-week}).
381 Generate a calendar for one year
382 (@code{cal-tex-cursor-year}).
384 Generate a sideways-printing calendar for one year
385 (@code{cal-tex-cursor-year-landscape}).
387 Generate a Filofax-style calendar for one year
388 (@code{cal-tex-cursor-filofax-year}).
391 Some of these commands print the calendar sideways (in ``landscape
392 mode''), so it can be wider than it is long. Some of them use Filofax
393 paper size (3.75in x 6.75in). All of these commands accept a prefix
394 argument which specifies how many days, weeks, months or years to print
395 (starting always with the selected one).
397 If the variable @code{cal-tex-holidays} is non-@code{nil} (the default),
398 then the printed calendars show the holidays in @code{calendar-holidays}.
399 If the variable @code{cal-tex-diary} is non-@code{nil} (the default is
400 @code{nil}), diary entries are included also (in weekly and monthly
401 calendars only). If the variable @code{cal-tex-rules} is non-@code{nil}
402 (the default is @code{nil}), the calendar displays ruled pages
403 in styles that have sufficient room. You can use the variable
404 @code{cal-tex-preamble-extra} to insert extra LaTeX commands in the
405 preamble of the generated document if you need to.
411 The Emacs calendar knows about all major and many minor holidays,
412 and can display them.
416 Display holidays for the selected date
417 (@code{calendar-cursor-holidays}).
418 @item Mouse-2 Holidays
419 Display any holidays for the date you click on.
421 Mark holidays in the calendar window (@code{mark-calendar-holidays}).
423 Unmark calendar window (@code{calendar-unmark}).
425 List all holidays for the displayed three months in another window
426 (@code{list-calendar-holidays}).
428 List all holidays for three months around today's date in another
430 @item M-x list-holidays
431 List holidays in another window for a specified range of years.
434 @kindex h @r{(Calendar mode)}
435 @findex calendar-cursor-holidays
436 @vindex view-calendar-holidays-initially
437 To see if any holidays fall on a given date, position point on that
438 date in the calendar window and use the @kbd{h} command. Alternatively,
439 click on that date with @kbd{Mouse-2} and then choose @kbd{Holidays}
440 from the menu that appears. Either way, this displays the holidays for
441 that date, in the echo area if they fit there, otherwise in a separate
444 @kindex x @r{(Calendar mode)}
445 @findex mark-calendar-holidays
446 @kindex u @r{(Calendar mode)}
447 @findex calendar-unmark
448 @vindex mark-holidays-in-calendar
449 To view the distribution of holidays for all the dates shown in the
450 calendar, use the @kbd{x} command. This displays the dates that are
451 holidays in a different face (or places a @samp{*} after these dates, if
452 display with multiple faces is not available).
454 @xref{Calendar Customizing, calendar-holiday-marker,, emacs-xtra,
455 Specialized Emacs Features}.
458 @xref{Calendar Customizing, calendar-holiday-marker}.
460 The command applies both to the currently visible months and to
461 other months that subsequently become visible by scrolling. To turn
462 marking off and erase the current marks, type @kbd{u}, which also
463 erases any diary marks (@pxref{Diary}). If the variable
464 @code{mark-holidays-in-calendar} is non-@code{nil}, creating or
465 updating the calendar marks holidays automatically.
467 @kindex a @r{(Calendar mode)}
468 @findex list-calendar-holidays
469 To get even more detailed information, use the @kbd{a} command, which
470 displays a separate buffer containing a list of all holidays in the
471 current three-month range. You can use @key{SPC} and @key{DEL} in the
472 calendar window to scroll that list up and down, respectively.
475 The command @kbd{M-x holidays} displays the list of holidays for the
476 current month and the preceding and succeeding months; this works even
477 if you don't have a calendar window. If the variable
478 @code{view-calendar-holidays-initially} is non-@code{nil}, creating
479 the calendar displays holidays in this way. If you want the list of
480 holidays centered around a different month, use @kbd{C-u M-x
481 holidays}, which prompts for the month and year.
483 The holidays known to Emacs include United States holidays and the
484 major Christian, Jewish, and Islamic holidays; also the solstices and
487 @findex list-holidays
488 The command @kbd{M-x list-holidays} displays the list of holidays for
489 a range of years. This function asks you for the starting and stopping
490 years, and allows you to choose all the holidays or one of several
491 categories of holidays. You can use this command even if you don't have
494 The dates used by Emacs for holidays are based on @emph{current
495 practice}, not historical fact. Historically, for instance, the start
496 of daylight savings time and even its existence have varied from year to
497 year, but present United States law mandates that daylight savings time
498 begins on the first Sunday in April. When the daylight savings rules
499 are set up for the United States, Emacs always uses the present
500 definition, even though it is wrong for some prior years.
503 @section Times of Sunrise and Sunset
504 @cindex sunrise and sunset
506 Special calendar commands can tell you, to within a minute or two, the
507 times of sunrise and sunset for any date.
511 Display times of sunrise and sunset for the selected date
512 (@code{calendar-sunrise-sunset}).
513 @item Mouse-2 Sunrise/sunset
514 Display times of sunrise and sunset for the date you click on.
515 @item M-x sunrise-sunset
516 Display times of sunrise and sunset for today's date.
517 @item C-u M-x sunrise-sunset
518 Display times of sunrise and sunset for a specified date.
521 @kindex S @r{(Calendar mode)}
522 @findex calendar-sunrise-sunset
523 @findex sunrise-sunset
524 Within the calendar, to display the @emph{local times} of sunrise and
525 sunset in the echo area, move point to the date you want, and type
526 @kbd{S}. Alternatively, click @kbd{Mouse-2} on the date, then choose
527 @samp{Sunrise/sunset} from the menu that appears. The command @kbd{M-x
528 sunrise-sunset} is available outside the calendar to display this
529 information for today's date or a specified date. To specify a date
530 other than today, use @kbd{C-u M-x sunrise-sunset}, which prompts for
531 the year, month, and day.
533 You can display the times of sunrise and sunset for any location and
534 any date with @kbd{C-u C-u M-x sunrise-sunset}. This asks you for a
535 longitude, latitude, number of minutes difference from Coordinated
536 Universal Time, and date, and then tells you the times of sunrise and
537 sunset for that location on that date.
539 Because the times of sunrise and sunset depend on the location on
540 earth, you need to tell Emacs your latitude, longitude, and location
541 name before using these commands. Here is an example of what to set:
543 @vindex calendar-location-name
544 @vindex calendar-longitude
545 @vindex calendar-latitude
547 (setq calendar-latitude 40.1)
548 (setq calendar-longitude -88.2)
549 (setq calendar-location-name "Urbana, IL")
553 Use one decimal place in the values of @code{calendar-latitude} and
554 @code{calendar-longitude}.
556 Your time zone also affects the local time of sunrise and sunset.
557 Emacs usually gets time zone information from the operating system, but
558 if these values are not what you want (or if the operating system does
559 not supply them), you must set them yourself. Here is an example:
561 @vindex calendar-time-zone
562 @vindex calendar-standard-time-zone-name
563 @vindex calendar-daylight-time-zone-name
565 (setq calendar-time-zone -360)
566 (setq calendar-standard-time-zone-name "CST")
567 (setq calendar-daylight-time-zone-name "CDT")
571 The value of @code{calendar-time-zone} is the number of minutes
572 difference between your local standard time and Coordinated Universal
573 Time (Greenwich time). The values of
574 @code{calendar-standard-time-zone-name} and
575 @code{calendar-daylight-time-zone-name} are the abbreviations used in
576 your time zone. Emacs displays the times of sunrise and sunset
577 @emph{corrected for daylight savings time}. @xref{Daylight Savings},
578 for how daylight savings time is determined.
580 As a user, you might find it convenient to set the calendar location
581 variables for your usual physical location in your @file{.emacs} file.
582 And when you install Emacs on a machine, you can create a
583 @file{default.el} file which sets them properly for the typical location
584 of most users of that machine. @xref{Init File}.
587 @section Phases of the Moon
588 @cindex phases of the moon
589 @cindex moon, phases of
591 These calendar commands display the dates and times of the phases of
592 the moon (new moon, first quarter, full moon, last quarter). This
593 feature is useful for debugging problems that ``depend on the phase of
598 Display the dates and times for all the quarters of the moon for the
599 three-month period shown (@code{calendar-phases-of-moon}).
600 @item M-x phases-of-moon
601 Display dates and times of the quarters of the moon for three months around
605 @kindex M @r{(Calendar mode)}
606 @findex calendar-phases-of-moon
607 Within the calendar, use the @kbd{M} command to display a separate
608 buffer of the phases of the moon for the current three-month range. The
609 dates and times listed are accurate to within a few minutes.
611 @findex phases-of-moon
612 Outside the calendar, use the command @kbd{M-x phases-of-moon} to
613 display the list of the phases of the moon for the current month and the
614 preceding and succeeding months. For information about a different
615 month, use @kbd{C-u M-x phases-of-moon}, which prompts for the month and
618 The dates and times given for the phases of the moon are given in
619 local time (corrected for daylight savings, when appropriate); but if
620 the variable @code{calendar-time-zone} is void, Coordinated Universal
621 Time (the Greenwich time zone) is used. @xref{Daylight Savings}.
623 @node Other Calendars
624 @section Conversion To and From Other Calendars
626 @cindex Gregorian calendar
627 The Emacs calendar displayed is @emph{always} the Gregorian calendar,
628 sometimes called the ``new style'' calendar, which is used in most of
629 the world today. However, this calendar did not exist before the
630 sixteenth century and was not widely used before the eighteenth century;
631 it did not fully displace the Julian calendar and gain universal
632 acceptance until the early twentieth century. The Emacs calendar can
633 display any month since January, year 1 of the current era, but the
634 calendar displayed is the Gregorian, even for a date at which the
635 Gregorian calendar did not exist.
637 While Emacs cannot display other calendars, it can convert dates to
638 and from several other calendars.
641 * Calendar Systems:: The calendars Emacs understands
642 (aside from Gregorian).
643 * To Other Calendar:: Converting the selected date to various calendars.
644 * From Other Calendar:: Moving to a date specified in another calendar.
645 * Mayan Calendar:: Moving to a date specified in a Mayan calendar.
648 @node Calendar Systems
649 @subsection Supported Calendar Systems
651 @cindex ISO commercial calendar
652 The ISO commercial calendar is used largely in Europe.
654 @cindex Julian calendar
655 The Julian calendar, named after Julius Caesar, was the one used in Europe
656 throughout medieval times, and in many countries up until the nineteenth
659 @cindex Julian day numbers
660 @cindex astronomical day numbers
661 Astronomers use a simple counting of days elapsed since noon, Monday,
662 January 1, 4713 B.C. on the Julian calendar. The number of days elapsed
663 is called the @dfn{Julian day number} or the @dfn{Astronomical day number}.
665 @cindex Hebrew calendar
666 The Hebrew calendar is used by tradition in the Jewish religion. The
667 Emacs calendar program uses the Hebrew calendar to determine the dates
668 of Jewish holidays. Hebrew calendar dates begin and end at sunset.
670 @cindex Islamic calendar
671 The Islamic calendar is used in many predominantly Islamic countries.
672 Emacs uses it to determine the dates of Islamic holidays. There is no
673 universal agreement in the Islamic world about the calendar; Emacs uses
674 a widely accepted version, but the precise dates of Islamic holidays
675 often depend on proclamation by religious authorities, not on
676 calculations. As a consequence, the actual dates of observance can vary
677 slightly from the dates computed by Emacs. Islamic calendar dates begin
680 @cindex French Revolutionary calendar
681 The French Revolutionary calendar was created by the Jacobins after the 1789
682 revolution, to represent a more secular and nature-based view of the annual
683 cycle, and to install a 10-day week in a rationalization measure similar to
684 the metric system. The French government officially abandoned this
685 calendar at the end of 1805.
687 @cindex Mayan calendar
688 The Maya of Central America used three separate, overlapping calendar
689 systems, the @emph{long count}, the @emph{tzolkin}, and the @emph{haab}.
690 Emacs knows about all three of these calendars. Experts dispute the
691 exact correlation between the Mayan calendar and our calendar; Emacs uses the
692 Goodman-Martinez-Thompson correlation in its calculations.
694 @cindex Coptic calendar
695 @cindex Ethiopic calendar
696 The Copts use a calendar based on the ancient Egyptian solar calendar.
697 Their calendar consists of twelve 30-day months followed by an extra
698 five-day period. Once every fourth year they add a leap day to this
699 extra period to make it six days. The Ethiopic calendar is identical in
700 structure, but has different year numbers and month names.
702 @cindex Persian calendar
703 The Persians use a solar calendar based on a design of Omar Khayyam.
704 Their calendar consists of twelve months of which the first six have 31
705 days, the next five have 30 days, and the last has 29 in ordinary years
706 and 30 in leap years. Leap years occur in a complicated pattern every
708 The calendar implemented here is the arithmetical Persian calendar
709 championed by Birashk, based on a 2,820-year cycle. It differs from
710 the astronomical Persian calendar, which is based on astronomical
711 events. As of this writing the first future discrepancy is projected
712 to occur on March 20, 2025. It is currently not clear what the
713 official calendar of Iran will be that far into the future.
715 @cindex Chinese calendar
716 The Chinese calendar is a complicated system of lunar months arranged
717 into solar years. The years go in cycles of sixty, each year containing
718 either twelve months in an ordinary year or thirteen months in a leap
719 year; each month has either 29 or 30 days. Years, ordinary months, and
720 days are named by combining one of ten ``celestial stems'' with one of
721 twelve ``terrestrial branches'' for a total of sixty names that are
722 repeated in a cycle of sixty.
724 @node To Other Calendar
725 @subsection Converting To Other Calendars
727 The following commands describe the selected date (the date at point)
728 in various other calendar systems:
731 @item Mouse-2 Other calendars
732 Display the date that you click on, expressed in various other calendars.
733 @kindex p @r{(Calendar mode)}
734 @findex calendar-print-iso-date
736 Display ISO commercial calendar equivalent for selected day
737 (@code{calendar-print-iso-date}).
738 @findex calendar-print-julian-date
740 Display Julian date for selected day (@code{calendar-print-julian-date}).
741 @findex calendar-print-astro-day-number
743 Display astronomical (Julian) day number for selected day
744 (@code{calendar-print-astro-day-number}).
745 @findex calendar-print-hebrew-date
747 Display Hebrew date for selected day (@code{calendar-print-hebrew-date}).
748 @findex calendar-print-islamic-date
750 Display Islamic date for selected day (@code{calendar-print-islamic-date}).
751 @findex calendar-print-french-date
753 Display French Revolutionary date for selected day
754 (@code{calendar-print-french-date}).
755 @findex calendar-print-chinese-date
757 Display Chinese date for selected day
758 (@code{calendar-print-chinese-date}).
759 @findex calendar-print-coptic-date
761 Display Coptic date for selected day
762 (@code{calendar-print-coptic-date}).
763 @findex calendar-print-ethiopic-date
765 Display Ethiopic date for selected day
766 (@code{calendar-print-ethiopic-date}).
767 @findex calendar-print-persian-date
769 Display Persian date for selected day
770 (@code{calendar-print-persian-date}).
771 @findex calendar-print-mayan-date
773 Display Mayan date for selected day (@code{calendar-print-mayan-date}).
776 If you are using X, the easiest way to translate a date into other
777 calendars is to click on it with @kbd{Mouse-2}, then choose @kbd{Other
778 calendars} from the menu that appears. This displays the equivalent
779 forms of the date in all the calendars Emacs understands, in the form of
780 a menu. (Choosing an alternative from this menu doesn't actually do
781 anything---the menu is used only for display.)
783 Otherwise, move point to the date you want to convert, then type the
784 appropriate command starting with @kbd{p} from the table above. The
785 prefix @kbd{p} is a mnemonic for ``print,'' since Emacs ``prints'' the
786 equivalent date in the echo area.
788 @node From Other Calendar
789 @subsection Converting From Other Calendars
791 You can use the other supported calendars to specify a date to move
792 to. This section describes the commands for doing this using calendars
793 other than Mayan; for the Mayan calendar, see the following section.
795 @kindex g @var{char} @r{(Calendar mode)}
796 @findex calendar-goto-iso-date
797 @findex calendar-goto-iso-week
798 @findex calendar-goto-julian-date
799 @findex calendar-goto-astro-day-number
800 @findex calendar-goto-hebrew-date
801 @findex calendar-goto-islamic-date
802 @findex calendar-goto-french-date
803 @findex calendar-goto-chinese-date
804 @findex calendar-goto-persian-date
805 @findex calendar-goto-coptic-date
806 @findex calendar-goto-ethiopic-date
809 Move to a date specified in the ISO commercial calendar
810 (@code{calendar-goto-iso-date}).
812 Move to a week specified in the ISO commercial calendar
813 (@code{calendar-goto-iso-week}).
815 Move to a date specified in the Julian calendar
816 (@code{calendar-goto-julian-date}).
818 Move to a date specified with an astronomical (Julian) day number
819 (@code{calendar-goto-astro-day-number}).
821 Move to a date specified in the Hebrew calendar
822 (@code{calendar-goto-hebrew-date}).
824 Move to a date specified in the Islamic calendar
825 (@code{calendar-goto-islamic-date}).
827 Move to a date specified in the French Revolutionary calendar
828 (@code{calendar-goto-french-date}).
830 Move to a date specified in the Chinese calendar
831 (@code{calendar-goto-chinese-date}).
833 Move to a date specified in the Persian calendar
834 (@code{calendar-goto-persian-date}).
836 Move to a date specified in the Coptic calendar
837 (@code{calendar-goto-coptic-date}).
839 Move to a date specified in the Ethiopic calendar
840 (@code{calendar-goto-ethiopic-date}).
843 These commands ask you for a date on the other calendar, move point to
844 the Gregorian calendar date equivalent to that date, and display the
845 other calendar's date in the echo area. Emacs uses strict completion
846 (@pxref{Completion}) whenever it asks you to type a month name, so you
847 don't have to worry about the spelling of Hebrew, Islamic, or French names.
849 @findex list-yahrzeit-dates
851 One common question concerning the Hebrew calendar is the computation
852 of the anniversary of a date of death, called a ``yahrzeit.'' The Emacs
853 calendar includes a facility for such calculations. If you are in the
854 calendar, the command @kbd{M-x list-yahrzeit-dates} asks you for a
855 range of years and then displays a list of the yahrzeit dates for those
856 years for the date given by point. If you are not in the calendar,
857 this command first asks you for the date of death and the range of
858 years, and then displays the list of yahrzeit dates.
861 @subsection Converting from the Mayan Calendar
863 Here are the commands to select dates based on the Mayan calendar:
867 Move to a date specified by the long count calendar
868 (@code{calendar-goto-mayan-long-count-date}).
870 Move to the next occurrence of a place in the
871 tzolkin calendar (@code{calendar-next-tzolkin-date}).
873 Move to the previous occurrence of a place in the
874 tzolkin calendar (@code{calendar-previous-tzolkin-date}).
876 Move to the next occurrence of a place in the
877 haab calendar (@code{calendar-next-haab-date}).
879 Move to the previous occurrence of a place in the
880 haab calendar (@code{calendar-previous-haab-date}).
882 Move to the next occurrence of a place in the
883 calendar round (@code{calendar-next-calendar-round-date}).
885 Move to the previous occurrence of a place in the
886 calendar round (@code{calendar-previous-calendar-round-date}).
889 @cindex Mayan long count
890 To understand these commands, you need to understand the Mayan calendars.
891 The @dfn{long count} is a counting of days with these units:
894 1 kin = 1 day@ @ @ 1 uinal = 20 kin@ @ @ 1 tun = 18 uinal
895 1 katun = 20 tun@ @ @ 1 baktun = 20 katun
898 @kindex g m @r{(Calendar mode)}
899 @findex calendar-goto-mayan-long-count-date
901 Thus, the long count date 12.16.11.16.6 means 12 baktun, 16 katun, 11
902 tun, 16 uinal, and 6 kin. The Emacs calendar can handle Mayan long
903 count dates as early as 7.17.18.13.3, but no earlier. When you use the
904 @kbd{g m l} command, type the Mayan long count date with the baktun,
905 katun, tun, uinal, and kin separated by periods.
907 @findex calendar-previous-tzolkin-date
908 @findex calendar-next-tzolkin-date
909 @cindex Mayan tzolkin calendar
910 The Mayan tzolkin calendar is a cycle of 260 days formed by a pair of
911 independent cycles of 13 and 20 days. Since this cycle repeats
912 endlessly, Emacs provides commands to move backward and forward to the
913 previous or next point in the cycle. Type @kbd{g m p t} to go to the
914 previous tzolkin date; Emacs asks you for a tzolkin date and moves point
915 to the previous occurrence of that date. Similarly, type @kbd{g m n t}
916 to go to the next occurrence of a tzolkin date.
918 @findex calendar-previous-haab-date
919 @findex calendar-next-haab-date
920 @cindex Mayan haab calendar
921 The Mayan haab calendar is a cycle of 365 days arranged as 18 months
922 of 20 days each, followed a 5-day monthless period. Like the tzolkin
923 cycle, this cycle repeats endlessly, and there are commands to move
924 backward and forward to the previous or next point in the cycle. Type
925 @kbd{g m p h} to go to the previous haab date; Emacs asks you for a haab
926 date and moves point to the previous occurrence of that date.
927 Similarly, type @kbd{g m n h} to go to the next occurrence of a haab
930 @c This is omitted because it is too long for smallbook format.
931 @c @findex calendar-previous-calendar-round-date
932 @findex calendar-next-calendar-round-date
933 @cindex Mayan calendar round
934 The Maya also used the combination of the tzolkin date and the haab
935 date. This combination is a cycle of about 52 years called a
936 @emph{calendar round}. If you type @kbd{g m p c}, Emacs asks you for
937 both a haab and a tzolkin date and then moves point to the previous
938 occurrence of that combination. Use @kbd{g m n c} to move point to the
939 next occurrence of a combination. These commands signal an error if the
940 haab/tzolkin date combination you have typed is impossible.
942 Emacs uses strict completion (@pxref{Strict Completion}) whenever it
943 asks you to type a Mayan name, so you don't have to worry about
950 The Emacs diary keeps track of appointments or other events on a daily
951 basis, in conjunction with the calendar. To use the diary feature, you
952 must first create a @dfn{diary file} containing a list of events and
953 their dates. Then Emacs can automatically pick out and display the
954 events for today, for the immediate future, or for any specified
957 The name of the diary file is specified by the variable
958 @code{diary-file}; @file{~/diary} is the default. A sample diary file
959 is (note that the file format is essentially the same as that used by
960 the external shell utility @samp{calendar}):
963 12/22/1988 Twentieth wedding anniversary!!
964 &1/1. Happy New Year!
965 10/22 Ruth's birthday.
967 Tuesday--weekly meeting with grad students at 10am
968 Supowit, Shen, Bitner, and Kapoor to attend.
969 1/13/89 Friday the thirteenth!!
970 &thu 4pm squash game with Lloyd.
971 mar 16 Dad's birthday
972 April 15, 1989 Income tax due.
973 &* 15 time cards due.
977 This example uses extra spaces to align the event descriptions of most
978 of the entries. Such formatting is purely a matter of taste.
980 Although you probably will start by creating a diary manually, Emacs
981 provides a number of commands to let you view, add, and change diary
985 * Displaying the Diary:: Viewing diary entries and associated calendar dates.
986 * Format of Diary File:: Entering events in your diary.
987 * Date Formats:: Various ways you can specify dates.
988 * Adding to Diary:: Commands to create diary entries.
989 * Special Diary Entries:: Anniversaries, blocks of dates, cyclic entries, etc.
992 @node Displaying the Diary
993 @subsection Displaying the Diary
995 Once you have created a diary file, you can use the calendar to view
996 it. You can also view today's events outside of Calendar mode.
1000 Display all diary entries for the selected date
1001 (@code{view-diary-entries}).
1003 Display all diary entries for the date you click on.
1005 Display the entire diary file (@code{show-all-diary-entries}).
1007 Mark all visible dates that have diary entries
1008 (@code{mark-diary-entries}).
1010 Unmark the calendar window (@code{calendar-unmark}).
1011 @item M-x print-diary-entries
1012 Print hard copy of the diary display as it appears.
1014 Display all diary entries for today's date.
1015 @item M-x diary-mail-entries
1016 Mail yourself email reminders about upcoming diary entries.
1019 @kindex d @r{(Calendar mode)}
1020 @findex view-diary-entries
1021 @vindex view-diary-entries-initially
1022 Displaying the diary entries with @kbd{d} shows in a separate window
1023 the diary entries for the selected date in the calendar. The mode line
1024 of the new window shows the date of the diary entries and any holidays
1025 that fall on that date. If you specify a numeric argument with @kbd{d},
1026 it shows all the diary entries for that many successive days. Thus,
1027 @kbd{2 d} displays all the entries for the selected date and for the
1030 Another way to display the diary entries for a date is to click
1031 @kbd{Mouse-2} on the date, and then choose @kbd{Diary entries} from
1032 the menu that appears. If the variable
1033 @code{view-diary-entries-initially} is non-@code{nil}, creating the
1034 calendar lists the diary entries for the current date (provided the
1035 current date is visible).
1037 @kindex m @r{(Calendar mode)}
1038 @findex mark-diary-entries
1039 @vindex mark-diary-entries-in-calendar
1040 To get a broader view of which days are mentioned in the diary, use
1041 the @kbd{m} command. This displays the dates that have diary entries in
1042 a different face (or places a @samp{+} after these dates, if display
1043 with multiple faces is not available).
1045 @xref{Calendar Customizing, diary-entry-marker,, emacs-xtra,
1046 Specialized Emacs Features}.
1049 @xref{Calendar Customizing, diary-entry-marker}.
1051 The command applies both to the currently visible months and to
1052 other months that subsequently become visible by scrolling. To turn
1053 marking off and erase the current marks, type @kbd{u}, which also
1054 turns off holiday marks (@pxref{Holidays}). If the variable
1055 @code{mark-diary-entries-in-calendar} is non-@code{nil}, creating or
1056 updating the calendar marks diary dates automatically.
1058 @kindex s @r{(Calendar mode)}
1059 @findex show-all-diary-entries
1060 To see the full diary file, rather than just some of the entries, use
1061 the @kbd{s} command.
1063 Display of selected diary entries uses the selective display feature
1064 to hide entries that don't apply. The diary buffer as you see it is
1065 an illusion, so simply printing the buffer does not print what you see
1066 on your screen. There is a special command to print hard copy of the
1067 diary buffer @emph{as it appears}; this command is @kbd{M-x
1068 print-diary-entries}. It sends the data directly to the printer. You
1069 can customize it like @code{lpr-region} (@pxref{Printing}).
1072 The command @kbd{M-x diary} displays the diary entries for the current
1073 date, independently of the calendar display, and optionally for the next
1074 few days as well; the variable @code{number-of-diary-entries} specifies
1075 how many days to include.
1077 @xref{Diary Customizing,,, emacs-xtra, Specialized Emacs Features}.
1080 @xref{Diary Customizing, number-of-diary-entries}.
1083 If you put @code{(diary)} in your @file{.emacs} file, this
1084 automatically displays a window with the day's diary entries, when you
1085 enter Emacs. The mode line of the displayed window shows the date and
1086 any holidays that fall on that date.
1088 @findex diary-mail-entries
1089 @vindex diary-mail-days
1090 Many users like to receive notice of events in their diary as email.
1091 To send such mail to yourself, use the command @kbd{M-x
1092 diary-mail-entries}. A prefix argument specifies how many days
1093 (starting with today) to check; otherwise, the variable
1094 @code{diary-mail-days} says how many days.
1096 @node Format of Diary File
1097 @subsection The Diary File
1101 Your @dfn{diary file} is a file that records events associated with
1102 particular dates. The name of the diary file is specified by the
1103 variable @code{diary-file}; @file{~/diary} is the default. The
1104 @code{calendar} utility program supports a subset of the format allowed
1105 by the Emacs diary facilities, so you can use that utility to view the
1106 diary file, with reasonable results aside from the entries it cannot
1109 Each entry in the diary file describes one event and consists of one
1110 or more lines. An entry always begins with a date specification at the
1111 left margin. The rest of the entry is simply text to describe the
1112 event. If the entry has more than one line, then the lines after the
1113 first must begin with whitespace to indicate they continue a previous
1114 entry. Lines that do not begin with valid dates and do not continue a
1115 preceding entry are ignored.
1117 You can inhibit the marking of certain diary entries in the calendar
1118 window; to do this, insert an ampersand (@samp{&}) at the beginning of
1119 the entry, before the date. This has no effect on display of the entry
1120 in the diary window; it affects only marks on dates in the calendar
1121 window. Nonmarking entries are especially useful for generic entries
1122 that would otherwise mark many different dates.
1124 If the first line of a diary entry consists only of the date or day
1125 name with no following blanks or punctuation, then the diary window
1126 display doesn't include that line; only the continuation lines appear.
1127 For example, this entry:
1131 Bill B. visits Princeton today
1132 2pm Cognitive Studies Committee meeting
1133 2:30-5:30 Liz at Lawrenceville
1135 7:30pm Dinner at George's
1136 8:00-10:00pm concert
1140 appears in the diary window without the date line at the beginning.
1141 This style of entry looks neater when you display just a single day's
1142 entries, but can cause confusion if you ask for more than one day's
1145 You can edit the diary entries as they appear in the window, but it is
1146 important to remember that the buffer displayed contains the @emph{entire}
1147 diary file, with portions of it concealed from view. This means, for
1148 instance, that the @kbd{C-f} (@code{forward-char}) command can put point
1149 at what appears to be the end of the line, but what is in reality the
1150 middle of some concealed line.
1152 @emph{Be careful when editing the diary entries!} Inserting
1153 additional lines or adding/deleting characters in the middle of a
1154 visible line cannot cause problems, but editing at the end of a line may
1155 not do what you expect. Deleting a line may delete other invisible
1156 entries that follow it. Before editing the diary, it is best to display
1157 the entire file with @kbd{s} (@code{show-all-diary-entries}).
1160 @subsection Date Formats
1162 Here are some sample diary entries, illustrating different ways of
1163 formatting a date. The examples all show dates in American order
1164 (month, day, year), but Calendar mode supports European order (day,
1165 month, year) as an option.
1168 4/20/93 Switch-over to new tabulation system
1169 apr. 25 Start tabulating annual results
1170 4/30 Results for April are due
1171 */25 Monthly cycle finishes
1172 Friday Don't leave without backing up files
1175 The first entry appears only once, on April 20, 1993. The second and
1176 third appear every year on the specified dates, and the fourth uses a
1177 wildcard (asterisk) for the month, so it appears on the 25th of every
1178 month. The final entry appears every week on Friday.
1180 You can use just numbers to express a date, as in
1181 @samp{@var{month}/@var{day}} or @samp{@var{month}/@var{day}/@var{year}}.
1182 This must be followed by a nondigit. In the date itself, @var{month}
1183 and @var{day} are numbers of one or two digits. The optional @var{year}
1184 is also a number, and may be abbreviated to the last two digits; that
1185 is, you can use @samp{11/12/1989} or @samp{11/12/89}.
1187 Dates can also have the form @samp{@var{monthname} @var{day}} or
1188 @samp{@var{monthname} @var{day}, @var{year}}, where the month's name can
1189 be spelled in full or abbreviated (with or without a period). The
1190 preferred abbreviations can be controlled using the variables
1191 @code{calendar-abbrev-length}, @code{calendar-month-abbrev-array}, and
1192 @code{calendar-day-abbrev-array}. The default is to use the first three
1193 letters of a name as its abbreviation. Case is not significant.
1195 A date may be @dfn{generic}; that is, partially unspecified. Then the
1196 entry applies to all dates that match the specification. If the date
1197 does not contain a year, it is generic and applies to any year.
1198 Alternatively, @var{month}, @var{day}, or @var{year} can be a @samp{*};
1199 this matches any month, day, or year, respectively. Thus, a diary entry
1200 @samp{3/*/*} matches any day in March of any year; so does @samp{march
1203 @vindex european-calendar-style
1204 @findex european-calendar
1205 @findex american-calendar
1206 If you prefer the European style of writing dates---in which the day
1207 comes before the month---type @kbd{M-x european-calendar} while in the
1208 calendar, or set the variable @code{european-calendar-style} to @code{t}
1209 @emph{before} using any calendar or diary command. This mode interprets
1210 all dates in the diary in the European manner, and also uses European
1211 style for displaying diary dates. (Note that there is no comma after
1212 the @var{monthname} in the European style.) To go back to the (default)
1213 American style of writing dates, type @kbd{M-x american-calendar}.
1215 You can use the name of a day of the week as a generic date which
1216 applies to any date falling on that day of the week. You can abbreviate
1217 the day of the week to three letters (with or without a period) or spell
1218 it in full; case is not significant.
1220 @node Adding to Diary
1221 @subsection Commands to Add to the Diary
1223 While in the calendar, there are several commands to create diary
1228 Add a diary entry for the selected date (@code{insert-diary-entry}).
1230 Add a diary entry for the selected day of the week (@code{insert-weekly-diary-entry}).
1232 Add a diary entry for the selected day of the month (@code{insert-monthly-diary-entry}).
1234 Add a diary entry for the selected day of the year (@code{insert-yearly-diary-entry}).
1237 @kindex i d @r{(Calendar mode)}
1238 @findex insert-diary-entry
1239 You can make a diary entry for a specific date by selecting that date
1240 in the calendar window and typing the @kbd{i d} command. This command
1241 displays the end of your diary file in another window and inserts the
1242 date; you can then type the rest of the diary entry.
1244 @kindex i w @r{(Calendar mode)}
1245 @findex insert-weekly-diary-entry
1246 @kindex i m @r{(Calendar mode)}
1247 @findex insert-monthly-diary-entry
1248 @kindex i y @r{(Calendar mode)}
1249 @findex insert-yearly-diary-entry
1250 If you want to make a diary entry that applies to a specific day of
1251 the week, select that day of the week (any occurrence will do) and type
1252 @kbd{i w}. This inserts the day-of-week as a generic date; you can then
1253 type the rest of the diary entry. You can make a monthly diary entry in
1254 the same fashion: select the day of the month, use the @kbd{i m}
1255 command, and type the rest of the entry. Similarly, you can insert a
1256 yearly diary entry with the @kbd{i y} command.
1258 All of the above commands make marking diary entries by default. To
1259 make a nonmarking diary entry, give a numeric argument to the command.
1260 For example, @kbd{C-u i w} makes a nonmarking weekly diary entry.
1262 When you modify the diary file, be sure to save the file before
1263 exiting Emacs. Saving the diary file after using any of the above
1264 insertion commands will automatically update the diary marks in the
1265 calendar window, if appropriate. You can use the command
1266 @code{redraw-calendar} to force an update at any time.
1268 @node Special Diary Entries
1269 @subsection Special Diary Entries
1271 In addition to entries based on calendar dates, the diary file can
1272 contain @dfn{sexp entries} for regular events such as anniversaries.
1273 These entries are based on Lisp expressions (sexps) that Emacs evaluates
1274 as it scans the diary file. Instead of a date, a sexp entry contains
1275 @samp{%%} followed by a Lisp expression which must begin and end with
1276 parentheses. The Lisp expression determines which dates the entry
1279 Calendar mode provides commands to insert certain commonly used
1284 Add an anniversary diary entry for the selected date
1285 (@code{insert-anniversary-diary-entry}).
1287 Add a block diary entry for the current region
1288 (@code{insert-block-diary-entry}).
1290 Add a cyclic diary entry starting at the date
1291 (@code{insert-cyclic-diary-entry}).
1294 @kindex i a @r{(Calendar mode)}
1295 @findex insert-anniversary-diary-entry
1296 If you want to make a diary entry that applies to the anniversary of a
1297 specific date, move point to that date and use the @kbd{i a} command.
1298 This displays the end of your diary file in another window and inserts
1299 the anniversary description; you can then type the rest of the diary
1300 entry. The entry looks like this:
1302 @findex diary-anniversary
1304 %%(diary-anniversary 10 31 1948) Arthur's birthday
1308 This entry applies to October 31 in any year after 1948; @samp{10 31
1309 1948} specifies the date. (If you are using the European calendar
1310 style, the month and day are interchanged.) The reason this expression
1311 requires a beginning year is that advanced diary functions can use it to
1312 calculate the number of elapsed years.
1314 A @dfn{block} diary entry applies to a specified range of consecutive
1315 dates. Here is a block diary entry that applies to all dates from June
1316 24, 1990 through July 10, 1990:
1320 %%(diary-block 6 24 1990 7 10 1990) Vacation
1324 The @samp{6 24 1990} indicates the starting date and the @samp{7 10 1990}
1325 indicates the stopping date. (Again, if you are using the European calendar
1326 style, the month and day are interchanged.)
1328 @kindex i b @r{(Calendar mode)}
1329 @findex insert-block-diary-entry
1330 To insert a block entry, place point and the mark on the two
1331 dates that begin and end the range, and type @kbd{i b}. This command
1332 displays the end of your diary file in another window and inserts the
1333 block description; you can then type the diary entry.
1335 @kindex i c @r{(Calendar mode)}
1336 @findex insert-cyclic-diary-entry
1337 @dfn{Cyclic} diary entries repeat after a fixed interval of days. To
1338 create one, select the starting date and use the @kbd{i c} command. The
1339 command prompts for the length of interval, then inserts the entry,
1340 which looks like this:
1342 @findex diary-cyclic
1344 %%(diary-cyclic 50 3 1 1990) Renew medication
1348 This entry applies to March 1, 1990 and every 50th day following;
1349 @samp{3 1 1990} specifies the starting date. (If you are using the
1350 European calendar style, the month and day are interchanged.)
1352 All three of these commands make marking diary entries. To insert a
1353 nonmarking entry, give a numeric argument to the command. For example,
1354 @kbd{C-u i a} makes a nonmarking anniversary diary entry.
1356 Marking sexp diary entries in the calendar is @emph{extremely}
1357 time-consuming, since every date visible in the calendar window must be
1358 individually checked. So it's a good idea to make sexp diary entries
1359 nonmarking (with @samp{&}) when possible.
1361 Another sophisticated kind of sexp entry, a @dfn{floating} diary entry,
1362 specifies a regularly occurring event by offsets specified in days,
1363 weeks, and months. It is comparable to a crontab entry interpreted by
1364 the @code{cron} utility. Here is a nonmarking, floating diary entry
1365 that applies to the last Thursday in November:
1369 &%%(diary-float 11 4 -1) American Thanksgiving
1373 The 11 specifies November (the eleventh month), the 4 specifies Thursday
1374 (the fourth day of the week, where Sunday is numbered zero), and the
1375 @minus{}1 specifies ``last'' (1 would mean ``first,'' 2 would mean
1376 ``second,'' @minus{}2 would mean ``second-to-last,'' and so on). The
1377 month can be a single month or a list of months. Thus you could change
1378 the 11 above to @samp{'(1 2 3)} and have the entry apply to the last
1379 Thursday of January, February, and March. If the month is @code{t}, the
1380 entry applies to all months of the year.@refill
1382 Each of the standard sexp diary entries takes an optional parameter
1383 specifying the name of a face or a single-character string to use when
1384 marking the entry in the calendar. Most generally, sexp diary entries
1385 can perform arbitrary computations to determine when they apply.
1387 @xref{Sexp Diary Entries,,, emacs-xtra, Specialized Emacs Features}.
1390 @inforef{Sexp Diary Entries}.
1394 @section Appointments
1395 @cindex appointment notification
1397 @vindex appt-display-format
1398 @vindex appt-audible
1399 @vindex appt-display-mode-line
1400 If you have a diary entry for an appointment, and that diary entry
1401 begins with a recognizable time of day, Emacs can warn you several
1402 minutes beforehand that that appointment is pending. Emacs alerts you
1403 to the appointment by displaying a message in your chosen format, as
1404 specified by the variable @code{appt-display-format}. If the value of
1405 @code{appt-audible} is non-@code{nil}, the warning includes an audible
1406 reminder. In addition, if @code{appt-display-mode-line} is
1407 non-@code{nil}, Emacs displays the number of minutes to the
1408 appointment on the mode line.
1410 @vindex appt-display-duration
1411 @vindex appt-disp-window-function
1412 @vindex appt-delete-window-function
1413 If @code{appt-display-format} has the value @code{window}, then the
1414 variable @code{appt-display-duration} controls how long the reminder
1415 window is visible for; and the variables
1416 @code{appt-disp-window-function} and @code{appt-delete-window-function}
1417 give the names of functions used to create and destroy the window,
1420 @findex appt-activate
1421 To enable appointment notification, use the command @kbd{M-x
1422 appt-activate}. With a positive argument, it enables notification;
1423 with a negative argument, it disables notification; with no argument,
1424 it toggles. Enabling notification also sets up an appointment list
1425 for today from the diary file, giving all diary entries found with
1426 recognizable times of day, and reminds you just before each of them.
1428 For example, suppose the diary file contains these lines:
1436 @vindex appt-message-warning-time
1438 Then on Mondays, you will be reminded at around 9:20am about your
1439 coffee break and at around 11:50am about lunch. The variable
1440 @code{appt-message-warning-time} specifies how many minutes in advance
1441 to warn you; its default value is 12 (12 minutes).
1443 You can write times in am/pm style (with @samp{12:00am} standing
1444 for midnight and @samp{12:00pm} standing for noon), or 24-hour
1445 European/military style. You need not be consistent; your diary file
1446 can have a mixture of the two styles. Times must be at the beginning
1447 of lines if they are to be recognized.
1449 @vindex appt-display-diary
1450 Emacs updates the appointments list from the diary file
1451 automatically just after midnight. You can force an update at any
1452 time by re-enabling appointment notification. Both these actions also
1453 display the day's diary buffer, unless you set
1454 @code{appt-display-diary} to @code{nil}. The appointments list is
1455 also updated whenever the diary file is saved.
1460 You can also use the appointment notification facility like an alarm
1461 clock. The command @kbd{M-x appt-add} adds entries to the appointment
1462 list without affecting your diary file. You delete entries from the
1463 appointment list with @kbd{M-x appt-delete}.
1465 @node Importing Diary
1466 @section Importing and Exporting Diary Entries
1468 You can transfer diary entries between Emacs diary files and a
1469 variety of other formats.
1471 @vindex diary-outlook-formats
1472 You can import diary entries from Outlook-generated appointment
1473 messages. While viewing such a message in Rmail or Gnus, do @kbd{M-x
1474 diary-from-outlook} to import the entry. You can make this command
1475 recognize additional appointment message formats by customizing the
1476 variable @code{diary-outlook-formats}.
1478 @cindex iCalendar support
1479 The icalendar package allows you to transfer data between your Emacs
1480 diary file and iCalendar files, which are defined in ``RFC
1481 2445---Internet Calendaring and Scheduling Core Object Specification
1482 (iCalendar)'' (as well as the earlier vCalendar format).
1484 Importing works for ``ordinary'' (i.e. non-recurring) events, but
1485 (at present) may not work correctly (if at all) for recurring events.
1486 Exporting of diary files into iCalendar files should work correctly
1487 for most diary entries. This feature is a work in progress, so the
1488 commands may evolve in future.
1490 @findex icalendar-import-buffer
1491 The command @code{icalendar-import-buffer} extracts
1492 iCalendar data from the current buffer and adds it to your (default)
1493 diary file. This function is also suitable for automatic extraction of
1494 iCalendar data; for example with the Rmail mail client one could use:
1497 (add-hook 'rmail-show-message-hook 'icalendar-import-buffer)
1500 @findex icalendar-import-file
1501 The command @code{icalendar-import-file} imports an iCalendar file
1502 and adds the results to an Emacs diary file. For example:
1505 (icalendar-import-file "/here/is/calendar.ics" "/there/goes/ical-diary")
1509 You can use an @code{#include} directive to add the import file contents
1510 to the main diary file, if these are different files.
1512 @xref{Fancy Diary Display,,, emacs-xtra, Specialized Emacs Features}.
1515 @xref{Fancy Diary Display}.
1519 @findex icalendar-export-file, icalendar-export-region
1520 Use @code{icalendar-export-file} to interactively export an entire
1521 Emacs diary file to iCalendar format. To export only a part of a diary
1522 file, mark the relevant area, and call @code{icalendar-export-region}.
1523 In both cases the result is appended to the target file.
1525 @node Daylight Savings
1526 @section Daylight Savings Time
1527 @cindex daylight savings time
1529 Emacs understands the difference between standard time and daylight
1530 savings time---the times given for sunrise, sunset, solstices,
1531 equinoxes, and the phases of the moon take that into account. The rules
1532 for daylight savings time vary from place to place and have also varied
1533 historically from year to year. To do the job properly, Emacs needs to
1534 know which rules to use.
1536 @vindex calendar-daylight-savings-starts
1537 @vindex calendar-daylight-savings-ends
1538 Some operating systems keep track of the rules that apply to the place
1539 where you are; on these systems, Emacs gets the information it needs
1540 from the system automatically. If some or all of this information is
1541 missing, Emacs fills in the gaps with the rules currently used in
1542 Cambridge, Massachusetts. If the resulting rules are not what you want,
1543 you can tell Emacs the rules to use by setting certain variables:
1544 @code{calendar-daylight-savings-starts} and
1545 @code{calendar-daylight-savings-ends}.
1547 These values should be Lisp expressions that refer to the variable
1548 @code{year}, and evaluate to the Gregorian date on which daylight
1549 savings time starts or (respectively) ends, in the form of a list
1550 @code{(@var{month} @var{day} @var{year})}. The values should be
1551 @code{nil} if your area does not use daylight savings time.
1553 Emacs uses these expressions to determine the starting date of
1554 daylight savings time for the holiday list and for correcting times of
1555 day in the solar and lunar calculations.
1557 The values for Cambridge, Massachusetts are as follows:
1560 (calendar-nth-named-day 1 0 4 year)
1561 (calendar-nth-named-day -1 0 10 year)
1565 That is, the first 0th day (Sunday) of the fourth month (April) in
1566 the year specified by @code{year}, and the last Sunday of the tenth month
1567 (October) of that year. If daylight savings time were
1568 changed to start on October 1, you would set
1569 @code{calendar-daylight-savings-starts} to this:
1575 If there is no daylight savings time at your location, or if you want
1576 all times in standard time, set @code{calendar-daylight-savings-starts}
1577 and @code{calendar-daylight-savings-ends} to @code{nil}.
1579 @vindex calendar-daylight-time-offset
1580 The variable @code{calendar-daylight-time-offset} specifies the
1581 difference between daylight savings time and standard time, measured in
1582 minutes. The value for Cambridge, Massachusetts is 60.
1584 @c @vindex calendar-daylight-savings-starts-time too long!
1585 @vindex calendar-daylight-savings-ends-time
1586 The two variables @code{calendar-daylight-savings-starts-time} and
1587 @code{calendar-daylight-savings-ends-time} specify the number of minutes
1588 after midnight local time when the transition to and from daylight
1589 savings time should occur. For Cambridge, Massachusetts both variables'
1592 @node Time Intervals
1593 @section Summing Time Intervals
1594 @cindex time intervals, summing
1595 @cindex summing time intervals
1598 The timeclock feature adds up time intervals, so you can (for
1599 instance) keep track of how much time you spend working on particular
1602 @findex timeclock-in
1603 @findex timeclock-out
1604 @findex timeclock-change
1605 @findex timeclock-workday-remaining
1606 @findex timeclock-when-to-leave
1607 Use the @kbd{M-x timeclock-in} command when you start working on a
1608 project, and @kbd{M-x timeclock-out} command when you're done. Each
1609 time you do this, it adds one time interval to the record of the
1610 project. You can change to working on a different project with @kbd{M-x
1613 Once you've collected data from a number of time intervals, you can use
1614 @kbd{M-x timeclock-workday-remaining} to see how much time is left to
1615 work today (assuming a typical average of 8 hours a day), and @kbd{M-x
1616 timeclock-when-to-leave} which will calculate when you're ``done.''
1618 @vindex timeclock-modeline-display
1619 @findex timeclock-modeline-display
1620 If you want Emacs to display the amount of time ``left'' of your
1621 workday in the mode line, either customize the
1622 @code{timeclock-modeline-display} variable and set its value to
1623 @code{t}, or invoke the @kbd{M-x timeclock-modeline-display} command.
1625 @vindex timeclock-ask-before-exiting
1626 Terminating the current Emacs session might or might not mean that
1627 you have stopped working on the project and, by default, Emacs asks
1628 you. You can, however, set the value of the variable
1629 @code{timeclock-ask-before-exiting} to @code{nil} (via @kbd{M-x
1630 customize}) to avoid the question; then, only an explicit @kbd{M-x
1631 timeclock-out} or @kbd{M-x timeclock-change} will tell Emacs that the
1632 current interval is over.
1634 @cindex @file{.timelog} file
1635 @vindex timeclock-file
1636 @findex timeclock-reread-log
1637 The timeclock functions work by accumulating the data in a file
1638 called @file{.timelog} in your home directory. You can specify a
1639 different name for this file by customizing the variable
1640 @code{timeclock-file}. If you edit the timeclock file manually, or if
1641 you change the value of any of timeclock's customizable variables, you
1642 should run the command @kbd{M-x timeclock-reread-log} to update the
1643 data in Emacs from the file.
1646 @include cal-xtra.texi
1650 arch-tag: 4531ef09-9df3-449d-9c52-2b5a4a337f92