1 @c This is part of the Emacs manual.
2 @c Copyright (C) 1985-1987, 1993-1995, 1997, 2000-2011
3 @c Free Software Foundation, Inc.
4 @c See file emacs.texi for copying conditions.
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-3} in the calendar brings up a menu of operations on a
23 particular date; @kbd{Mouse-2} 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 @inforef{Advanced Calendar/Diary Usage,, emacs-xtra}, for information
30 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 * Writing Calendar Files:: Writing calendars to files of various formats.
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 Saving:: How to specify when daylight saving 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-iso-goto-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-iso-goto-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-iso-goto-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{calendar-scroll-left}).
246 Scroll calendar one month backward (@code{calendar-scroll-right}).
249 Scroll calendar three months forward
250 (@code{calendar-scroll-left-three-months}).
253 Scroll calendar three months backward
254 (@code{calendar-scroll-right-three-months}).
257 @kindex > @r{(Calendar mode)}
258 @findex calendar-scroll-left
259 @kindex < @r{(Calendar mode)}
260 @findex calendar-scroll-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 the
264 calendar contents one month forward in time. @kbd{<} scrolls the
265 contents one month backwards in time.
267 @kindex C-v @r{(Calendar mode)}
268 @findex calendar-scroll-left-three-months
269 @kindex M-v @r{(Calendar mode)}
270 @findex calendar-scroll-right-three-months
271 The commands @kbd{C-v} and @kbd{M-v} scroll the calendar by an entire
272 ``screenful''---three months---in analogy with the usual meaning of
273 these commands. @kbd{C-v} makes later dates visible and @kbd{M-v} makes
274 earlier dates visible. These commands take a numeric argument as a
275 repeat count; in particular, since @kbd{C-u} multiplies the next command
276 by four, typing @kbd{C-u C-v} scrolls the calendar forward by a year and
277 typing @kbd{C-u M-v} scrolls the calendar backward by a year.
279 The function keys @key{next} and @key{prior} are equivalent to
280 @kbd{C-v} and @kbd{M-v}, just as they are in other modes.
283 @section Counting Days
287 Display the number of days in the current region
288 (@code{calendar-count-days-region}).
291 @kindex M-= @r{(Calendar mode)}
292 @findex calendar-count-days-region
293 To determine the number of days in the region, type @kbd{M-=}
294 (@code{calendar-count-days-region}). The numbers of days shown is
295 @emph{inclusive}; that is, it includes the days specified by mark and
298 @node General Calendar
299 @section Miscellaneous Calendar Commands
303 Display day-in-year (@code{calendar-print-day-of-year}).
305 Regenerate the calendar window (@code{calendar-redraw}).
307 Scroll the next window up (@code{scroll-other-window}).
309 Scroll the next window down (@code{scroll-other-window-down}).
311 Exit from calendar (@code{calendar-exit}).
314 @kindex p d @r{(Calendar mode)}
316 @findex calendar-print-day-of-year
317 To display the number of days elapsed since the start of the year, or
318 the number of days remaining in the year, type the @kbd{p d} command
319 (@code{calendar-print-day-of-year}). This displays both of those
320 numbers in the echo area. The count of days elapsed includes the
321 selected date. The count of days remaining does not include that
324 @kindex C-c C-l @r{(Calendar mode)}
325 @findex calendar-redraw
326 If the calendar window text gets corrupted, type @kbd{C-c C-l}
327 (@code{calendar-redraw}) to redraw it. (This can only happen if you use
328 non-Calendar-mode editing commands.)
330 @kindex SPC @r{(Calendar mode)}
331 In Calendar mode, you can use @kbd{SPC} (@code{scroll-other-window})
332 and @kbd{DEL} (@code{scroll-other-window-down}) to scroll the other
333 window (if there is one) up or down, respectively. This is handy when
334 you display a list of holidays or diary entries in another window.
336 @kindex q @r{(Calendar mode)}
337 @findex exit-calendar
338 @vindex calendar-remove-frame-by-deleting
339 To exit from the calendar, type @kbd{q} (@code{calendar-exit}). 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 deletes or iconifies that frame depending on the value of
343 @code{calendar-remove-frame-by-deleting}.)
345 @node Writing Calendar Files
346 @section Writing Calendar Files
348 You can write calendars and diary entries to HTML and La@TeX{} files.
350 @cindex calendar and HTML
351 The Calendar HTML commands produce files of HTML code that contain
352 calendar and diary entries. Each file applies to one month, and has a
353 name of the format @file{@var{yyyy}-@var{mm}.html}, where @var{yyyy} and
354 @var{mm} are the four-digit year and two-digit month, respectively. The
355 variable @code{cal-html-directory} specifies the default output
356 directory for the HTML files.
358 @vindex cal-html-css-default
359 Diary entries enclosed by @code{<} and @code{>} are interpreted as
360 HTML tags (for example: this is a diary entry with <font
361 color=''red''>some red text</font>). You can change the overall
362 appearance of the displayed HTML pages (for example, the color of
363 various page elements, header styles) via a stylesheet @file{cal.css} in
364 the directory containing the HTML files (see the value of the variable
365 @code{cal-html-css-default} for relevant style settings).
367 @kindex t @r{(Calendar mode)}
370 Generate a one-month calendar (@code{cal-html-cursor-month}).
372 Generate a calendar file for each month of a year, as well as an index
373 page (@code{cal-html-cursor-year}). By default, this command writes
374 files to a @var{yyyy} subdirectory - if this is altered some hyperlinks
375 between years will not work.
378 If the variable @code{cal-html-print-day-number-flag} is
379 non-@code{nil}, then the monthly calendars show the day-of-the-year
380 number. The variable @code{cal-html-year-index-cols} specifies the
381 number of columns in the yearly index page.
383 @cindex calendar and La@TeX{}
384 The Calendar La@TeX{} commands produce a buffer of La@TeX{} code that
385 prints as a calendar. Depending on the command you use, the printed
386 calendar covers the day, week, month or year that point is in.
388 @kindex t @r{(Calendar mode)}
391 Generate a one-month calendar (@code{cal-tex-cursor-month}).
393 Generate a sideways-printing one-month calendar
394 (@code{cal-tex-cursor-month-landscape}).
396 Generate a one-day calendar
397 (@code{cal-tex-cursor-day}).
399 Generate a one-page calendar for one week
400 (@code{cal-tex-cursor-week}).
402 Generate a two-page calendar for one week
403 (@code{cal-tex-cursor-week2}).
405 Generate an ISO-style calendar for one week
406 (@code{cal-tex-cursor-week-iso}).
408 Generate a calendar for one Monday-starting week
409 (@code{cal-tex-cursor-week-monday}).
411 Generate a Filofax-style two-weeks-at-a-glance calendar
412 (@code{cal-tex-cursor-filofax-2week}).
414 Generate a Filofax-style one-week-at-a-glance calendar
415 (@code{cal-tex-cursor-filofax-week}).
417 Generate a calendar for one year
418 (@code{cal-tex-cursor-year}).
420 Generate a sideways-printing calendar for one year
421 (@code{cal-tex-cursor-year-landscape}).
423 Generate a Filofax-style calendar for one year
424 (@code{cal-tex-cursor-filofax-year}).
427 Some of these commands print the calendar sideways (in ``landscape
428 mode''), so it can be wider than it is long. Some of them use Filofax
429 paper size (3.75in x 6.75in). All of these commands accept a prefix
430 argument which specifies how many days, weeks, months or years to print
431 (starting always with the selected one).
433 If the variable @code{cal-tex-holidays} is non-@code{nil} (the default),
434 then the printed calendars show the holidays in @code{calendar-holidays}.
435 If the variable @code{cal-tex-diary} is non-@code{nil} (the default is
436 @code{nil}), diary entries are included also (in monthly, filofax, and
437 iso-week calendars only). If the variable @code{cal-tex-rules} is
438 non-@code{nil} (the default is @code{nil}), the calendar displays ruled
439 pages in styles that have sufficient room. Consult the documentation of
440 the individual cal-tex functions to see which calendars support which
443 You can use the variable @code{cal-tex-preamble-extra} to insert extra
444 La@TeX{} commands in the preamble of the generated document if you need
451 The Emacs calendar knows about many major and minor holidays,
452 and can display them. You can add your own holidays to the default list.
456 Display holidays for the selected date
457 (@code{calendar-cursor-holidays}).
458 @item Mouse-3 Holidays
459 Display any holidays for the date you click on.
461 Mark holidays in the calendar window (@code{calendar-mark-holidays}).
463 Unmark calendar window (@code{calendar-unmark}).
465 List all holidays for the displayed three months in another window
466 (@code{calendar-list-holidays}).
468 List all holidays for three months around today's date in another
470 @item M-x list-holidays
471 List holidays in another window for a specified range of years.
474 @kindex h @r{(Calendar mode)}
475 @findex calendar-cursor-holidays
476 @vindex calendar-view-holidays-initially-flag
477 To see if any holidays fall on a given date, position point on that
478 date in the calendar window and use the @kbd{h} command. Alternatively,
479 click on that date with @kbd{Mouse-3} and then choose @kbd{Holidays}
480 from the menu that appears. Either way, this displays the holidays for
481 that date, in the echo area if they fit there, otherwise in a separate
484 @kindex x @r{(Calendar mode)}
485 @findex calendar-mark-holidays
486 @kindex u @r{(Calendar mode)}
487 @findex calendar-unmark
488 @vindex calendar-mark-holidays-flag
489 To view the distribution of holidays for all the dates shown in the
490 calendar, use the @kbd{x} command. This displays the dates that are
491 holidays in a different face.
493 @inforef{Calendar Customizing, calendar-holiday-marker, emacs-xtra}.
496 @xref{Calendar Customizing, calendar-holiday-marker}.
498 The command applies both to the currently visible months and to
499 other months that subsequently become visible by scrolling. To turn
500 marking off and erase the current marks, type @kbd{u}, which also
501 erases any diary marks (@pxref{Diary}). If the variable
502 @code{calendar-mark-holidays-flag} is non-@code{nil}, creating or
503 updating the calendar marks holidays automatically.
505 @kindex a @r{(Calendar mode)}
506 @findex calendar-list-holidays
507 To get even more detailed information, use the @kbd{a} command, which
508 displays a separate buffer containing a list of all holidays in the
509 current three-month range. You can use @key{SPC} and @key{DEL} in the
510 calendar window to scroll that list up and down, respectively.
513 The command @kbd{M-x holidays} displays the list of holidays for the
514 current month and the preceding and succeeding months; this works even
515 if you don't have a calendar window. If the variable
516 @code{calendar-view-holidays-initially-flag} is non-@code{nil}, creating
517 the calendar displays holidays in this way. If you want the list of
518 holidays centered around a different month, use @kbd{C-u M-x
519 holidays}, which prompts for the month and year.
521 The holidays known to Emacs include United States holidays and the
522 major Baha'i, Chinese, Christian, Islamic, and Jewish holidays; also the
523 solstices and equinoxes.
525 @findex list-holidays
526 The command @kbd{M-x holiday-list} displays the list of holidays for
527 a range of years. This function asks you for the starting and stopping
528 years, and allows you to choose all the holidays or one of several
529 categories of holidays. You can use this command even if you don't have
532 The dates used by Emacs for holidays are based on @emph{current
533 practice}, not historical fact. For example Veteran's Day began in
534 1919, but is shown in earlier years.
537 @section Times of Sunrise and Sunset
538 @cindex sunrise and sunset
540 Special calendar commands can tell you, to within a minute or two, the
541 times of sunrise and sunset for any date.
545 Display times of sunrise and sunset for the selected date
546 (@code{calendar-sunrise-sunset}).
547 @item Mouse-3 Sunrise/sunset
548 Display times of sunrise and sunset for the date you click on.
549 @item M-x sunrise-sunset
550 Display times of sunrise and sunset for today's date.
551 @item C-u M-x sunrise-sunset
552 Display times of sunrise and sunset for a specified date.
553 @item M-x calendar-sunrise-sunset-month
554 Display times of sunrise and sunset for the selected month.
557 @kindex S @r{(Calendar mode)}
558 @findex calendar-sunrise-sunset
559 @findex sunrise-sunset
560 Within the calendar, to display the @emph{local times} of sunrise and
561 sunset in the echo area, move point to the date you want, and type
562 @kbd{S}. Alternatively, click @kbd{Mouse-3} on the date, then choose
563 @samp{Sunrise/sunset} from the menu that appears. The command @kbd{M-x
564 sunrise-sunset} is available outside the calendar to display this
565 information for today's date or a specified date. To specify a date
566 other than today, use @kbd{C-u M-x sunrise-sunset}, which prompts for
567 the year, month, and day.
569 You can display the times of sunrise and sunset for any location and
570 any date with @kbd{C-u C-u M-x sunrise-sunset}. This asks you for a
571 longitude, latitude, number of minutes difference from Coordinated
572 Universal Time, and date, and then tells you the times of sunrise and
573 sunset for that location on that date.
575 Because the times of sunrise and sunset depend on the location on
576 earth, you need to tell Emacs your latitude, longitude, and location
577 name before using these commands. Here is an example of what to set:
579 @vindex calendar-location-name
580 @vindex calendar-longitude
581 @vindex calendar-latitude
583 (setq calendar-latitude 40.1)
584 (setq calendar-longitude -88.2)
585 (setq calendar-location-name "Urbana, IL")
589 Use one decimal place in the values of @code{calendar-latitude} and
590 @code{calendar-longitude}.
592 Your time zone also affects the local time of sunrise and sunset.
593 Emacs usually gets time zone information from the operating system, but
594 if these values are not what you want (or if the operating system does
595 not supply them), you must set them yourself. Here is an example:
597 @vindex calendar-time-zone
598 @vindex calendar-standard-time-zone-name
599 @vindex calendar-daylight-time-zone-name
601 (setq calendar-time-zone -360)
602 (setq calendar-standard-time-zone-name "CST")
603 (setq calendar-daylight-time-zone-name "CDT")
607 The value of @code{calendar-time-zone} is the number of minutes
608 difference between your local standard time and Coordinated Universal
609 Time (Greenwich time). The values of
610 @code{calendar-standard-time-zone-name} and
611 @code{calendar-daylight-time-zone-name} are the abbreviations used in
612 your time zone. Emacs displays the times of sunrise and sunset
613 @emph{corrected for daylight saving time}. @xref{Daylight Saving},
614 for how daylight saving time is determined.
616 As a user, you might find it convenient to set the calendar location
617 variables for your usual physical location in your @file{.emacs} file.
618 And when you install Emacs on a machine, you can create a
619 @file{default.el} file which sets them properly for the typical location
620 of most users of that machine. @xref{Init File}.
623 @section Phases of the Moon
624 @cindex phases of the moon
625 @cindex moon, phases of
627 These calendar commands display the dates and times of the phases of
628 the moon (new moon, first quarter, full moon, last quarter). This
629 feature is useful for debugging problems that ``depend on the phase of
634 Display the dates and times for all the quarters of the moon for the
635 three-month period shown (@code{calendar-lunar-phases}).
636 @item M-x lunar-phases
637 Display dates and times of the quarters of the moon for three months around
641 @kindex M @r{(Calendar mode)}
642 @findex calendar-lunar-phases
643 Within the calendar, use the @kbd{M} command to display a separate
644 buffer of the phases of the moon for the current three-month range. The
645 dates and times listed are accurate to within a few minutes.
648 Outside the calendar, use the command @kbd{M-x lunar-phases} to
649 display the list of the phases of the moon for the current month and the
650 preceding and succeeding months. For information about a different
651 month, use @kbd{C-u M-x lunar-phases}, which prompts for the month and
654 The dates and times given for the phases of the moon are given in
655 local time (corrected for daylight saving, when appropriate).
656 See the discussion in the previous section. @xref{Sunrise/Sunset}.
658 @node Other Calendars
659 @section Conversion To and From Other Calendars
661 @cindex Gregorian calendar
662 The Emacs calendar displayed is @emph{always} the Gregorian calendar,
663 sometimes called the ``new style'' calendar, which is used in most of
664 the world today. However, this calendar did not exist before the
665 sixteenth century and was not widely used before the eighteenth century;
666 it did not fully displace the Julian calendar and gain universal
667 acceptance until the early twentieth century. The Emacs calendar can
668 display any month since January, year 1 of the current era, but the
669 calendar displayed is the Gregorian, even for a date at which the
670 Gregorian calendar did not exist.
672 While Emacs cannot display other calendars, it can convert dates to
673 and from several other calendars.
676 * Calendar Systems:: The calendars Emacs understands
677 (aside from Gregorian).
678 * To Other Calendar:: Converting the selected date to various calendars.
679 * From Other Calendar:: Moving to a date specified in another calendar.
680 * Mayan Calendar:: Moving to a date specified in a Mayan calendar.
683 @node Calendar Systems
684 @subsection Supported Calendar Systems
686 @cindex ISO commercial calendar
687 The ISO commercial calendar is used largely in Europe.
689 @cindex Julian calendar
690 The Julian calendar, named after Julius Caesar, was the one used in Europe
691 throughout medieval times, and in many countries up until the nineteenth
694 @cindex Julian day numbers
695 @cindex astronomical day numbers
696 Astronomers use a simple counting of days elapsed since noon, Monday,
697 January 1, 4713 B.C. on the Julian calendar. The number of days elapsed
698 is called the @dfn{Julian day number} or the @dfn{Astronomical day number}.
700 @cindex Hebrew calendar
701 The Hebrew calendar is used by tradition in the Jewish religion. The
702 Emacs calendar program uses the Hebrew calendar to determine the dates
703 of Jewish holidays. Hebrew calendar dates begin and end at sunset.
705 @cindex Islamic calendar
706 The Islamic calendar is used in many predominantly Islamic countries.
707 Emacs uses it to determine the dates of Islamic holidays. There is no
708 universal agreement in the Islamic world about the calendar; Emacs uses
709 a widely accepted version, but the precise dates of Islamic holidays
710 often depend on proclamation by religious authorities, not on
711 calculations. As a consequence, the actual dates of observance can vary
712 slightly from the dates computed by Emacs. Islamic calendar dates begin
715 @cindex French Revolutionary calendar
716 The French Revolutionary calendar was created by the Jacobins after the 1789
717 revolution, to represent a more secular and nature-based view of the annual
718 cycle, and to install a 10-day week in a rationalization measure similar to
719 the metric system. The French government officially abandoned this
720 calendar at the end of 1805.
722 @cindex Mayan calendar
723 The Maya of Central America used three separate, overlapping calendar
724 systems, the @emph{long count}, the @emph{tzolkin}, and the @emph{haab}.
725 Emacs knows about all three of these calendars. Experts dispute the
726 exact correlation between the Mayan calendar and our calendar; Emacs uses the
727 Goodman-Martinez-Thompson correlation in its calculations.
729 @cindex Coptic calendar
730 @cindex Ethiopic calendar
731 The Copts use a calendar based on the ancient Egyptian solar calendar.
732 Their calendar consists of twelve 30-day months followed by an extra
733 five-day period. Once every fourth year they add a leap day to this
734 extra period to make it six days. The Ethiopic calendar is identical in
735 structure, but has different year numbers and month names.
737 @cindex Persian calendar
738 The Persians use a solar calendar based on a design of Omar Khayyam.
739 Their calendar consists of twelve months of which the first six have 31
740 days, the next five have 30 days, and the last has 29 in ordinary years
741 and 30 in leap years. Leap years occur in a complicated pattern every
743 The calendar implemented here is the arithmetical Persian calendar
744 championed by Birashk, based on a 2,820-year cycle. It differs from
745 the astronomical Persian calendar, which is based on astronomical
746 events. As of this writing the first future discrepancy is projected
747 to occur on March 20, 2025. It is currently not clear what the
748 official calendar of Iran will be that far into the future.
750 @cindex Chinese calendar
751 The Chinese calendar is a complicated system of lunar months arranged
752 into solar years. The years go in cycles of sixty, each year containing
753 either twelve months in an ordinary year or thirteen months in a leap
754 year; each month has either 29 or 30 days. Years, ordinary months, and
755 days are named by combining one of ten ``celestial stems'' with one of
756 twelve ``terrestrial branches'' for a total of sixty names that are
757 repeated in a cycle of sixty.
759 @cindex Baha'i calendar
760 The Baha'i calendar system is based on a solar cycle of 19 months with
761 19 days each. The four remaining ``intercalary'' days are placed
762 between the 18th and 19th months.
764 @node To Other Calendar
765 @subsection Converting To Other Calendars
767 The following commands describe the selected date (the date at point)
768 in various other calendar systems:
771 @item Mouse-3 Other calendars
772 Display the date that you click on, expressed in various other calendars.
773 @kindex p @r{(Calendar mode)}
774 @findex calendar-print-other-dates
776 Display the selected date in various other calendars.
777 (@code{calendar-print-other-dates}).
778 @findex calendar-iso-print-date
780 Display ISO commercial calendar equivalent for selected day
781 (@code{calendar-iso-print-date}).
782 @findex calendar-julian-print-date
784 Display Julian date for selected day (@code{calendar-julian-print-date}).
785 @findex calendar-astro-print-day-number
787 Display astronomical (Julian) day number for selected day
788 (@code{calendar-astro-print-day-number}).
789 @findex calendar-hebrew-print-date
791 Display Hebrew date for selected day (@code{calendar-hebrew-print-date}).
792 @findex calendar-islamic-print-date
794 Display Islamic date for selected day (@code{calendar-islamic-print-date}).
795 @findex calendar-french-print-date
797 Display French Revolutionary date for selected day
798 (@code{calendar-french-print-date}).
799 @findex calendar-bahai-print-date
801 Display Baha'i date for selected day
802 (@code{calendar-bahai-print-date}).
803 @findex calendar-chinese-print-date
805 Display Chinese date for selected day
806 (@code{calendar-chinese-print-date}).
807 @findex calendar-coptic-print-date
809 Display Coptic date for selected day
810 (@code{calendar-coptic-print-date}).
811 @findex calendar-ethiopic-print-date
813 Display Ethiopic date for selected day
814 (@code{calendar-ethiopic-print-date}).
815 @findex calendar-persian-print-date
817 Display Persian date for selected day
818 (@code{calendar-persian-print-date}).
819 @findex calendar-mayan-print-date
821 Display Mayan date for selected day (@code{calendar-mayan-print-date}).
824 If you are using a graphic display, the easiest way to translate a
825 date into other calendars is to click on it with @kbd{Mouse-3}, then
826 choose @kbd{Other calendars} from the menu that appears. This displays
827 the equivalent forms of the date in all the calendars Emacs understands,
828 in the form of a menu. (Choosing an alternative from this menu doesn't
829 actually do anything---the menu is used only for display.)
831 Otherwise, move point to the date you want to convert, then type the
832 appropriate command starting with @kbd{p} from the table above. The
833 prefix @kbd{p} is a mnemonic for ``print,'' since Emacs ``prints'' the
834 equivalent date in the echo area. @kbd{p o} displays the
835 date in all forms known to Emacs.
837 @node From Other Calendar
838 @subsection Converting From Other Calendars
840 You can use the other supported calendars to specify a date to move
841 to. This section describes the commands for doing this using calendars
842 other than Mayan; for the Mayan calendar, see the following section.
844 @kindex g @var{char} @r{(Calendar mode)}
845 @findex calendar-iso-goto-date
846 @findex calendar-iso-goto-week
847 @findex calendar-julian-goto-date
848 @findex calendar-astro-goto-day-number
849 @findex calendar-bahai-goto-date
850 @findex calendar-hebrew-goto-date
851 @findex calendar-islamic-goto-date
852 @findex calendar-french-goto-date
853 @findex calendar-chinese-goto-date
854 @findex calendar-persian-goto-date
855 @findex calendar-coptic-goto-date
856 @findex calendar-ethiopic-goto-date
859 Move to a date specified in the ISO commercial calendar
860 (@code{calendar-iso-goto-date}).
862 Move to a week specified in the ISO commercial calendar
863 (@code{calendar-iso-goto-week}).
865 Move to a date specified in the Julian calendar
866 (@code{calendar-julian-goto-date}).
868 Move to a date specified with an astronomical (Julian) day number
869 (@code{calendar-astro-goto-day-number}).
871 Move to a date specified in the Baha'i calendar
872 (@code{calendar-bahai-goto-date}).
874 Move to a date specified in the Hebrew calendar
875 (@code{calendar-hebrew-goto-date}).
877 Move to a date specified in the Islamic calendar
878 (@code{calendar-islamic-goto-date}).
880 Move to a date specified in the French Revolutionary calendar
881 (@code{calendar-french-goto-date}).
883 Move to a date specified in the Chinese calendar
884 (@code{calendar-chinese-goto-date}).
886 Move to a date specified in the Persian calendar
887 (@code{calendar-persian-goto-date}).
889 Move to a date specified in the Coptic calendar
890 (@code{calendar-coptic-goto-date}).
892 Move to a date specified in the Ethiopic calendar
893 (@code{calendar-ethiopic-goto-date}).
896 These commands ask you for a date on the other calendar, move point
897 to the Gregorian calendar date equivalent to that date, and display
898 the other calendar's date in the echo area. Emacs uses strict
899 completion (@pxref{Completion Exit}) whenever it asks you to type a
900 month name, so you don't have to worry about the spelling of Hebrew,
901 Islamic, or French names.
904 @findex calendar-hebrew-list-yahrzeits
906 One common question concerning the Hebrew calendar is the computation
907 of the anniversary of a date of death, called a ``yahrzeit.'' The Emacs
908 calendar includes a facility for such calculations. If you are in the
909 calendar, the command @kbd{M-x calendar-hebrew-list-yahrzeits} asks you for
910 a range of years and then displays a list of the yahrzeit dates for those
911 years for the date given by point. If you are not in the calendar,
912 this command first asks you for the date of death and the range of
913 years, and then displays the list of yahrzeit dates.
916 @subsection Converting from the Mayan Calendar
918 Here are the commands to select dates based on the Mayan calendar:
922 Move to a date specified by the long count calendar
923 (@code{calendar-mayan-goto-long-count-date}).
925 Move to the next occurrence of a place in the
926 tzolkin calendar (@code{calendar-mayan-next-tzolkin-date}).
928 Move to the previous occurrence of a place in the
929 tzolkin calendar (@code{calendar-mayan-previous-tzolkin-date}).
931 Move to the next occurrence of a place in the
932 haab calendar (@code{calendar-mayan-next-haab-date}).
934 Move to the previous occurrence of a place in the
935 haab calendar (@code{calendar-mayan-previous-haab-date}).
937 Move to the next occurrence of a place in the
938 calendar round (@code{calendar-mayan-next-calendar-round-date}).
940 Move to the previous occurrence of a place in the
941 calendar round (@code{calendar-mayan-previous-calendar-round-date}).
944 @cindex Mayan long count
945 To understand these commands, you need to understand the Mayan calendars.
946 The @dfn{long count} is a counting of days with these units:
949 1 kin = 1 day@ @ @ 1 uinal = 20 kin@ @ @ 1 tun = 18 uinal
950 1 katun = 20 tun@ @ @ 1 baktun = 20 katun
953 @kindex g m @r{(Calendar mode)}
954 @findex calendar-mayan-goto-long-count-date
956 Thus, the long count date 12.16.11.16.6 means 12 baktun, 16 katun, 11
957 tun, 16 uinal, and 6 kin. The Emacs calendar can handle Mayan long
958 count dates as early as 7.17.18.13.3, but no earlier. When you use the
959 @kbd{g m l} command, type the Mayan long count date with the baktun,
960 katun, tun, uinal, and kin separated by periods.
962 @findex calendar-mayan-previous-tzolkin-date
963 @findex calendar-mayan-next-tzolkin-date
964 @cindex Mayan tzolkin calendar
965 The Mayan tzolkin calendar is a cycle of 260 days formed by a pair of
966 independent cycles of 13 and 20 days. Since this cycle repeats
967 endlessly, Emacs provides commands to move backward and forward to the
968 previous or next point in the cycle. Type @kbd{g m p t} to go to the
969 previous tzolkin date; Emacs asks you for a tzolkin date and moves point
970 to the previous occurrence of that date. Similarly, type @kbd{g m n t}
971 to go to the next occurrence of a tzolkin date.
973 @findex calendar-mayan-previous-haab-date
974 @findex calendar-mayan-next-haab-date
975 @cindex Mayan haab calendar
976 The Mayan haab calendar is a cycle of 365 days arranged as 18 months
977 of 20 days each, followed a 5-day monthless period. Like the tzolkin
978 cycle, this cycle repeats endlessly, and there are commands to move
979 backward and forward to the previous or next point in the cycle. Type
980 @kbd{g m p h} to go to the previous haab date; Emacs asks you for a haab
981 date and moves point to the previous occurrence of that date.
982 Similarly, type @kbd{g m n h} to go to the next occurrence of a haab
985 @c This is omitted because it is too long for smallbook format.
986 @c @findex calendar-mayan-previous-calendar-round-date
987 @findex calendar-mayan-next-calendar-round-date
988 @cindex Mayan calendar round
989 The Maya also used the combination of the tzolkin date and the haab
990 date. This combination is a cycle of about 52 years called a
991 @emph{calendar round}. If you type @kbd{g m p c}, Emacs asks you for
992 both a haab and a tzolkin date and then moves point to the previous
993 occurrence of that combination. Use @kbd{g m n c} to move point to the
994 next occurrence of a combination. These commands signal an error if the
995 haab/tzolkin date combination you have typed is impossible.
997 Emacs uses strict completion (@pxref{Completion Exit}) whenever it
998 asks you to type a Mayan name, so you don't have to worry about
1005 The Emacs diary keeps track of appointments or other events on a daily
1006 basis, in conjunction with the calendar. To use the diary feature, you
1007 must first create a @dfn{diary file} containing a list of events and
1008 their dates. Then Emacs can automatically pick out and display the
1009 events for today, for the immediate future, or for any specified
1012 The name of the diary file is specified by the variable
1013 @code{diary-file}; @file{~/diary} is the default. Here's an example
1014 showing what that file looks like:
1017 12/22/1988 Twentieth wedding anniversary!!
1018 &1/1. Happy New Year!
1019 10/22 Ruth's birthday.
1021 Tuesday--weekly meeting with grad students at 10am
1022 Supowit, Shen, Bitner, and Kapoor to attend.
1023 1/13/89 Friday the thirteenth!!
1024 &thu 4pm squash game with Lloyd.
1025 mar 16 Dad's birthday
1026 April 15, 1989 Income tax due.
1027 &* 15 time cards due.
1031 This format is essentially the same as the one used by the system's
1032 @command{calendar} utility. This example uses extra spaces to align
1033 the event descriptions of most of the entries. Such formatting is
1034 purely a matter of taste.
1036 Although you probably will start by creating a diary manually, Emacs
1037 provides a number of commands to let you view, add, and change diary
1041 * Displaying the Diary:: Viewing diary entries and associated calendar dates.
1042 * Format of Diary File:: Entering events in your diary.
1043 * Date Formats:: Various ways you can specify dates.
1044 * Adding to Diary:: Commands to create diary entries.
1045 * Special Diary Entries:: Anniversaries, blocks of dates, cyclic entries, etc.
1048 @node Displaying the Diary
1049 @subsection Displaying the Diary
1051 Once you have created a diary file, you can use the calendar to view
1052 it. You can also view today's events outside of Calendar mode. In the
1053 following, key bindings refer to the Calendar buffer.
1057 Display all diary entries for the selected date
1058 (@code{diary-view-entries}).
1060 Display all diary entries for the date you click on.
1062 Display the entire diary file (@code{diary-show-all-entries}).
1064 Mark all visible dates that have diary entries
1065 (@code{diary-mark-entries}).
1067 Unmark the calendar window (@code{calendar-unmark}).
1068 @item M-x diary-print-entries
1069 Print hard copy of the diary display as it appears.
1071 Display all diary entries for today's date.
1072 @item M-x diary-mail-entries
1073 Mail yourself email reminders about upcoming diary entries.
1076 @kindex d @r{(Calendar mode)}
1077 @findex diary-view-entries
1078 @vindex calendar-view-diary-initially-flag
1079 Displaying the diary entries with @kbd{d} shows in a separate window
1080 the diary entries for the selected date in the calendar. The mode line
1081 of the new window shows the date of the diary entries. Holidays are
1082 shown either in the buffer or in the mode line, depending on the display
1085 (@pxref{Diary Display,,, emacs-xtra, Specialized Emacs Features}).
1088 (@pxref{Diary Display}).
1090 If you specify a numeric argument with @kbd{d}, it shows all the diary
1091 entries for that many successive days. Thus, @kbd{2 d} displays all the
1092 entries for the selected date and for the following day.
1094 Another way to display the diary entries for a date is to click
1095 @kbd{Mouse-3} on the date, and then choose @kbd{Diary entries} from
1096 the menu that appears. If the variable
1097 @code{calendar-view-diary-initially-flag} is non-@code{nil}, creating the
1098 calendar lists the diary entries for the current date (provided the
1099 current date is visible).
1101 @kindex m @r{(Calendar mode)}
1102 @findex diary-mark-entries
1103 @vindex calendar-mark-diary-entries-flag
1104 To get a broader view of which days are mentioned in the diary, use
1105 the @kbd{m} command. This marks the dates that have diary entries in
1108 @inforef{Calendar Customizing, diary-entry-marker, emacs-xtra}.
1111 @xref{Calendar Customizing, diary-entry-marker}.
1114 The command applies both to the currently visible months and to
1115 other months that subsequently become visible by scrolling. To turn
1116 marking off and erase the current marks, type @kbd{u}, which also
1117 turns off holiday marks (@pxref{Holidays}). If the variable
1118 @code{calendar-mark-diary-entries-flag} is non-@code{nil}, creating or
1119 updating the calendar marks diary dates automatically.
1121 @kindex s @r{(Calendar mode)}
1122 @findex diary-show-all-entries
1123 To see the full diary file, rather than just some of the entries, use
1124 the @kbd{s} command.
1127 The command @kbd{M-x diary} displays the diary entries for the current
1128 date, independently of the calendar display, and optionally for the next
1129 few days as well; the variable @code{diary-number-of-entries} specifies
1130 how many days to include.
1132 @inforef{Diary Customizing,, emacs-xtra}.
1135 @xref{Diary Customizing, diary-number-of-entries}.
1138 If you put @code{(diary)} in your @file{.emacs} file, this
1139 automatically displays a window with the day's diary entries, when you
1142 @findex diary-mail-entries
1143 @vindex diary-mail-days
1144 Many users like to receive notice of events in their diary as email.
1145 To send such mail to yourself, use the command @kbd{M-x
1146 diary-mail-entries}. A prefix argument specifies how many days
1147 (starting with today) to check; otherwise, the variable
1148 @code{diary-mail-days} says how many days.
1150 @node Format of Diary File
1151 @subsection The Diary File
1155 Your @dfn{diary file} is a file that records events associated with
1156 particular dates. The name of the diary file is specified by the
1157 variable @code{diary-file}; @file{~/diary} is the default. The
1158 @code{calendar} utility program supports a subset of the format allowed
1159 by the Emacs diary facilities, so you can use that utility to view the
1160 diary file, with reasonable results aside from the entries it cannot
1163 Each entry in the diary file describes one event and consists of one
1164 or more lines. An entry always begins with a date specification at the
1165 left margin. The rest of the entry is simply text to describe the
1166 event. If the entry has more than one line, then the lines after the
1167 first must begin with whitespace to indicate they continue a previous
1168 entry. Lines that do not begin with valid dates and do not continue a
1169 preceding entry are ignored.
1171 You can also use a format where the first line of a diary entry
1172 consists only of the date or day name (with no following blanks or
1173 punctuation). For example:
1177 Bill B. visits Princeton today
1178 2pm Cognitive Studies Committee meeting
1179 2:30-5:30 Liz at Lawrenceville
1181 7:30pm Dinner at George's
1182 8:00-10:00pm concert
1186 This entry will have a different appearance if you use the simple diary
1189 (@pxref{Diary Display,,, emacs-xtra, Specialized Emacs Features}).
1192 (@pxref{Diary Display}).
1194 The simple diary display omits the date line at the beginning; only the
1195 continuation lines appear. This style of entry looks neater when you
1196 display just a single day's entries, but can cause confusion if you ask
1197 for more than one day's entries.
1199 @vindex diary-nonmarking-symbol
1200 You can inhibit the marking of certain diary entries in the calendar
1201 window; to do this, insert an ampersand @code{diary-nonmarking-symbol}
1202 (default @samp{&}) at the beginning of the entry, before the date. This
1203 has no effect on display of the entry in the diary window; it affects
1204 only marks on dates in the calendar window. Nonmarking entries are
1205 especially useful for generic entries that would otherwise mark many
1209 @subsection Date Formats
1211 Here are some sample diary entries, illustrating different ways of
1212 formatting a date. The examples all show dates in American order
1213 (month, day, year), but Calendar mode supports European order (day,
1214 month, year) and ISO order (year, month, day) as options.
1217 4/20/93 Switch-over to new tabulation system
1218 apr. 25 Start tabulating annual results
1219 4/30 Results for April are due
1220 */25 Monthly cycle finishes
1221 Friday Don't leave without backing up files
1224 The first entry appears only once, on April 20, 1993. The second and
1225 third appear every year on the specified dates, and the fourth uses a
1226 wildcard (asterisk) for the month, so it appears on the 25th of every
1227 month. The final entry appears every week on Friday.
1229 You can use just numbers to express a date, as in
1230 @samp{@var{month}/@var{day}} or @samp{@var{month}/@var{day}/@var{year}}.
1231 This must be followed by a nondigit. In the date itself, @var{month}
1232 and @var{day} are numbers of one or two digits. The optional @var{year}
1233 is also a number, and may be abbreviated to the last two digits; that
1234 is, you can use @samp{11/12/1989} or @samp{11/12/89}.
1236 Dates can also have the form @samp{@var{monthname} @var{day}} or
1237 @samp{@var{monthname} @var{day}, @var{year}}, where the month's name can
1238 be spelled in full or abbreviated (with or without a period). The
1239 preferred abbreviations for month and day names can be set using
1240 the variables @code{calendar-abbrev-length},
1241 @code{calendar-month-abbrev-array}, and
1242 @code{calendar-day-abbrev-array}. The default is to use the first three
1243 letters of a name as its abbreviation. Case is not significant.
1245 A date may be @dfn{generic}; that is, partially unspecified. Then the
1246 entry applies to all dates that match the specification. If the date
1247 does not contain a year, it is generic and applies to any year.
1248 Alternatively, @var{month}, @var{day}, or @var{year} can be a @samp{*};
1249 this matches any month, day, or year, respectively. Thus, a diary entry
1250 @samp{3/*/*} matches any day in March of any year; so does @samp{march
1253 @vindex calendar-date-style
1254 @findex calendar-set-date-style
1255 If you prefer the European style of writing dates (in which the day
1256 comes before the month), or the ISO style (in which the order is year,
1257 month, day), type @kbd{M-x calendar-set-date-style} while in the
1258 calendar, or customize the variable @code{calendar-date-style}. This
1259 affects how diary dates are interpreted, date display, and the order in
1260 which some commands expect their arguments to be given.
1262 You can use the name of a day of the week as a generic date which
1263 applies to any date falling on that day of the week. You can abbreviate
1264 the day of the week as described above, or spell it in full; case is not
1267 @node Adding to Diary
1268 @subsection Commands to Add to the Diary
1270 While in the calendar, there are several commands to create diary
1271 entries. The basic commands are listed here; more sophisticated
1272 commands are in the next section (@pxref{Special Diary Entries}).
1273 Entries can also be based on non-Gregorian calendars.
1275 @inforef{Non-Gregorian Diary,, emacs-xtra}.
1278 @xref{Non-Gregorian Diary}.
1283 Add a diary entry for the selected date (@code{diary-insert-entry}).
1285 Add a diary entry for the selected day of the week (@code{diary-insert-weekly-entry}).
1287 Add a diary entry for the selected day of the month (@code{diary-insert-monthly-entry}).
1289 Add a diary entry for the selected day of the year (@code{diary-insert-yearly-entry}).
1292 @kindex i d @r{(Calendar mode)}
1293 @findex diary-insert-entry
1294 You can make a diary entry for a specific date by selecting that date
1295 in the calendar window and typing the @kbd{i d} command. This command
1296 displays the end of your diary file in another window and inserts the
1297 date; you can then type the rest of the diary entry.
1299 @kindex i w @r{(Calendar mode)}
1300 @findex diary-insert-weekly-entry
1301 @kindex i m @r{(Calendar mode)}
1302 @findex diary-insert-monthly-entry
1303 @kindex i y @r{(Calendar mode)}
1304 @findex diary-insert-yearly-entry
1305 If you want to make a diary entry that applies to a specific day of
1306 the week, select that day of the week (any occurrence will do) and type
1307 @kbd{i w}. This inserts the day-of-week as a generic date; you can then
1308 type the rest of the diary entry. You can make a monthly diary entry in
1309 the same fashion: select the day of the month, use the @kbd{i m}
1310 command, and type the rest of the entry. Similarly, you can insert a
1311 yearly diary entry with the @kbd{i y} command.
1313 All of the above commands make marking diary entries by default. To
1314 make a nonmarking diary entry, give a numeric argument to the command.
1315 For example, @kbd{C-u i w} makes a nonmarking weekly diary entry.
1317 When you modify the diary file, be sure to save the file before
1318 exiting Emacs. Saving the diary file after using any of the above
1319 insertion commands will automatically update the diary marks in the
1320 calendar window, if appropriate. You can use the command
1321 @code{calendar-redraw} to force an update at any time.
1323 @node Special Diary Entries
1324 @subsection Special Diary Entries
1326 In addition to entries based on calendar dates, the diary file can
1327 contain @dfn{sexp entries} for regular events such as anniversaries.
1328 These entries are based on Lisp expressions (sexps) that Emacs evaluates
1329 as it scans the diary file. Instead of a date, a sexp entry contains
1330 @samp{%%} followed by a Lisp expression which must begin and end with
1331 parentheses. The Lisp expression determines which dates the entry
1334 Calendar mode provides commands to insert certain commonly used
1339 Add an anniversary diary entry for the selected date
1340 (@code{diary-insert-anniversary-entry}).
1342 Add a block diary entry for the current region
1343 (@code{diary-insert-block-entry}).
1345 Add a cyclic diary entry starting at the date
1346 (@code{diary-insert-cyclic-entry}).
1349 @kindex i a @r{(Calendar mode)}
1350 @findex diary-insert-anniversary-entry
1351 If you want to make a diary entry that applies to the anniversary of a
1352 specific date, move point to that date and use the @kbd{i a} command.
1353 This displays the end of your diary file in another window and inserts
1354 the anniversary description; you can then type the rest of the diary
1355 entry. The entry looks like this:
1357 @findex diary-anniversary
1359 %%(diary-anniversary 10 31 1948) Arthur's birthday
1363 This entry applies to October 31 in any year after 1948; @samp{10 31
1364 1948} specifies the date. (If you are using the European or ISO
1365 calendar style, the input order of month, day and year is different.)
1366 The reason this expression requires a beginning year is that advanced
1367 diary functions can use it to calculate the number of elapsed years.
1369 A @dfn{block} diary entry applies to a specified range of consecutive
1370 dates. Here is a block diary entry that applies to all dates from June
1371 24, 1990 through July 10, 1990:
1375 %%(diary-block 6 24 1990 7 10 1990) Vacation
1379 The @samp{6 24 1990} indicates the starting date and the @samp{7 10 1990}
1380 indicates the stopping date. (Again, if you are using the European or ISO
1381 calendar style, the input order of month, day and year is different.)
1383 @kindex i b @r{(Calendar mode)}
1384 @findex diary-insert-block-entry
1385 To insert a block entry, place point and the mark on the two
1386 dates that begin and end the range, and type @kbd{i b}. This command
1387 displays the end of your diary file in another window and inserts the
1388 block description; you can then type the diary entry.
1390 @kindex i c @r{(Calendar mode)}
1391 @findex diary-insert-cyclic-entry
1392 @dfn{Cyclic} diary entries repeat after a fixed interval of days. To
1393 create one, select the starting date and use the @kbd{i c} command. The
1394 command prompts for the length of interval, then inserts the entry,
1395 which looks like this:
1397 @findex diary-cyclic
1399 %%(diary-cyclic 50 3 1 1990) Renew medication
1403 This entry applies to March 1, 1990 and every 50th day following;
1404 @samp{3 1 1990} specifies the starting date. (If you are using the
1405 European or ISO calendar style, the input order of month, day and year
1408 All three of these commands make marking diary entries. To insert a
1409 nonmarking entry, give a numeric argument to the command. For example,
1410 @kbd{C-u i a} makes a nonmarking anniversary diary entry.
1412 Marking sexp diary entries in the calendar is @emph{extremely}
1413 time-consuming, since every date visible in the calendar window must be
1414 individually checked. So it's a good idea to make sexp diary entries
1415 nonmarking (with @samp{&}) when possible.
1417 Another sophisticated kind of sexp entry, a @dfn{floating} diary entry,
1418 specifies a regularly occurring event by offsets specified in days,
1419 weeks, and months. It is comparable to a crontab entry interpreted by
1420 the @code{cron} utility. Here is a nonmarking, floating diary entry
1421 that applies to the fourth Thursday in November:
1425 &%%(diary-float 11 4 4) American Thanksgiving
1429 The 11 specifies November (the eleventh month), the 4 specifies Thursday
1430 (the fourth day of the week, where Sunday is numbered zero), and the
1431 second 4 specifies the fourth Thursday (1 would mean ``first,'' 2 would
1432 mean ``second,'' @minus{}2 would mean ``second-to-last,'' and so on).
1433 The month can be a single month or a list of months. Thus you could change
1434 the 11 above to @samp{'(1 2 3)} and have the entry apply to the last
1435 Thursday of January, February, and March. If the month is @code{t}, the
1436 entry applies to all months of the year.@refill
1438 Each of the standard sexp diary entries takes an optional parameter
1439 specifying the name of a face or a single-character string to use when
1440 marking the entry in the calendar. Most generally, sexp diary entries
1441 can perform arbitrary computations to determine when they apply.
1443 @inforef{Sexp Diary Entries,, emacs-xtra}.
1446 @xref{Sexp Diary Entries}.
1450 @section Appointments
1451 @cindex appointment notification
1453 @vindex appt-display-format
1454 @vindex appt-audible
1455 @vindex appt-display-mode-line
1456 If you have a diary entry for an appointment, and that diary entry
1457 begins with a recognizable time of day, Emacs can warn you several
1458 minutes beforehand that that appointment is pending. Emacs alerts you
1459 to the appointment by displaying a message in your chosen format, as
1460 specified by the variable @code{appt-display-format}. If the value of
1461 @code{appt-audible} is non-@code{nil}, the warning includes an audible
1462 reminder. In addition, if @code{appt-display-mode-line} is
1463 non-@code{nil}, Emacs displays the number of minutes to the
1464 appointment on the mode line.
1466 @vindex appt-display-duration
1467 @vindex appt-disp-window-function
1468 @vindex appt-delete-window-function
1469 If @code{appt-display-format} has the value @code{window}, then the
1470 variable @code{appt-display-duration} controls how long the reminder
1471 window is visible for; and the variables
1472 @code{appt-disp-window-function} and @code{appt-delete-window-function}
1473 give the names of functions used to create and destroy the window,
1476 @findex appt-activate
1477 To enable appointment notification, type @kbd{M-x appt-activate}.
1478 With a positive argument, it enables notification; with a negative
1479 argument, it disables notification; with no argument, it toggles.
1480 Enabling notification also sets up an appointment list for today from
1481 the diary file, giving all diary entries found with recognizable times
1482 of day, and reminds you just before each of them.
1484 For example, suppose the diary file contains these lines:
1492 @vindex appt-message-warning-time
1493 @vindex appt-warning-time-regexp
1495 Then on Mondays, you will be reminded at around 9:20am about your
1496 coffee break and at around 11:50am about lunch. The variable
1497 @code{appt-message-warning-time} specifies how many minutes (default 12)
1498 in advance to warn you. This is a default warning time. Each
1499 appointment can specify a different warning time by adding a piece
1500 matching @code{appt-warning-time-regexp} (see that variable's
1501 documentation for details).
1503 You can write times in am/pm style (with @samp{12:00am} standing
1504 for midnight and @samp{12:00pm} standing for noon), or 24-hour
1505 European/military style. You need not be consistent; your diary file
1506 can have a mixture of the two styles. Times must be at the beginning of
1507 diary entries if they are to be recognized.
1509 @vindex appt-display-diary
1510 Emacs updates the appointments list from the diary file
1511 automatically just after midnight. You can force an update at any
1512 time by re-enabling appointment notification. Both these actions also
1513 display the day's diary buffer, unless you set
1514 @code{appt-display-diary} to @code{nil}. The appointments list is
1515 also updated whenever the diary file (or a file it includes; see
1517 @inforef{Fancy Diary Display,, emacs-xtra})
1520 @ref{Fancy Diary Display})
1527 You can also use the appointment notification facility like an alarm
1528 clock. The command @kbd{M-x appt-add} adds entries to the appointment
1529 list without affecting your diary file. You delete entries from the
1530 appointment list with @kbd{M-x appt-delete}.
1532 @node Importing Diary
1533 @section Importing and Exporting Diary Entries
1535 You can transfer diary entries between Emacs diary files and a
1536 variety of other formats.
1538 @vindex diary-outlook-formats
1539 You can import diary entries from Outlook-generated appointment
1540 messages. While viewing such a message in Rmail or Gnus, do @kbd{M-x
1541 diary-from-outlook} to import the entry. You can make this command
1542 recognize additional appointment message formats by customizing the
1543 variable @code{diary-outlook-formats}.
1545 @cindex iCalendar support
1546 The icalendar package allows you to transfer data between your Emacs
1547 diary file and iCalendar files, which are defined in ``RFC
1548 2445---Internet Calendaring and Scheduling Core Object Specification
1549 (iCalendar)'' (as well as the earlier vCalendar format).
1551 @c Importing works for ``ordinary'' (i.e. non-recurring) events, but
1552 @c (at present) may not work correctly (if at all) for recurring events.
1553 @c Exporting of diary files into iCalendar files should work correctly
1554 @c for most diary entries. This feature is a work in progress, so the
1555 @c commands may evolve in future.
1557 @findex icalendar-import-buffer
1558 The command @code{icalendar-import-buffer} extracts
1559 iCalendar data from the current buffer and adds it to your (default)
1560 diary file. This function is also suitable for automatic extraction of
1561 iCalendar data; for example with the Rmail mail client one could use:
1564 (add-hook 'rmail-show-message-hook 'icalendar-import-buffer)
1567 @findex icalendar-import-file
1568 The command @code{icalendar-import-file} imports an iCalendar file
1569 and adds the results to an Emacs diary file. For example:
1572 (icalendar-import-file "/here/is/calendar.ics"
1573 "/there/goes/ical-diary")
1577 You can use an @code{#include} directive to add the import file contents
1578 to the main diary file, if these are different files.
1580 @inforef{Fancy Diary Display,, emacs-xtra}.
1583 @xref{Fancy Diary Display}.
1587 @findex icalendar-export-file, icalendar-export-region
1588 Use @code{icalendar-export-file} to interactively export an entire
1589 Emacs diary file to iCalendar format. To export only a part of a diary
1590 file, mark the relevant area, and call @code{icalendar-export-region}.
1591 In both cases the result is appended to the target file.
1593 @node Daylight Saving
1594 @section Daylight Saving Time
1595 @cindex daylight saving time
1597 Emacs understands the difference between standard time and daylight
1598 saving time---the times given for sunrise, sunset, solstices,
1599 equinoxes, and the phases of the moon take that into account. The rules
1600 for daylight saving time vary from place to place and have also varied
1601 historically from year to year. To do the job properly, Emacs needs to
1602 know which rules to use.
1604 @vindex calendar-daylight-savings-starts
1605 @vindex calendar-daylight-savings-ends
1606 Some operating systems keep track of the rules that apply to the place
1607 where you are; on these systems, Emacs gets the information it needs
1608 from the system automatically. If some or all of this information is
1609 missing, Emacs fills in the gaps with the rules currently used in
1610 Cambridge, Massachusetts. If the resulting rules are not what you want,
1611 you can tell Emacs the rules to use by setting certain variables:
1612 @code{calendar-daylight-savings-starts} and
1613 @code{calendar-daylight-savings-ends}.
1615 These values should be Lisp expressions that refer to the variable
1616 @code{year}, and evaluate to the Gregorian date on which daylight
1617 saving time starts or (respectively) ends, in the form of a list
1618 @code{(@var{month} @var{day} @var{year})}. The values should be
1619 @code{nil} if your area does not use daylight saving time.
1621 Emacs uses these expressions to determine the starting date of
1622 daylight saving time for the holiday list and for correcting times of
1623 day in the solar and lunar calculations.
1625 The values for Cambridge, Massachusetts are as follows:
1628 (calendar-nth-named-day 2 0 3 year)
1629 (calendar-nth-named-day 1 0 11 year)
1633 That is, the second 0th day (Sunday) of the third month (March) in
1634 the year specified by @code{year}, and the first Sunday of the eleventh month
1635 (November) of that year. If daylight saving time were
1636 changed to start on October 1, you would set
1637 @code{calendar-daylight-savings-starts} to this:
1643 If there is no daylight saving time at your location, or if you want
1644 all times in standard time, set @code{calendar-daylight-savings-starts}
1645 and @code{calendar-daylight-savings-ends} to @code{nil}.
1647 @vindex calendar-daylight-time-offset
1648 The variable @code{calendar-daylight-time-offset} specifies the
1649 difference between daylight saving time and standard time, measured in
1650 minutes. The value for Cambridge, Massachusetts is 60.
1652 @c @vindex calendar-daylight-savings-starts-time too long!
1653 @vindex calendar-daylight-savings-ends-time
1654 Finally, the two variables
1655 @code{calendar-daylight-savings-starts-time} and
1656 @code{calendar-daylight-savings-ends-time} specify the number of
1657 minutes after midnight local time when the transition to and from
1658 daylight saving time should occur. For Cambridge, Massachusetts both
1659 variables' values are 120.
1661 @node Time Intervals
1662 @section Summing Time Intervals
1663 @cindex time intervals, summing
1664 @cindex summing time intervals
1667 The timeclock package adds up time intervals, so you can (for
1668 instance) keep track of how much time you spend working on particular
1671 @findex timeclock-in
1672 @findex timeclock-out
1673 @findex timeclock-change
1674 @findex timeclock-workday-remaining
1675 @findex timeclock-when-to-leave
1676 Use the @kbd{M-x timeclock-in} command when you start working on a
1677 project, and @kbd{M-x timeclock-out} command when you're done. Each
1678 time you do this, it adds one time interval to the record of the
1679 project. You can change to working on a different project with @kbd{M-x
1682 Once you've collected data from a number of time intervals, you can use
1683 @kbd{M-x timeclock-workday-remaining} to see how much time is left to
1684 work today (assuming a typical average of 8 hours a day), and @kbd{M-x
1685 timeclock-when-to-leave} which will calculate when you're ``done.''
1687 @vindex timeclock-modeline-display
1688 @findex timeclock-modeline-display
1689 If you want Emacs to display the amount of time ``left'' of your
1690 workday in the mode line, either customize the
1691 @code{timeclock-modeline-display} variable and set its value to
1692 @code{t}, or invoke the @kbd{M-x timeclock-modeline-display} command.
1694 @vindex timeclock-ask-before-exiting
1695 Terminating the current Emacs session might or might not mean that
1696 you have stopped working on the project and, by default, Emacs asks
1697 you. You can, however, set customize the value of the variable
1698 @code{timeclock-ask-before-exiting} to @code{nil} to avoid the question;
1699 then, only an explicit @kbd{M-x timeclock-out} or @kbd{M-x
1700 timeclock-change} will tell Emacs that the current interval is over.
1702 @cindex @file{.timelog} file
1703 @vindex timeclock-file
1704 @findex timeclock-reread-log
1705 The timeclock functions work by accumulating the data in a file
1706 called @file{.timelog} in your home directory. You can specify a
1707 different name for this file by customizing the variable
1708 @code{timeclock-file}. If you edit the timeclock file manually, or if
1709 you change the value of any of timeclock's customizable variables, you
1710 should run the command @kbd{M-x timeclock-reread-log} to update the
1711 data in Emacs from the file.
1714 @include cal-xtra.texi