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