428
+ − 1 @node Calendar/Diary, Sorting, Reading Mail, Top
+ − 2 @section Calendar Mode and the Diary
+ − 3 @cindex calendar
+ − 4 @findex calendar
+ − 5
+ − 6 Emacs provides the functions of a desk calendar, with a diary of
+ − 7 planned or past events. To enter the calendar, type @kbd{M-x calendar};
+ − 8 this displays a three-month calendar centered on the current month, with
+ − 9 point on the current date. With a numeric argument, as in @kbd{C-u M-x
+ − 10 calendar}, it prompts you for the month and year to be the center of the
+ − 11 three-month calendar. The calendar uses its own buffer, whose major
+ − 12 mode is Calendar mode.
+ − 13
+ − 14 @kbd{Button2} in the calendar brings up a menu of operations on a
+ − 15 particular date; @kbd{Buttons3} brings up a menu of commonly used
+ − 16 calendar features that are independent of any particular date. To exit
+ − 17 the calendar, type @kbd{q}. @xref{Calendar, Customizing the Calendar
446
+ − 18 and Diary,, lispref, The XEmacs Lisp Reference Manual}, for customization
428
+ − 19 information about the calendar and diary.
+ − 20
+ − 21 @menu
+ − 22 * Calendar Motion:: Moving through the calendar; selecting a date.
+ − 23 * Scroll Calendar:: Bringing earlier or later months onto the screen.
+ − 24 * Mark and Region:: Remembering dates, the mark ring.
+ − 25 * General Calendar:: Exiting or recomputing the calendar.
+ − 26 * LaTeX Calendar:: Print a calendar using LaTeX.
+ − 27 * Holidays:: Displaying dates of holidays.
+ − 28 * Sunrise/Sunset:: Displaying local times of sunrise and sunset.
+ − 29 * Lunar Phases:: Displaying phases of the moon.
+ − 30 * Other Calendars:: Converting dates to other calendar systems.
+ − 31 * Diary:: Displaying events from your diary.
+ − 32 * Calendar Customization:: Altering the behavior of the features above.
+ − 33 @end menu
+ − 34
+ − 35 @node Calendar Motion, Scroll Calendar, Calendar/Diary, Calendar/Diary
+ − 36 @subsection Movement in the Calendar
+ − 37
+ − 38 @cindex moving inside the calendar
+ − 39 Calendar mode lets you move through the calendar in logical units of
+ − 40 time such as days, weeks, months, and years. If you move outside the
+ − 41 three months originally displayed, the calendar display ``scrolls''
+ − 42 automatically through time to make the selected date visible. Moving to
+ − 43 a date lets you view its holidays or diary entries, or convert it to other
+ − 44 calendars; moving longer time periods is also useful simply to scroll the
+ − 45 calendar.
+ − 46
+ − 47 @menu
+ − 48 * Calendar Unit Motion:: Moving by days, weeks, months, and years.
+ − 49 * Move to Beginning or End:: Moving to start/end of weeks, months, and years.
+ − 50 * Specified Dates:: Moving to the current date or another
+ − 51 specific date.
+ − 52 @end menu
+ − 53
+ − 54 @node Calendar Unit Motion, Move to Beginning or End, Calendar Motion, Calendar Motion
+ − 55 @subsubsection Motion by Integral Days, Weeks, Months, Years
+ − 56
+ − 57 The commands for movement in the calendar buffer parallel the
+ − 58 commands for movement in text. You can move forward and backward by
+ − 59 days, weeks, months, and years.
+ − 60
+ − 61 @table @kbd
+ − 62 @item C-f
+ − 63 Move point one day forward (@code{calendar-forward-day}).
+ − 64 @item C-b
+ − 65 Move point one day backward (@code{calendar-backward-day}).
+ − 66 @item C-n
+ − 67 Move point one week forward (@code{calendar-forward-week}).
+ − 68 @item C-p
+ − 69 Move point one week backward (@code{calendar-backward-week}).
+ − 70 @item M-@}
+ − 71 Move point one month forward (@code{calendar-forward-month}).
+ − 72 @item M-@{
+ − 73 Move point one month backward (@code{calendar-backward-month}).
+ − 74 @item C-x ]
+ − 75 Move point one year forward (@code{calendar-forward-year}).
+ − 76 @item C-x [
+ − 77 Move point one year backward (@code{calendar-backward-year}).
+ − 78 @end table
+ − 79
+ − 80 @kindex C-f @r{(Calendar mode)}
+ − 81 @findex calendar-forward-day
+ − 82 @kindex C-b @r{(Calendar mode)}
+ − 83 @findex calendar-backward-day
+ − 84 @kindex C-n @r{(Calendar mode)}
+ − 85 @findex calendar-forward-week
+ − 86 @kindex C-p @r{(Calendar mode)}
+ − 87 @findex calendar-backward-week
+ − 88 The day and week commands are natural analogues of the usual Emacs
+ − 89 commands for moving by characters and by lines. Just as @kbd{C-n}
+ − 90 usually moves to the same column in the following line, in Calendar
+ − 91 mode it moves to the same day in the following week. And @kbd{C-p}
+ − 92 moves to the same day in the previous week.
+ − 93
+ − 94 The arrow keys are equivalent to @kbd{C-f}, @kbd{C-b}, @kbd{C-n} and
+ − 95 @kbd{C-p}, just as they normally are in other modes.
+ − 96
+ − 97 @kindex M-@} @r{(Calendar mode)}
+ − 98 @findex calendar-forward-month
+ − 99 @kindex M-@{ @r{(Calendar mode)}
+ − 100 @findex calendar-backward-month
+ − 101 @kindex C-x ] @r{(Calendar mode)}
+ − 102 @findex calendar-forward-year
+ − 103 @kindex C-x [ @r{(Calendar mode)}
+ − 104 @findex calendar-forward-year
+ − 105 The commands for motion by months and years work like those for
+ − 106 weeks, but move a larger distance. The month commands @kbd{M-@}} and
+ − 107 @kbd{M-@{} move forward or backward by an entire month's time. The
+ − 108 year commands @kbd{C-x ]} and @w{@kbd{C-x [}} move forward or backward a
+ − 109 whole year.
+ − 110
+ − 111 The easiest way to remember these commands is to consider months and
+ − 112 years analogous to paragraphs and pages of text, respectively. But the
+ − 113 commands themselves are not quite analogous. The ordinary Emacs paragraph
+ − 114 commands move to the beginning or end of a paragraph, whereas these month
+ − 115 and year commands move by an entire month or an entire year, which usually
+ − 116 involves skipping across the end of a month or year.
+ − 117
+ − 118 All these commands accept a numeric argument as a repeat count.
+ − 119 For convenience, the digit keys and the minus sign specify numeric
+ − 120 arguments in Calendar mode even without the Meta modifier. For example,
+ − 121 @kbd{100 C-f} moves point 100 days forward from its present location.
+ − 122
+ − 123 @node Move to Beginning or End, Specified Dates, Calendar Unit Motion, Calendar Motion
+ − 124 @subsubsection Beginning or End of Week, Month or Year
+ − 125
+ − 126 A week (or month, or year) is not just a quantity of days; we think of
+ − 127 weeks (months, years) as starting on particular dates. So Calendar mode
+ − 128 provides commands to move to the beginning or end of a week, month or
+ − 129 year:
+ − 130
+ − 131 @table @kbd
+ − 132 @kindex C-a @r{(Calendar mode)}
+ − 133 @findex calendar-beginning-of-week
+ − 134 @item C-a
+ − 135 Move point to start of week (@code{calendar-beginning-of-week}).
+ − 136 @kindex C-e @r{(Calendar mode)}
+ − 137 @findex calendar-end-of-week
+ − 138 @item C-e
+ − 139 Move point to end of week (@code{calendar-end-of-week}).
+ − 140 @kindex M-a @r{(Calendar mode)}
+ − 141 @findex calendar-beginning-of-month
+ − 142 @item M-a
+ − 143 Move point to start of month (@code{calendar-beginning-of-month}).
+ − 144 @kindex M-e @r{(Calendar mode)}
+ − 145 @findex calendar-end-of-month
+ − 146 @item M-e
+ − 147 Move point to end of month (@code{calendar-end-of-month}).
+ − 148 @kindex M-< @r{(Calendar mode)}
+ − 149 @findex calendar-beginning-of-year
+ − 150 @item M-<
+ − 151 Move point to start of year (@code{calendar-beginning-of-year}).
+ − 152 @kindex M-> @r{(Calendar mode)}
+ − 153 @findex calendar-end-of-year
+ − 154 @item M->
+ − 155 Move point to end of year (@code{calendar-end-of-year}).
+ − 156 @end table
+ − 157
+ − 158 These commands also take numeric arguments as repeat counts, with the
+ − 159 repeat count indicating how many weeks, months, or years to move
+ − 160 backward or forward.
+ − 161
+ − 162 @vindex calendar-week-start-day
+ − 163 @cindex weeks, which day they start on
+ − 164 @cindex calendar, first day of week
+ − 165 By default, weeks begin on Sunday. To make them begin on Monday
+ − 166 instead, set the variable @code{calendar-week-start-day} to 1.
+ − 167
+ − 168 @node Specified Dates,,Move to Beginning or End, Calendar Motion
+ − 169 @subsubsection Particular Dates
+ − 170
+ − 171 Calendar mode provides commands for moving to a particular date
+ − 172 specified in various ways.
+ − 173
+ − 174 @table @kbd
+ − 175 @item g d
+ − 176 Move point to specified date (@code{calendar-goto-date}).
+ − 177 @item o
+ − 178 Center calendar around specified month (@code{calendar-other-month}).
+ − 179 @item .
+ − 180 Move point to today's date (@code{calendar-goto-today}).
+ − 181 @end table
+ − 182
+ − 183 @kindex g d @r{(Calendar mode)}
+ − 184 @findex calendar-goto-date
+ − 185 @kbd{g d} (@code{calendar-goto-date}) prompts for a year, a month, and a day
+ − 186 of the month, and then moves to that date. Because the calendar includes all
+ − 187 dates from the beginning of the current era, you must type the year in its
+ − 188 entirety; that is, type @samp{1990}, not @samp{90}.
+ − 189
+ − 190 @kindex o @r{(Calendar mode)}
+ − 191 @findex calendar-other-month
+ − 192 @kbd{o} (@code{calendar-other-month}) prompts for a month and year,
+ − 193 then centers the three-month calendar around that month.
+ − 194
+ − 195 @kindex . @r{(Calendar mode)}
+ − 196 @findex calendar-goto-today
+ − 197 You can return to today's date with @kbd{.}@:
+ − 198 (@code{calendar-goto-today}).
+ − 199
+ − 200 @node Scroll Calendar, Mark and Region, Calendar Motion, Calendar/Diary
+ − 201 @subsection Scrolling the Calendar through Time
+ − 202
+ − 203 @cindex scrolling in the calendar
+ − 204 The calendar display scrolls automatically through time when you move out
+ − 205 of the visible portion. You can also scroll it manually. Imagine that the
+ − 206 calendar window contains a long strip of paper with the months on it.
+ − 207 Scrolling it means moving the strip so that new months become visible in
+ − 208 the window.
+ − 209
+ − 210 @table @kbd
+ − 211 @item C-x <
+ − 212 Scroll calendar one month forward (@code{scroll-calendar-left}).
+ − 213 @item C-x >
+ − 214 Scroll calendar one month backward (@code{scroll-calendar-right}).
+ − 215 @item C-v
+ − 216 @itemx @key{NEXT}
+ − 217 Scroll calendar three months forward
+ − 218 (@code{scroll-calendar-left-three-months}).
+ − 219 @item M-v
+ − 220 @itemx @key{PRIOR}
+ − 221 Scroll calendar three months backward
+ − 222 (@code{scroll-calendar-right-three-months}).
+ − 223 @end table
+ − 224
+ − 225 @kindex C-x < @r{(Calendar mode)}
+ − 226 @findex scroll-calendar-left
+ − 227 @kindex C-x > @r{(Calendar mode)}
+ − 228 @findex scroll-calendar-right
+ − 229 The most basic calendar scroll commands scroll by one month at a
+ − 230 time. This means that there are two months of overlap between the
+ − 231 display before the command and the display after. @kbd{C-x <} scrolls
+ − 232 the calendar contents one month to the left; that is, it moves the
+ − 233 display forward in time. @kbd{C-x >} scrolls the contents to the
+ − 234 right, which moves backwards in time.
+ − 235
+ − 236 @kindex C-v @r{(Calendar mode)}
+ − 237 @findex scroll-calendar-left-three-months
+ − 238 @kindex M-v @r{(Calendar mode)}
+ − 239 @findex scroll-calendar-right-three-months
+ − 240 The commands @kbd{C-v} and @kbd{M-v} scroll the calendar by an entire
+ − 241 ``screenful''---three months---in analogy with the usual meaning of
+ − 242 these commands. @kbd{C-v} makes later dates visible and @kbd{M-v} makes
+ − 243 earlier dates visible. These commands take a numeric argument as a
+ − 244 repeat count; in particular, since @kbd{C-u} multiplies the next command
+ − 245 by four, typing @kbd{C-u C-v} scrolls the calendar forward by a year and
+ − 246 typing @kbd{C-u M-v} scrolls the calendar backward by a year.
+ − 247
+ − 248 The function keys @key{NEXT} and @key{PRIOR} are equivalent to
+ − 249 @kbd{C-v} and @kbd{M-v}, just as they are in other modes.
+ − 250
+ − 251
+ − 252 @node Mark and Region, General Calendar, Scroll Calendar, Calendar/Diary
+ − 253 @subsection The Mark and the Region
+ − 254
+ − 255 The concept of the mark applies to the calendar just as to any other
+ − 256 buffer, but it marks a @emph{date}, not a @emph{position} in the buffer.
+ − 257 The region consists of the days between the mark and point (including
+ − 258 the starting and stopping dates).
+ − 259
+ − 260 @table @kbd
+ − 261 @item C-SPC
+ − 262 Set the mark to today's date (@code{calendar-set-mark}).
+ − 263 @item C-@@
+ − 264 The same.
+ − 265 @item C-x C-x
+ − 266 Interchange mark and point (@code{calendar-exchange-point-and-mark}).
+ − 267 @item M-=
+ − 268 Display the number of days in the current region
+ − 269 (@code{calendar-count-days-region}).
+ − 270 @end table
+ − 271
+ − 272 @kindex C-@@ @r{(Calendar mode)}
+ − 273 @kindex C-SPC @r{(Calendar mode)}
+ − 274 @findex calendar-set-mark
+ − 275 @kindex C-x C-x @r{(Calendar mode)}
+ − 276 @findex calendar-exchange-point-and-mark
+ − 277 You set the mark in the calendar, as in any other buffer, by using @kbd{C-@@}
+ − 278 or @kbd{C-SPC} (@code{calendar-set-mark}). You return to the marked date
+ − 279 with the command @kbd{C-x C-x} (@code{calendar-exchange-point-and-mark})
+ − 280 which puts the mark where point was and point where mark was. The calendar
+ − 281 is scrolled as necessary, if the marked date was not visible on the
+ − 282 screen. This does not change the extent of the region.
+ − 283
+ − 284 @kindex M-= @r{(Calendar mode)}
+ − 285 @findex calendar-count-days-region
+ − 286 To determine the number of days in the region, type @kbd{M-=}
+ − 287 (@code{calendar-count-days-region}). The numbers of days printed is
+ − 288 @emph{inclusive}; that is, it includes the days specified by mark and
+ − 289 point.
+ − 290
+ − 291 @cindex mark ring
+ − 292 The main use of the mark in the calendar is to remember dates that you may
+ − 293 want to go back to. To make this feature more useful, the mark ring
+ − 294 (@pxref{Mark Ring}) operates exactly as in other buffers: Emacs remembers
+ − 295 16 previous locations of the mark. To return to a marked date, type @kbd{C-u
+ − 296 C-SPC} (or @kbd{C-u C-@@}); this is the command @code{calendar-set-mark} given
+ − 297 a numeric argument. It moves point to where the mark was, restores the mark
+ − 298 from the ring of former marks, and stores the previous point at the end of
+ − 299 the mark ring. So, repeated use of this command moves point through all
+ − 300 the old marks on the ring, one by one.
+ − 301
+ − 302 @node General Calendar, LaTeX Calendar, Mark and Region, Calendar/Diary
+ − 303 @subsection Miscellaneous Calendar Commands
+ − 304
+ − 305 @table @kbd
+ − 306 @item p d
+ − 307 Display day-in-year (@code{calendar-print-day-of-year}).
+ − 308 @item ?
+ − 309 Briefly describe calendar commands (@code{describe-calendar-mode}).
+ − 310 @item C-c C-l
+ − 311 Regenerate the calendar window (@code{redraw-calendar}).
+ − 312 @item SPC
+ − 313 Scroll the next window (@code{scroll-other-window}).
+ − 314 @item q
+ − 315 Exit from calendar (@code{exit-calendar}).
+ − 316 @end table
+ − 317
+ − 318 @kindex p d @r{(Calendar mode)}
+ − 319 @cindex day of year
+ − 320 @findex calendar-print-day-of-year
+ − 321 If you want to know how many days have elapsed since the start of
+ − 322 the year, or the number of days remaining in the year, type the @kbd{p d}
+ − 323 command (@code{calendar-print-day-of-year}). This displays both
+ − 324 of those numbers in the echo area.
+ − 325
+ − 326 @kindex ? @r{(Calendar mode)}
+ − 327 @findex describe-calendar-mode
+ − 328 To display a brief description of the calendar commands, type @kbd{?}
+ − 329 (@code{describe-calendar-mode}). For a fuller description, type @kbd{C-h m}.
+ − 330
+ − 331 @kindex SPC @r{(Calendar mode)}
+ − 332 @findex scroll-other-window
+ − 333 You can use @kbd{SPC} (@code{scroll-other-window}) to scroll the other
+ − 334 window. This is handy when you display a list of holidays or diary entries
+ − 335 in another window.
+ − 336
+ − 337 @kindex C-c C-l @r{(Calendar mode)}
+ − 338 @findex redraw-calendar
+ − 339 If the calendar window text gets corrupted, type @kbd{C-c C-l}
+ − 340 (@code{redraw-calendar}) to redraw it. (This can only happen if you use
+ − 341 non-Calendar-mode editing commands.)
+ − 342
+ − 343 @kindex SPC @r{(Calendar mode)}
+ − 344 In Calendar mode, you can use @kbd{SPC} (@code{scroll-other-window})
+ − 345 to scroll the other window. This is handy when you display a list of
+ − 346 holidays or diary entries in another window.
+ − 347
+ − 348 @kindex q @r{(Calendar mode)}
+ − 349 @findex exit-calendar
+ − 350 To exit from the calendar, type @kbd{q} (@code{exit-calendar}). This
+ − 351 buries all buffers related to the calendar, selecting other buffers.
+ − 352 (If a frame contains a dedicated calendar window, exiting from the
+ − 353 calendar iconifies that frame.)
+ − 354
+ − 355 @node LaTeX Calendar, Holidays, General Calendar, Calendar/Diary
+ − 356 @section LaTeX Calendar
+ − 357 @cindex calendar and La@TeX{}
+ − 358
+ − 359 The Calendar La@TeX{} commands produce a buffer of La@TeX{} code that
+ − 360 prints as a calendar. Depending on the command you use, the printed
+ − 361 calendar covers the day, week, month or year that point is in.
+ − 362
+ − 363 @kindex t @r{(Calendar mode)}
+ − 364 @table @kbd
+ − 365 @item t m
+ − 366 Generate a one-month calendar (@code{cal-tex-cursor-month}).
+ − 367 @item t M
+ − 368 Generate a sideways-printing one-month calendar
+ − 369 (@code{cal-tex-cursor-month-landscape}).
+ − 370 @item t d
+ − 371 Generate a one-day calendar
+ − 372 (@code{cal-tex-cursor-day}).
+ − 373 @item t w 1
+ − 374 Generate a one-page calendar for one week
+ − 375 (@code{cal-tex-cursor-week}).
+ − 376 @item t w 2
+ − 377 Generate a two-page calendar for one week
+ − 378 (@code{cal-tex-cursor-week2}).
+ − 379 @item t w 3
+ − 380 Generate an ISO-style calendar for one week
+ − 381 (@code{cal-tex-cursor-week-iso}).
+ − 382 @item t w 4
+ − 383 Generate a calendar for one Monday-starting week
+ − 384 (@code{cal-tex-cursor-week-monday}).
+ − 385 @item t f w
+ − 386 Generate a Filofax-style two-weeks-at-a-glance calendar
+ − 387 (@code{cal-tex-cursor-filofax-2week}).
+ − 388 @item t f W
+ − 389 Generate a Filofax-style one-week-at-a-glance calendar
+ − 390 (@code{cal-tex-cursor-filofax-week}).
+ − 391 @item t y
+ − 392 Generate a calendar for one year
+ − 393 (@code{cal-tex-cursor-year}).
+ − 394 @item t Y
+ − 395 Generate a sideways-printing calendar for one year
+ − 396 (@code{cal-tex-cursor-year-landscape}).
+ − 397 @item t f y
+ − 398 Generate a Filofax-style calendar for one year
+ − 399 (@code{cal-tex-cursor-filofax-year}).
+ − 400 @end table
+ − 401
+ − 402 Some of these commands print the calendar sideways (in ``landscape
+ − 403 mode''), so it can be wider than it is long. Some of them use Filofax
+ − 404 paper size (3.75in x 6.75in). All of these commands accept a prefix
+ − 405 argument which specifies how many days, weeks, months or years to print
+ − 406 (starting always with the selected one).
+ − 407
+ − 408 If the variable @code{cal-tex-holidays} is non-@code{nil} (the
+ − 409 default), then the printed calendars show the holidays in
+ − 410 @code{calendar-holidays}. If the variable @code{cal-tex-diary} is
+ − 411 non-@code{nil} (the default is @code{nil}), diary entries are included
+ − 412 also (in weekly and monthly calendars only).
+ − 413
+ − 414 @node Holidays, Sunrise/Sunset, LaTeX Calendar, Calendar/Diary
+ − 415 @subsection Holidays
+ − 416 @cindex holidays
+ − 417
+ − 418 The Emacs calendar knows about all major and many minor holidays,
+ − 419 and can display them.
+ − 420
+ − 421 @table @kbd
+ − 422 @item h
+ − 423 Display holidays for the selected date
+ − 424 (@code{calendar-cursor-holidays}).
+ − 425 @item Button2 Holidays
+ − 426 Display any holidays for the date you click on.
+ − 427 @item x
+ − 428 Mark holidays in the calendar window (@code{mark-calendar-holidays}).
+ − 429 @item u
+ − 430 Unmark calendar window (@code{calendar-unmark}).
+ − 431 @item a
+ − 432 List all holidays for the displayed three months in another window
+ − 433 (@code{list-calendar-holidays}).
+ − 434 @item M-x holidays
+ − 435 List all holidays for three months around today's date in another
+ − 436 window.
+ − 437 @item M-x list-holidays
+ − 438 List holidays in another window for a specified range of years.
+ − 439 @end table
+ − 440
+ − 441 @kindex h @r{(Calendar mode)}
+ − 442 @findex calendar-cursor-holidays
+ − 443 To see if any holidays fall on a given date, position point on that
+ − 444 date in the calendar window and use the @kbd{h} command. Alternatively,
+ − 445 click on that date with @kbd{Button2} and then choose @kbd{Holidays}
+ − 446 from the menu that appears. Either way, this displays the holidays for
+ − 447 that date, in the echo area if they fit there, otherwise in a separate
+ − 448 window.
+ − 449
+ − 450 @kindex x @r{(Calendar mode)}
+ − 451 @findex mark-calendar-holidays
+ − 452 @kindex u @r{(Calendar mode)}
+ − 453 @findex calendar-unmark
+ − 454 To view the distribution of holidays for all the dates shown in the
+ − 455 calendar, use the @kbd{x} command. This displays the dates that are
+ − 456 holidays in a different face (or places a @samp{*} after these dates, if
+ − 457 display with multiple faces is not available). The command applies both
+ − 458 to the currently visible months and to other months that subsequently
+ − 459 become visible by scrolling. To turn marking off and erase the current
+ − 460 marks, type @kbd{u}, which also erases any diary marks (@pxref{Diary}).
+ − 461
+ − 462 @kindex a @r{(Calendar mode)}
+ − 463 @findex list-calendar-holidays
+ − 464 To get even more detailed information, use the @kbd{a} command, which
+ − 465 displays a separate buffer containing a list of all holidays in the
+ − 466 current three-month range. You can use @key{SPC} in the calendar window
+ − 467 to scroll that list.
+ − 468
+ − 469 @findex holidays
+ − 470 The command @kbd{M-x holidays} displays the list of holidays for the
+ − 471 current month and the preceding and succeeding months; this works even
+ − 472 if you don't have a calendar window. If you want the list of holidays
+ − 473 centered around a different month, use @kbd{C-u M-x holidays}, which
+ − 474 prompts for the month and year.
+ − 475
+ − 476 The holidays known to Emacs include United States holidays and the
+ − 477 major Christian, Jewish, and Islamic holidays; also the solstices and
+ − 478 equinoxes.
+ − 479
+ − 480 @findex list-holidays
+ − 481 The command @kbd{M-x list-holidays} displays the list of holidays for
+ − 482 a range of years. This function asks you for the starting and stopping
+ − 483 years, and allows you to choose all the holidays or one of several
+ − 484 categories of holidays. You can use this command even if you don't have
+ − 485 a calendar window.
+ − 486
+ − 487 The dates used by Emacs for holidays are based on @emph{current
+ − 488 practice}, not historical fact. Historically, for instance, the start
+ − 489 of daylight savings time and even its existence have varied from year to
+ − 490 year, but present United States law mandates that daylight savings time
+ − 491 begins on the first Sunday in April. When the daylight savings rules
+ − 492 are set up for the United States, Emacs always uses the present
+ − 493 definition, even though it is wrong for some prior years.
+ − 494
+ − 495 @node Sunrise/Sunset, Lunar Phases, Holidays, Calendar/Diary
+ − 496 @subsection Times of Sunrise and Sunset
+ − 497 @cindex sunrise and sunset
+ − 498
+ − 499 Special calendar commands can tell you, to within a minute or two, the
+ − 500 times of sunrise and sunset for any date.
+ − 501
+ − 502 @table @kbd
+ − 503 @item S
+ − 504 Display times of sunrise and sunset for the selected date
+ − 505 (@code{calendar-sunrise-sunset}).
+ − 506 @item Button2 Sunrise/Sunset
+ − 507 Display times of sunrise and sunset for the date you click on.
+ − 508 @item M-x sunrise-sunset
+ − 509 Display times of sunrise and sunset for today's date.
+ − 510 @item C-u M-x sunrise-sunset
+ − 511 Display times of sunrise and sunset for a specified date.
+ − 512 @end table
+ − 513
+ − 514 @kindex S @r{(Calendar mode)}
+ − 515 @findex calendar-sunrise-sunset
+ − 516 @findex sunrise-sunset
+ − 517 Within the calendar, to display the @emph{local times} of sunrise and
+ − 518 sunset in the echo area, move point to the date you want, and type
+ − 519 @kbd{S}. Alternatively, click @kbd{Button2} on the date, then choose
+ − 520 @kbd{Sunrise/Sunset} from the menu that appears. The command @kbd{M-x
+ − 521 sunrise-sunset} is available outside the calendar to display this
+ − 522 information for today's date or a specified date. To specify a date
+ − 523 other than today, use @kbd{C-u M-x sunrise-sunset}, which prompts for
+ − 524 the year, month, and day.
+ − 525
+ − 526 You can display the times of sunrise and sunset for any location and
+ − 527 any date with @kbd{C-u C-u M-x sunrise-sunset}. This asks you for a
+ − 528 longitude, latitude, number of minutes difference from Coordinated
+ − 529 Universal Time, and date, and then tells you the times of sunrise and
+ − 530 sunset for that location on that date.
+ − 531
+ − 532 Because the times of sunrise and sunset depend on the location on
+ − 533 earth, you need to tell Emacs your latitude, longitude, and location
+ − 534 name before using these commands. Here is an example of what to set:
+ − 535
+ − 536 @vindex calendar-location-name
+ − 537 @vindex calendar-longitude
+ − 538 @vindex calendar-latitude
+ − 539 @example
+ − 540 (setq calendar-latitude 40.1)
+ − 541 (setq calendar-longitude -88.2)
+ − 542 (setq calendar-location-name "Urbana, IL")
+ − 543 @end example
+ − 544
+ − 545 @noindent
+ − 546 Use one decimal place in the values of @code{calendar-latitude} and
+ − 547 @code{calendar-longitude}.
+ − 548
+ − 549 Your time zone also affects the local time of sunrise and sunset.
+ − 550 Emacs usually gets time zone information from the operating system, but
+ − 551 if these values are not what you want (or if the operating system does
+ − 552 not supply them), you must set them yourself. Here is an example:
+ − 553
+ − 554 @vindex calendar-time-zone
+ − 555 @vindex calendar-standard-time-zone-name
+ − 556 @vindex calendar-daylight-time-zone-name
+ − 557 @example
+ − 558 (setq calendar-time-zone -360)
+ − 559 (setq calendar-standard-time-zone-name "CST")
+ − 560 (setq calendar-daylight-time-zone-name "CDT")
+ − 561 @end example
+ − 562
+ − 563 @noindent
+ − 564 The value of @code{calendar-time-zone} is the number of minutes
+ − 565 difference between your local standard time and Coordinated Universal
+ − 566 Time (Greenwich time). The values of
+ − 567 @code{calendar-standard-time-zone-name} and
+ − 568 @code{calendar-daylight-time-zone-name} are the abbreviations used in
+ − 569 your time zone. Emacs displays the times of sunrise and sunset
+ − 570 @emph{corrected for daylight savings time}. @xref{Daylight Savings},
+ − 571 for how daylight savings time is determined.
+ − 572
+ − 573 As a user, you might find it convenient to set the calendar location
442
+ − 574 variables for your usual physical location in your init file. And when
+ − 575 you install Emacs on a machine, you can create a @file{default.el} file
+ − 576 which sets them properly for the typical location of most users of that
+ − 577 machine. @xref{Init File}.
428
+ − 578
+ − 579 @node Lunar Phases, Other Calendars, Sunrise/Sunset, Calendar/Diary
+ − 580 @subsection Phases of the Moon
+ − 581 @cindex phases of the moon
+ − 582 @cindex moon, phases of
+ − 583
+ − 584 These calendar commands display the dates and times of the phases of
+ − 585 the moon (new moon, first quarter, full moon, last quarter). This
+ − 586 feature is useful for debugging problems that ``depend on the phase of
+ − 587 the moon.''
+ − 588
+ − 589 @table @kbd
+ − 590 @item M
+ − 591 Display the dates and times for all the quarters of the moon for the
+ − 592 three-month period shown (@code{calendar-phases-of-moon}).
+ − 593 @item M-x phases-of-moon
+ − 594 Display dates and times of the quarters of the moon for three months around
+ − 595 today's date.
+ − 596 @end table
+ − 597
+ − 598 @kindex M @r{(Calendar mode)}
+ − 599 @findex calendar-phases-of-moon
+ − 600 Within the calendar, use the @kbd{M} command to display a separate
+ − 601 buffer of the phases of the moon for the current three-month range. The
+ − 602 dates and times listed are accurate to within a few minutes.
+ − 603
+ − 604 @findex phases-of-moon
+ − 605 Outside the calendar, use the command @kbd{M-x phases-of-moon} to
+ − 606 display the list of the phases of the moon for the current month and the
+ − 607 preceding and succeeding months. For information about a different
+ − 608 month, use @kbd{C-u M-x phases-of-moon}, which prompts for the month and
+ − 609 year.
+ − 610
+ − 611 The dates and times given for the phases of the moon are given in
+ − 612 local time (corrected for daylight savings, when appropriate); but if
+ − 613 the variable @code{calendar-time-zone} is void, Coordinated Universal
+ − 614 Time (the Greenwich time zone) is used. @xref{Daylight Savings}.
+ − 615
+ − 616 @node Other Calendars, Calendar Systems, Lunar Phases, Calendar/Diary
+ − 617 @subsection Conversion To and From Other Calendars
+ − 618
+ − 619 @cindex Gregorian calendar
+ − 620 The Emacs calendar displayed is @emph{always} the Gregorian calendar,
+ − 621 sometimes called the ``new style'' calendar, which is used in most of
+ − 622 the world today. However, this calendar did not exist before the
+ − 623 sixteenth century and was not widely used before the eighteenth century;
+ − 624 it did not fully displace the Julian calendar and gain universal
+ − 625 acceptance until the early twentieth century. The Emacs calendar can
+ − 626 display any month since January, year 1 of the current era, but the
+ − 627 calendar displayed is the Gregorian, even for a date at which the
+ − 628 Gregorian calendar did not exist.
+ − 629
+ − 630 While Emacs cannot display other calendars, it can convert dates to
+ − 631 and from several other calendars.
+ − 632
+ − 633 @menu
+ − 634 * Calendar Systems:: The calendars Emacs understands
+ − 635 (aside from Gregorian).
+ − 636 * To Other Calendar:: Converting the selected date to various calendars.
+ − 637 * From Other Calendar:: Moving to a date specified in another calendar.
+ − 638 * Mayan Calendar:: Moving to a date specified in a Mayan calendar.
+ − 639 @end menu
+ − 640
+ − 641 If you are interested in these calendars, you can convert dates one at a
+ − 642 time. Put point on the desired date of the Gregorian calendar and press the
+ − 643 appropriate keys. The @kbd{p} is a mnemonic for ``print'' since Emacs
+ − 644 ``prints' the equivalent date in the echo area.
+ − 645 @node Calendar Systems, To Other Calendar, Other Calendars, Other Calendars
+ − 646 @section Supported Calendar Systems
+ − 647
+ − 648 @cindex ISO commercial calendar
+ − 649 The ISO commercial calendar is used largely in Europe.
+ − 650
+ − 651 @cindex Julian calendar
+ − 652 The Julian calendar, named after Julius Caesar, was the one used in Europe
+ − 653 throughout medieval times, and in many countries up until the nineteenth
+ − 654 century.
+ − 655
+ − 656 @cindex Julian day numbers
+ − 657 @cindex astronomical day numbers
+ − 658 Astronomers use a simple counting of days elapsed since noon, Monday,
+ − 659 January 1, 4713 B.C. on the Julian calendar. The number of days elapsed
+ − 660 is called the @emph{Julian day number} or the @emph{Astronomical day number}.
+ − 661
+ − 662 @cindex Hebrew calendar
+ − 663 The Hebrew calendar is used by tradition in the Jewish religion. The
+ − 664 Emacs calendar program uses the Hebrew calendar to determine the dates
+ − 665 of Jewish holidays. Hebrew calendar dates begin and end at sunset.
+ − 666
+ − 667 @cindex Islamic calendar
+ − 668 The Islamic calendar is used in many predominantly Islamic countries.
+ − 669 Emacs uses it to determine the dates of Islamic holidays. There is no
+ − 670 universal agreement in the Islamic world about the calendar; Emacs uses
+ − 671 a widely accepted version, but the precise dates of Islamic holidays
+ − 672 often depend on proclamation by religious authorities, not on
+ − 673 calculations. As a consequence, the actual dates of observance can vary
+ − 674 slightly from the dates computed by Emacs. Islamic calendar dates begin
+ − 675 and end at sunset.
+ − 676
+ − 677 @cindex French Revolutionary calendar
+ − 678 The French Revolutionary calendar was created by the Jacobins after the 1789
+ − 679 revolution, to represent a more secular and nature-based view of the annual
+ − 680 cycle, and to install a 10-day week in a rationalization measure similar to
+ − 681 the metric system. The French government officially abandoned this
+ − 682 calendar at the end of 1805.
+ − 683
+ − 684 @cindex Mayan calendar
+ − 685 The Maya of Central America used three separate, overlapping calendar
+ − 686 systems, the @emph{long count}, the @emph{tzolkin}, and the @emph{haab}.
+ − 687 Emacs knows about all three of these calendars. Experts dispute the
+ − 688 exact correlation between the Mayan calendar and our calendar; Emacs uses the
+ − 689 Goodman-Martinez-Thompson correlation in its calculations.
+ − 690
+ − 691 @cindex Coptic calendar
+ − 692 @cindex Ethiopic calendar
+ − 693 The Copts use a calendar based on the ancient Egyptian solar calendar.
+ − 694 Their calendar consists of twelve 30-day months followed by an extra
+ − 695 five-day period. Once every fourth year they add a leap day to this
+ − 696 extra period to make it six days. The Ethiopic calendar is identical in
+ − 697 structure, but has different year numbers and month names.
+ − 698
+ − 699 @cindex Persian calendar
+ − 700 The Persians use a solar calendar based on a design of Omar Khayyam.
+ − 701 Their calendar consists of twelve months of which the first six have 31
+ − 702 days, the next five have 30 days, and the last has 29 in ordinary years
+ − 703 and 30 in leap years. Leap years occur in a complicated pattern every
+ − 704 four or five years.
+ − 705
+ − 706 @cindex Chinese calendar
+ − 707 The Chinese calendar is a complicated system of lunar months arranged
+ − 708 into solar years. The years go in cycles of sixty, each year containing
+ − 709 either twelve months in an ordinary year or thirteen months in a leap
+ − 710 year; each month has either 29 or 30 days. Years, ordinary months, and
+ − 711 days are named by combining one of ten ``celestial stems'' with one of
+ − 712 twelve ``terrestrial branches'' for a total of sixty names that are
+ − 713 repeated in a cycle of sixty.
+ − 714
+ − 715 @node To Other Calendar, From Other Calendar, Calendar Systems, Other Calendars
+ − 716 @section Converting To Other Calendars
+ − 717
+ − 718 The following commands describe the selected date (the date at point)
+ − 719 in various other calendar systems:
+ − 720
+ − 721 @table @kbd
+ − 722 @item Button2 Other Calendars
+ − 723 Display the date that you click on, expressed in various other calendars.
+ − 724 @kindex p @r{(Calendar mode)}
+ − 725 @findex calendar-print-iso-date
+ − 726 @item p c
+ − 727 Display ISO commercial calendar equivalent for selected day
+ − 728 (@code{calendar-print-iso-date}).
+ − 729 @findex calendar-print-julian-date
+ − 730 @item p j
+ − 731 Display Julian date for selected day (@code{calendar-print-julian-date}).
+ − 732 @findex calendar-print-astro-day-number
+ − 733 @item p a
+ − 734 Display astronomical (Julian) day number for selected day
+ − 735 (@code{calendar-print-astro-day-number}).
+ − 736 @findex calendar-print-hebrew-date
+ − 737 @item p h
+ − 738 Display Hebrew date for selected day (@code{calendar-print-hebrew-date}).
+ − 739 @findex calendar-print-islamic-date
+ − 740 @item p i
+ − 741 Display Islamic date for selected day (@code{calendar-print-islamic-date}).
+ − 742 @findex calendar-print-french-date
+ − 743 @item p f
+ − 744 Display French Revolutionary date for selected day
+ − 745 (@code{calendar-print-french-date}).
+ − 746 @findex calendar-print-chinese-date
+ − 747 @item p C
+ − 748 Display Chinese date for selected day
+ − 749 (@code{calendar-print-chinese-date}).
+ − 750 @findex calendar-print-coptic-date
+ − 751 @item p k
+ − 752 Display Coptic date for selected day
+ − 753 (@code{calendar-print-coptic-date}).
+ − 754 @findex calendar-print-ethiopic-date
+ − 755 @item p e
+ − 756 Display Ethiopic date for selected day
+ − 757 (@code{calendar-print-ethiopic-date}).
+ − 758 @findex calendar-print-persian-date
+ − 759 @item p p
+ − 760 Display Persian date for selected day
+ − 761 (@code{calendar-print-persian-date}).
+ − 762 @findex calendar-print-mayan-date
+ − 763 @item p m
+ − 764 Display Mayan date for selected day (@code{calendar-print-mayan-date}).
+ − 765 @end table
+ − 766
+ − 767 If you are using X, the easiest way to translate a date into other
+ − 768 calendars is to click on it with @kbd{Button2}, then choose @kbd{Other
+ − 769 Calendars} from the menu that appears. This displays the equivalent
+ − 770 forms of the date in all the calendars Emacs understands, in the form of
+ − 771 a menu. (Choosing an alternative from this menu doesn't actually do
+ − 772 anything---the menu is used only for display.)
+ − 773
+ − 774 Put point on the desired date of the Gregorian calendar, then type the
+ − 775 appropriate keys. The @kbd{p} is a mnemonic for ``print'' since Emacs
+ − 776 ``prints'' the equivalent date in the echo area.
+ − 777
+ − 778 @node From Other Calendar, Mayan Calendar, To Other Calendar, Other Calendars
+ − 779 @section Converting From Other Calendars
+ − 780
+ − 781 You can use the other supported calendars to specify a date to move
+ − 782 to. This section describes the commands for doing this using calendars
+ − 783 other than Mayan; for the Mayan calendar, see the following section.
+ − 784
+ − 785 @kindex g @var{char} @r{(Calendar mode)}
+ − 786 @findex calendar-goto-iso-date
+ − 787 @findex calendar-goto-julian-date
+ − 788 @findex calendar-goto-astro-day-number
+ − 789 @findex calendar-goto-hebrew-date
+ − 790 @findex calendar-goto-islamic-date
+ − 791 @findex calendar-goto-french-date
+ − 792 @findex calendar-goto-chinese-date
+ − 793 @findex calendar-goto-persian-date
+ − 794 @findex calendar-goto-coptic-date
+ − 795 @findex calendar-goto-ethiopic-date
+ − 796 @table @kbd
+ − 797 @item g c
+ − 798 Move to a date specified in the ISO commercial calendar
+ − 799 (@code{calendar-goto-iso-date}).
+ − 800 @item g j
+ − 801 Move to a date specified in the Julian calendar
+ − 802 (@code{calendar-goto-julian-date}).
+ − 803 @item g a
+ − 804 Move to a date specified in astronomical (Julian) day number
+ − 805 (@code{calendar-goto-astro-day-number}).
+ − 806 @item g h
+ − 807 Move to a date specified in the Hebrew calendar
+ − 808 (@code{calendar-goto-hebrew-date}).
+ − 809 @item g i
+ − 810 Move to a date specified in the Islamic calendar
+ − 811 (@code{calendar-goto-islamic-date}).
+ − 812 @item g f
+ − 813 Move to a date specified in the French Revolutionary calendar
+ − 814 (@code{calendar-goto-french-date}).
+ − 815 @item g C
+ − 816 Move to a date specified in the Chinese calendar
+ − 817 (@code{calendar-goto-chinese-date}).
+ − 818 @item g p
+ − 819 Move to a date specified in the Persian calendar
+ − 820 (@code{calendar-goto-persian-date}).
+ − 821 @item g k
+ − 822 Move to a date specified in the Coptic calendar
+ − 823 (@code{calendar-goto-coptic-date}).
+ − 824 @item g e
+ − 825 Move to a date specified in the Ethiopic calendar
+ − 826 (@code{calendar-goto-ethiopic-date}).
+ − 827 @end table
+ − 828
+ − 829 These commands ask you for a date on the other calendar, move point to
+ − 830 the Gregorian calendar date equivalent to that date, and display the
+ − 831 other calendar's date in the echo area. Emacs uses strict completion
+ − 832 (@pxref{Completion}) whenever it asks you to type a month name, so you
+ − 833 don't have to worry about the spelling of Hebrew, Islamic, or French names.
+ − 834
+ − 835 @findex list-yahrzeit-dates
+ − 836 @cindex yahrzeits
+ − 837 One common question concerning the Hebrew calendar is the computation
+ − 838 of the anniversary of a date of death, called a ``yahrzeit.'' The Emacs
+ − 839 calendar includes a facility for such calculations. If you are in the
+ − 840 calendar, the command @kbd{M-x list-yahrzeit-dates} asks you for a
+ − 841 range of years and then displays a list of the yahrzeit dates for those
+ − 842 years for the date given by point. If you are not in the calendar,
+ − 843 this command first asks you for the date of death and the range of
+ − 844 years, and then displays the list of yahrzeit dates.
+ − 845
+ − 846 @node Mayan Calendar, Diary ,From Other Calendar ,Other Calendars
+ − 847 @subsection Converting from the Mayan Calendar
+ − 848
+ − 849 Here are the commands to select dates based on the Mayan calendar:
+ − 850
+ − 851 @table @kbd
+ − 852 @item g m l
+ − 853 Move to a date specified by the long count calendar
+ − 854 (@code{calendar-goto-mayan-long-count-date}).
+ − 855 @item g m n t
+ − 856 Move to the next occurrence of a place in the
+ − 857 tzolkin calendar (@code{calendar-next-tzolkin-date}).
+ − 858 @item g m p t
+ − 859 Move to the previous occurrence of a place in the
+ − 860 tzolkin calendar (@code{calendar-previous-tzolkin-date}).
+ − 861 @item g m n h
+ − 862 Move to the next occurrence of a place in the
+ − 863 haab calendar (@code{calendar-next-haab-date}).
+ − 864 @item g m p h
+ − 865 Move to the previous occurrence of a place in the
+ − 866 haab calendar (@code{calendar-previous-haab-date}).
+ − 867 @item g m n c
+ − 868 Move to the next occurrence of a place in the
+ − 869 calendar round (@code{calendar-next-calendar-round-date}).
+ − 870 @item g m p c
+ − 871 Move to the previous occurrence of a place in the
+ − 872 calendar round (@code{calendar-previous-calendar-round-date}).
+ − 873 @end table
+ − 874
+ − 875 @cindex Mayan long count
+ − 876 To understand these commands, you need to understand the Mayan calendars.
+ − 877 The @dfn{long count} is a counting of days with these units:
+ − 878
+ − 879 @display
+ − 880 1 kin = 1 day@ @ @ 1 uinal = 20 kin@ @ @ 1 tun = 18 uinal
+ − 881 1 katun = 20 tun@ @ @ 1 baktun = 20 katun
+ − 882 @end display
+ − 883
+ − 884 @kindex g m l @r{(Calendar mode)}
+ − 885 @findex calendar-goto-mayan-long-count-date
+ − 886 @noindent
+ − 887 Thus, the long count date 12.16.11.16.6 means 12 baktun, 16 katun, 11
+ − 888 tun, 16 uinal, and 6 kin. The Emacs calendar can handle Mayan long
+ − 889 count dates as early as 7.17.18.13.1, but no earlier. When you use the
+ − 890 @kbd{g m l} command, type the Mayan long count date with the baktun,
+ − 891 katun, tun, uinal, and kin separated by periods.
+ − 892
+ − 893 @findex calendar-previous-tzolkin-date
+ − 894 @findex calendar-next-tzolkin-date
+ − 895 @cindex Mayan tzolkin calendar
+ − 896 The Mayan tzolkin calendar is a cycle of 260 days formed by a pair of
+ − 897 independent cycles of 13 and 20 days. Since this cycle repeats
+ − 898 endlessly, Emacs provides commands to move backward and forward to the
+ − 899 previous or next point in the cycle. Type @kbd{g m p t} to go to the
+ − 900 previous tzolkin date; Emacs asks you for a tzolkin date and moves point
+ − 901 to the previous occurrence of that date. Similarly, type @kbd{g m n t}
+ − 902 to go to the next occurrence of a tzolkin date.
+ − 903
+ − 904 @findex calendar-previous-haab-date
+ − 905 @findex calendar-next-haab-date
+ − 906 @cindex Mayan haab calendar
+ − 907 The Mayan haab calendar is a cycle of 365 days arranged as 18 months
+ − 908 of 20 days each, followed a 5-day monthless period. Like the tzolkin
+ − 909 cycle, this cycle repeats endlessly, and there are commands to move
+ − 910 backward and forward to the previous or next point in the cycle. Type
+ − 911 @kbd{g m p h} to go to the previous haab date; Emacs asks you for a haab
+ − 912 date and moves point to the previous occurrence of that date.
+ − 913 Similarly, type @kbd{g m n h} to go to the next occurrence of a haab
+ − 914 date.
+ − 915
+ − 916 @c This is omitted because it is too long for smallbook format.
+ − 917 @c @findex calendar-previous-calendar-round-date
+ − 918 @findex calendar-next-calendar-round-date
+ − 919 @cindex Mayan calendar round
+ − 920 The Maya also used the combination of the tzolkin date and the haab
+ − 921 date. This combination is a cycle of about 52 years called a
+ − 922 @emph{calendar round}. If you type @kbd{g m p c}, Emacs asks you for
+ − 923 both a haab and a tzolkin date and then moves point to the previous
+ − 924 occurrence of that combination. Use @kbd{g m n c} to move point to the
+ − 925 next occurrence of a combination. These commands signal an error if the
+ − 926 haab/tzolkin date combination you have typed is impossible.
+ − 927
+ − 928 Emacs uses strict completion (@pxref{Completion}) whenever it
+ − 929 asks you to type a Mayan name, so you don't have to worry about
+ − 930 spelling.
+ − 931
+ − 932 @node Diary, Calendar Customization, Mayan Calendar, Calendar/Diary
+ − 933 @subsection The Diary
+ − 934 @cindex diary
+ − 935
+ − 936 The Emacs diary keeps track of appointments or other events on a daily
+ − 937 basis, in conjunction with the calendar. To use the diary feature, you
+ − 938 must first create a @dfn{diary file} containing a list of events and
+ − 939 their dates. Then Emacs can automatically pick out and display the
+ − 940 events for today, for the immediate future, or for any specified
+ − 941 date.
+ − 942
+ − 943 By default, Emacs uses @file{~/diary} as the diary file. This is the
+ − 944 same file that the @code{calendar} utility uses. A sample
+ − 945 @file{~/diary} file is:
+ − 946
+ − 947 @example
+ − 948 12/22/1988 Twentieth wedding anniversary!!
+ − 949 &1/1. Happy New Year!
+ − 950 10/22 Ruth's birthday.
+ − 951 * 21, *: Payday
+ − 952 Tuesday--weekly meeting with grad students at 10am
+ − 953 Supowit, Shen, Bitner, and Kapoor to attend.
+ − 954 1/13/89 Friday the thirteenth!!
+ − 955 &thu 4pm squash game with Lloyd.
+ − 956 mar 16 Dad's birthday
+ − 957 April 15, 1989 Income tax due.
+ − 958 &* 15 time cards due.
+ − 959 @end example
+ − 960
+ − 961 @noindent
+ − 962 This example uses extra spaces to align the event descriptions of most
+ − 963 of the entries. Such formatting is purely a matter of taste.
+ − 964
+ − 965 Although you probably will start by creating a diary manually, Emacs
+ − 966 provides a number of commands to let you view, add, and change diary
+ − 967 entries. You can also share diary entries with other users
+ − 968 (@pxref{Included Diary Files}).
+ − 969
+ − 970 @menu
+ − 971 * Diary Commands:: Viewing diary entries and associated calendar dates.
+ − 972 * Format of Diary File:: Entering events in your diary.
+ − 973 * Date Formats:: Various ways you can specify dates.
+ − 974 * Adding to Diary:: Commands to create diary entries.
+ − 975 * Special Diary Entries:: Anniversaries, blocks of dates, cyclic entries, etc.
+ − 976 @end menu
+ − 977
+ − 978 @node Diary Commands, Format of Diary File, Diary, Diary
+ − 979 @subsection Commands Displaying Diary Entries
+ − 980
+ − 981 Once you have created a @file{~/diary} file, you can use the calendar
+ − 982 to view it. You can also view today's events outside of Calendar mode.
+ − 983
+ − 984 @table @kbd
+ − 985 @item d
+ − 986 Display all diary entries for the selected date
+ − 987 (@code{view-diary-entries}).
+ − 988 @item Button2 Diary
+ − 989 Display all diary entries for the date you click on.
+ − 990 @item s
+ − 991 Display the entire diary file (@code{show-all-diary-entries}).
+ − 992 @item m
+ − 993 Mark all visible dates that have diary entries
+ − 994 (@code{mark-diary-entries}).
+ − 995 @item u
+ − 996 Unmark the calendar window (@code{calendar-unmark}).
+ − 997 @item M-x print-diary-entries
+ − 998 Print hard copy of the diary display as it appears.
+ − 999 @item M-x diary
+ − 1000 Display all diary entries for today's date.
+ − 1001 @item M-x diary-mail-entries
+ − 1002 Mail yourself email reminders about upcoming diary entries.
+ − 1003 @end table
+ − 1004
+ − 1005 @kindex d @r{(Calendar mode)}
+ − 1006 @findex view-diary-entries
+ − 1007 Displaying the diary entries with @kbd{d} shows in a separate window
+ − 1008 the diary entries for the selected date in the calendar. The mode line
+ − 1009 of the new window shows the date of the diary entries and any holidays
+ − 1010 that fall on that date. If you specify a numeric argument with @kbd{d},
+ − 1011 it shows all the diary entries for that many successive days. Thus,
+ − 1012 @kbd{2 d} displays all the entries for the selected date and for the
+ − 1013 following day.
+ − 1014
+ − 1015 Another way to display the diary entries for a date is to click
+ − 1016 @kbd{Button2} on the date, and then choose @kbd{Diary} from the menu
+ − 1017 that appears.
+ − 1018
+ − 1019 @kindex m @r{(Calendar mode)}
+ − 1020 @findex mark-diary-entries
+ − 1021 @kindex u @r{(Calendar mode)}
+ − 1022 @findex calendar-unmark
+ − 1023 To get a broader view of which days are mentioned in the diary, use
+ − 1024 the @kbd{m} command. This displays the dates that have diary entries
+ − 1025 in a different face (or places a @samp{+} after these dates, if
+ − 1026 display with multiple faces is not available). The command applies both
+ − 1027 to the currently visible months and to other months that subsequently
+ − 1028 become visible by scrolling. To turn marking off and erase the current
+ − 1029 marks, type @kbd{u}, which also turns off holiday marks
+ − 1030 (@pxref{Holidays}).
+ − 1031
+ − 1032 @kindex s @r{(Calendar mode)}
+ − 1033 @findex show-all-diary-entries
+ − 1034 To see the full diary file, rather than just some of the entries, use
+ − 1035 the @kbd{s} command.
+ − 1036
+ − 1037 Display of selected diary entries uses the selective display feature
+ − 1038 to hide entries that don't apply.
+ − 1039
+ − 1040 @findex print-diary-entries
+ − 1041 The diary buffer as you see it is an illusion, so simply printing the
+ − 1042 buffer does not print what you see on your screen. There is a special
+ − 1043 command to print hard copy of the diary buffer @emph{as it appears};
+ − 1044 this command is @kbd{M-x print-diary-entries}. It sends the data
+ − 1045 directly to the printer. You can customize it like @code{lpr-region}
+ − 1046 (@pxref{Hardcopy}).
+ − 1047
+ − 1048 @findex diary
+ − 1049 The command @kbd{M-x diary} displays the diary entries for the current
+ − 1050 date, independently of the calendar display, and optionally for the next
+ − 1051 few days as well; the variable @code{number-of-diary-entries} specifies
+ − 1052 how many days to include (@pxref{Customization}).
+ − 1053
442
+ − 1054 If you put @code{(diary)} in your init file, this
428
+ − 1055 automatically displays a window with the day's diary entries, when you
442
+ − 1056 enter Emacs. @xref{Init File}. The mode line of the displayed window
+ − 1057 shows the date and any holidays that fall on that date.
428
+ − 1058
+ − 1059 @findex diary-mail-entries
+ − 1060 @vindex diary-mail-days
+ − 1061 Many users like to receive notice of events in their diary as email.
+ − 1062 To send such mail to yourself, use the command @kbd{M-x
+ − 1063 diary-mail-entries}. A prefix argument specifies how many days
+ − 1064 (starting with today) to check; otherwise, the variable
+ − 1065 @code{diary-mail-days} says how many days.
+ − 1066
+ − 1067 @node Format of Diary File, Date Formats, Diary Commands, Diary
+ − 1068 @subsection The Diary File
+ − 1069 @cindex diary file
+ − 1070
+ − 1071 @vindex diary-file
+ − 1072 Your @dfn{diary file} is a file that records events associated with
+ − 1073 particular dates. The name of the diary file is specified by the
+ − 1074 variable @code{diary-file}; @file{~/diary} is the default. The
+ − 1075 @code{calendar} utility program supports a subset of the format allowed
+ − 1076 by the Emacs diary facilities, so you can use that utility to view the
+ − 1077 diary file, with reasonable results aside from the entries it cannot
+ − 1078 understand.
+ − 1079
+ − 1080 Each entry in the diary file describes one event and consists of one
+ − 1081 or more lines. An entry always begins with a date specification at the
+ − 1082 left margin. The rest of the entry is simply text to describe the
+ − 1083 event. If the entry has more than one line, then the lines after the
+ − 1084 first must begin with whitespace to indicate they continue a previous
+ − 1085 entry. Lines that do not begin with valid dates and do not continue a
+ − 1086 preceding entry are ignored.
+ − 1087
+ − 1088 You can inhibit the marking of certain diary entries in the calendar
+ − 1089 window; to do this, insert an ampersand (@samp{&}) at the beginning of
+ − 1090 the entry, before the date. This has no effect on display of the entry
+ − 1091 in the diary window; it affects only marks on dates in the calendar
+ − 1092 window. Nonmarking entries are especially useful for generic entries
+ − 1093 that would otherwise mark many different dates.
+ − 1094
+ − 1095 If the first line of a diary entry consists only of the date or day
+ − 1096 name with no following blanks or punctuation, then the diary window
+ − 1097 display doesn't include that line; only the continuation lines appear.
+ − 1098 For example, this entry:
+ − 1099
+ − 1100 @example
+ − 1101 02/11/1989
+ − 1102 Bill B. visits Princeton today
+ − 1103 2pm Cognitive Studies Committee meeting
+ − 1104 2:30-5:30 Liz at Lawrenceville
+ − 1105 4:00pm Dentist appt
+ − 1106 7:30pm Dinner at George's
+ − 1107 8:00-10:00pm concert
+ − 1108 @end example
+ − 1109
+ − 1110 @noindent
+ − 1111 appears in the diary window without the date line at the beginning.
+ − 1112 This style of entry looks neater when you display just a single day's
+ − 1113 entries, but can cause confusion if you ask for more than one day's
+ − 1114 entries.
+ − 1115
+ − 1116 You can edit the diary entries as they appear in the window, but it is
+ − 1117 important to remember that the buffer displayed contains the @emph{entire}
+ − 1118 diary file, with portions of it concealed from view. This means, for
+ − 1119 instance, that the @kbd{C-f} (@code{forward-char}) command can put point
+ − 1120 at what appears to be the end of the line, but what is in reality the
+ − 1121 middle of some concealed line.
+ − 1122
+ − 1123 @emph{Be careful when editing the diary entries!} Inserting
+ − 1124 additional lines or adding/deleting characters in the middle of a
+ − 1125 visible line cannot cause problems, but editing at the end of a line may
+ − 1126 not do what you expect. Deleting a line may delete other invisible
+ − 1127 entries that follow it. Before editing the diary, it is best to display
+ − 1128 the entire file with @kbd{s} (@code{show-all-diary-entries}).
+ − 1129
+ − 1130 @node Date Formats,Adding to Diary ,Format of Diary File, Diary
+ − 1131 @subsection Date Formats
+ − 1132
+ − 1133 Here are some sample diary entries, illustrating different ways of
+ − 1134 formatting a date. The examples all show dates in American order
+ − 1135 (month, day, year), but Calendar mode supports European order (day,
+ − 1136 month, year) as an option.
+ − 1137
+ − 1138 @example
+ − 1139 4/20/93 Switch-over to new tabulation system
+ − 1140 apr. 25 Start tabulating annual results
+ − 1141 4/30 Results for April are due
+ − 1142 */25 Monthly cycle finishes
+ − 1143 Friday Don't leave without backing up files
+ − 1144 @end example
+ − 1145
+ − 1146 The first entry appears only once, on April 20, 1993. The second and
+ − 1147 third appear every year on the specified dates, and the fourth uses a
+ − 1148 wildcard (asterisk) for the month, so it appears on the 25th of every
+ − 1149 month. The final entry appears every week on Friday.
+ − 1150
+ − 1151 You can use just numbers to express a date, as in
+ − 1152 @samp{@var{month}/@var{day}} or @samp{@var{month}/@var{day}/@var{year}}.
+ − 1153 This must be followed by a nondigit. In the date itself, @var{month}
+ − 1154 and @var{day} are numbers of one or two digits. The optional @var{year}
+ − 1155 is also a number, and may be abbreviated to the last two digits; that
+ − 1156 is, you can use @samp{11/12/1989} or @samp{11/12/89}.
+ − 1157
+ − 1158 Dates can also have the form @samp{@var{monthname} @var{day}} or
+ − 1159 @samp{@var{monthname} @var{day}, @var{year}}, where the month's name can
+ − 1160 be spelled in full or abbreviated to three characters (with or without a
+ − 1161 period). Case is not significant.
+ − 1162
+ − 1163 A date may be @dfn{generic}; that is, partially unspecified. Then the
+ − 1164 entry applies to all dates that match the specification. If the date
+ − 1165 does not contain a year, it is generic and applies to any year.
+ − 1166 Alternatively, @var{month}, @var{day}, or @var{year} can be a @samp{*};
+ − 1167 this matches any month, day, or year, respectively. Thus, a diary entry
+ − 1168 @samp{3/*/*} matches any day in March of any year; so does @samp{march
+ − 1169 *}.
+ − 1170
+ − 1171 @vindex european-calendar-style
+ − 1172 @findex european-calendar
+ − 1173 @findex american-calendar
+ − 1174 If you prefer the European style of writing dates---in which the day
+ − 1175 comes before the month---type @kbd{M-x european-calendar} while in the
+ − 1176 calendar, or set the variable @code{european-calendar-style} to @code{t}
+ − 1177 @emph{before} using any calendar or diary command. This mode interprets
+ − 1178 all dates in the diary in the European manner, and also uses European
+ − 1179 style for displaying diary dates. (Note that there is no comma after
+ − 1180 the @var{monthname} in the European style.) To go back to the (default)
+ − 1181 American style of writing dates, type @kbd{M-x american-calendar}.
+ − 1182
+ − 1183 You can use the name of a day of the week as a generic date which
+ − 1184 applies to any date falling on that day of the week. You can abbreviate
+ − 1185 the day of the week to three letters (with or without a period) or spell
+ − 1186 it in full; case is not significant.
+ − 1187
+ − 1188 @node Adding to Diary, Special Diary Entries, Date Formats, Diary
+ − 1189 @subsection Commands to Add to the Diary
+ − 1190
+ − 1191 While in the calendar, there are several commands to create diary
+ − 1192 entries:
+ − 1193
+ − 1194 @table @kbd
+ − 1195 @item i d
+ − 1196 Add a diary entry for the selected date (@code{insert-diary-entry}).
+ − 1197 @item i w
+ − 1198 Add a diary entry for the selected day of the week (@code{insert-weekly-diary-entry}).
+ − 1199 @item i m
+ − 1200 Add a diary entry for the selected day of the month (@code{insert-monthly-diary-entry}).
+ − 1201 @item i y
+ − 1202 Add a diary entry for the selected day of the year (@code{insert-yearly-diary-entry}).
+ − 1203 @end table
+ − 1204
+ − 1205 @kindex i d @r{(Calendar mode)}
+ − 1206 @findex insert-diary-entry
+ − 1207 You can make a diary entry for a specific date by selecting that date
+ − 1208 in the calendar window and typing the @kbd{i d} command. This command
+ − 1209 displays the end of your diary file in another window and inserts the
+ − 1210 date; you can then type the rest of the diary entry.
+ − 1211
+ − 1212 @kindex i w @r{(Calendar mode)}
+ − 1213 @findex insert-weekly-diary-entry
+ − 1214 @kindex i m @r{(Calendar mode)}
+ − 1215 @findex insert-monthly-diary-entry
+ − 1216 @kindex i y @r{(Calendar mode)}
+ − 1217 @findex insert-yearly-diary-entry
+ − 1218 If you want to make a diary entry that applies to a specific day of
+ − 1219 the week, select that day of the week (any occurrence will do) and type
+ − 1220 @kbd{i w}. This inserts the day-of-week as a generic date; you can then
+ − 1221 type the rest of the diary entry. You can make a monthly diary entry in
+ − 1222 the same fashion. Select the day of the month, use the @kbd{i m}
+ − 1223 command, and type rest of the entry. Similarly, you can insert a yearly
+ − 1224 diary entry with the @kbd{i y} command.
+ − 1225
+ − 1226 All of the above commands make marking diary entries by default. To
+ − 1227 make a nonmarking diary entry, give a numeric argument to the command.
+ − 1228 For example, @kbd{C-u i w} makes a nonmarking weekly diary entry.
+ − 1229
+ − 1230 When you modify the diary file, be sure to save the file before
+ − 1231 exiting Emacs.
+ − 1232
+ − 1233 @node Special Diary Entries,, Adding to Diary, Diary
+ − 1234 @subsection Special Diary Entries
+ − 1235
+ − 1236 In addition to entries based on calendar dates, the diary file can
+ − 1237 contain @dfn{sexp entries} for regular events such as anniversaries.
+ − 1238 These entries are based on Lisp expressions (sexps) that Emacs evaluates
+ − 1239 as it scans the diary file. Instead of a date, a sexp entry contains
+ − 1240 @samp{%%} followed by a Lisp expression which must begin and end with
+ − 1241 parentheses. The Lisp expression determines which dates the entry
+ − 1242 applies to.
+ − 1243
+ − 1244 Calendar mode provides commands to insert certain commonly used
+ − 1245 sexp entries:
+ − 1246
+ − 1247 @table @kbd
+ − 1248 @item i a
+ − 1249 Add an anniversary diary entry for the selected date
+ − 1250 (@code{insert-anniversary-diary-entry}).
+ − 1251 @item i b
+ − 1252 Add a block diary entry for the current region
+ − 1253 (@code{insert-block-diary-entry}).
+ − 1254 @item i c
+ − 1255 Add a cyclic diary entry starting at the date
+ − 1256 (@code{insert-cyclic-diary-entry}).
+ − 1257 @end table
+ − 1258
+ − 1259 @kindex i a @r{(Calendar mode)}
+ − 1260 @findex insert-anniversary-diary-entry
+ − 1261 If you want to make a diary entry that applies to the anniversary of a
+ − 1262 specific date, move point to that date and use the @kbd{i a} command.
+ − 1263 This displays the end of your diary file in another window and inserts
+ − 1264 the anniversary description; you can then type the rest of the diary
+ − 1265 entry. The entry looks like this:
+ − 1266
+ − 1267 @findex diary-anniversary
+ − 1268 The effect of @kbd{i a} is to add a @code{diary-anniversary} sexp to your
+ − 1269 diary file. You can also add one manually, for instance:
+ − 1270
+ − 1271 @example
+ − 1272 %%(diary-anniversary 10 31 1948) Arthur's birthday
+ − 1273 @end example
+ − 1274
+ − 1275 @noindent
+ − 1276 This entry applies to October 31 in any year after 1948; @samp{10 31
+ − 1277 1948} specifies the date. (If you are using the European calendar
+ − 1278 style, the month and day are interchanged.) The reason this expression
+ − 1279 requires a beginning year is that advanced diary functions can use it to
+ − 1280 calculate the number of elapsed years.
+ − 1281
+ − 1282 A @dfn{block} diary entry applies to a specified range of consecutive
+ − 1283 dates. Here is a block diary entry that applies to all dates from June
+ − 1284 24, 1990 through July 10, 1990:
+ − 1285
+ − 1286 @findex diary-block
+ − 1287 @example
+ − 1288 %%(diary-block 6 24 1990 7 10 1990) Vacation
+ − 1289 @end example
+ − 1290
+ − 1291 @noindent
+ − 1292 The @samp{6 24 1990} indicates the starting date and the @samp{7 10 1990}
+ − 1293 indicates the stopping date. (Again, if you are using the European calendar
+ − 1294 style, the month and day are interchanged.)
+ − 1295
+ − 1296 @kindex i b @r{(Calendar mode)}
+ − 1297 @findex insert-block-diary-entry
+ − 1298 To insert a block entry, place point and the mark on the two
+ − 1299 dates that begin and end the range, and type @kbd{i b}. This command
+ − 1300 displays the end of your diary file in another window and inserts the
+ − 1301 block description; you can then type the diary entry.
+ − 1302
+ − 1303 @kindex i c @r{(Calendar mode)}
+ − 1304 @findex insert-cyclic-diary-entry
+ − 1305 @dfn{Cyclic} diary entries repeat after a fixed interval of days. To
+ − 1306 create one, select the starting date and use the @kbd{i c} command. The
+ − 1307 command prompts for the length of interval, then inserts the entry,
+ − 1308 which looks like this:
+ − 1309
+ − 1310 @findex diary-cyclic
+ − 1311 @example
+ − 1312 %%(diary-cyclic 50 3 1 1990) Renew medication
+ − 1313 @end example
+ − 1314
+ − 1315 @noindent
+ − 1316 This entry applies to March 1, 1990 and every 50th day following;
+ − 1317 @samp{3 1 1990} specifies the starting date. (If you are using the
+ − 1318 European calendar style, the month and day are interchanged.)
+ − 1319
+ − 1320 All three of these commands make marking diary entries. To insert a
+ − 1321 nonmarking entry, give a numeric argument to the command. For example,
+ − 1322 @kbd{C-u i a} makes a nonmarking anniversary diary entry.
+ − 1323
+ − 1324 Marking sexp diary entries in the calendar is @emph{extremely}
+ − 1325 time-consuming, since every date visible in the calendar window must be
+ − 1326 individually checked. So it's a good idea to make sexp diary entries
+ − 1327 nonmarking (with @samp{&}) when possible.
+ − 1328
+ − 1329 Another sophisticated kind of sexp entry, a @dfn{floating} diary entry,
+ − 1330 specifies a regularly occurring event by offsets specified in days,
+ − 1331 weeks, and months. It is comparable to a crontab entry interpreted by
+ − 1332 the @code{cron} utility. Here is a nonmarking, floating diary entry
+ − 1333 that applies to the last Thursday in November:
+ − 1334
+ − 1335 @findex diary-float
+ − 1336 @example
+ − 1337 &%%(diary-float 11 4 -1) American Thanksgiving
+ − 1338 @end example
+ − 1339
+ − 1340 @noindent
+ − 1341 The 11 specifies November (the eleventh month), the 4 specifies Thursday
+ − 1342 (the fourth day of the week, where Sunday is numbered zero), and the
+ − 1343 @minus{}1 specifies ``last'' (1 would mean ``first'', 2 would mean
+ − 1344 ``second'', @minus{}2 would mean ``second-to-last'', and so on). The
+ − 1345 month can be a single month or a list of months. Thus you could change
+ − 1346 the 11 above to @samp{'(1 2 3)} and have the entry apply to the last
+ − 1347 Thursday of January, February, and March. If the month is @code{t}, the
+ − 1348 entry applies to all months of the year.@refill
+ − 1349
+ − 1350 The sexp feature of the diary allows you to specify diary entries
+ − 1351 based on any Emacs Lisp expression. You can use the library of built-in
+ − 1352 functions or you can write your own functions. The built-in functions
+ − 1353 include the ones shown in this section, plus a few others (@pxref{Sexp
+ − 1354 Diary Entries}).
+ − 1355
+ − 1356 The generality of sexps lets you specify any diary entry that you can
+ − 1357 describe algorithmically. Suppose you get paid on the 21st of the month
+ − 1358 if it is a weekday, and to the Friday before if the 21st is on a
+ − 1359 weekend. The diary entry
+ − 1360
+ − 1361 @example
+ − 1362 &%%(let ((dayname (calendar-day-of-week date))
+ − 1363 (day (car (cdr date))))
+ − 1364 (or (and (= day 21) (memq dayname '(1 2 3 4 5)))
+ − 1365 (and (memq day '(19 20)) (= dayname 5)))
+ − 1366 ) Pay check deposited
+ − 1367 @end example
+ − 1368
+ − 1369 @noindent
+ − 1370 to just those dates. This example illustrates how the sexp can depend
+ − 1371 on the variable @code{date}; this variable is a list (@var{month}
+ − 1372 @var{day} @var{year}) that gives the Gregorian date for which the diary
+ − 1373 entries are being found. If the value of the sexp is @code{t}, the
+ − 1374 entry applies to that date. If the sexp evaluates to @code{nil}, the
+ − 1375 entry does @emph{not} apply to that date.
+ − 1376
+ − 1377
+ − 1378 @node Calendar Customization,,Diary, Calendar/Diary
+ − 1379 @subsection Customizing the Calendar and Diary
+ − 1380
+ − 1381 There are many customizations that you can use to make the calendar and
+ − 1382 diary suit your personal tastes.
+ − 1383
+ − 1384 @menu
+ − 1385 * Calendar Customizing:: Defaults you can set.
+ − 1386 * Holiday Customizing:: Defining your own holidays.
+ − 1387 * Date Display Format:: Changing the format.
+ − 1388 * Time Display Format:: Changing the format.
+ − 1389 * Daylight Savings:: Changing the default.
+ − 1390 * Diary Customizing:: Defaults you can set.
+ − 1391 * Hebrew/Islamic Entries:: How to obtain them.
+ − 1392 * Fancy Diary Display:: Enhancing the diary display, sorting entries.
+ − 1393 * Included Diary Files:: Sharing a common diary file.
+ − 1394 * Sexp Diary Entries:: Fancy things you can do.
+ − 1395 * Appt Customizing:: Customizing appointment reminders.
+ − 1396 @end menu
+ − 1397
+ − 1398 @node Calendar Customizing
+ − 1399 @subsubsection Customizing the Calendar
+ − 1400 @vindex view-diary-entries-initially
+ − 1401
+ − 1402 If you set the variable @code{view-diary-entries-initially} to
+ − 1403 @code{t}, calling up the calendar automatically displays the diary
+ − 1404 entries for the current date as well. The diary dates appear only if
+ − 1405 the current date is visible. If you add both of the following lines to
442
+ − 1406 your init file:@refill
428
+ − 1407
+ − 1408 @example
+ − 1409 (setq view-diary-entries-initially t)
+ − 1410 (calendar)
+ − 1411 @end example
+ − 1412
+ − 1413 @noindent
442
+ − 1414 this displays both the calendar and diary windows whenever you start
+ − 1415 Emacs. @xref{Init File}.
428
+ − 1416
+ − 1417 @vindex view-calendar-holidays-initially
+ − 1418 Similarly, if you set the variable
+ − 1419 @code{view-calendar-holidays-initially} to @code{t}, entering the
+ − 1420 calendar automatically displays a list of holidays for the current
+ − 1421 three-month period. The holiday list appears in a separate
+ − 1422 window.
+ − 1423
+ − 1424 @vindex mark-diary-entries-in-calendar
+ − 1425 You can set the variable @code{mark-diary-entries-in-calendar} to
+ − 1426 @code{t} in order to mark any dates with diary entries. This takes
+ − 1427 effect whenever the calendar window contents are recomputed. There are
+ − 1428 two ways of marking these dates: by changing the face (@pxref{Faces}),
+ − 1429 if the display supports that, or by placing a plus sign (@samp{+})
+ − 1430 beside the date otherwise.
+ − 1431
+ − 1432 @vindex mark-holidays-in-calendar
+ − 1433 Similarly, setting the variable @code{mark-holidays-in-calendar} to
+ − 1434 @code{t} marks holiday dates, either with a change of face or with an
+ − 1435 asterisk (@samp{*}).
+ − 1436
+ − 1437 @vindex calendar-holiday-marker
+ − 1438 @vindex diary-entry-marker
+ − 1439 The variable @code{calendar-holiday-marker} specifies how to mark a
+ − 1440 date as being a holiday. Its value may be a character to insert next to
+ − 1441 the date, or a face name to use for displaying the date. Likewise, the
+ − 1442 variable @code{diary-entry-marker} specifies how to mark a date that has
+ − 1443 diary entries. The calendar creates faces named @code{holiday-face} and
+ − 1444 @code{diary-face} for these purposes; those symbols are the default
+ − 1445 values of these variables, when Emacs supports multiple faces on your
+ − 1446 terminal.
+ − 1447
+ − 1448 @vindex calendar-load-hook
+ − 1449 The variable @code{calendar-load-hook} is a normal hook run when the
+ − 1450 calendar package is first loaded (before actually starting to display
+ − 1451 the calendar).
+ − 1452
+ − 1453 @vindex initial-calendar-window-hook
+ − 1454 Starting the calendar runs the normal hook
+ − 1455 @code{initial-calendar-window-hook}. Recomputation of the calendar
+ − 1456 display does not run this hook. But if you leave the calendar with the
+ − 1457 @kbd{q} command and reenter it, the hook runs again.@refill
+ − 1458
+ − 1459 @vindex today-visible-calendar-hook
+ − 1460 The variable @code{today-visible-calendar-hook} is a normal hook run
+ − 1461 after the calendar buffer has been prepared with the calendar when the
+ − 1462 current date is visible in the window. One use of this hook is to
+ − 1463 replace today's date with asterisks; to do that, use the hook function
+ − 1464 @code{calendar-star-date}.
+ − 1465
+ − 1466 @findex calendar-star-date
+ − 1467 @example
+ − 1468 (add-hook 'today-visible-calendar-hook 'calendar-star-date)
+ − 1469 @end example
+ − 1470
+ − 1471 @noindent
+ − 1472 Another standard hook function marks the current date, either by
+ − 1473 changing its face or by adding an asterisk. Here's how to use it:
+ − 1474
+ − 1475 @findex calendar-mark-today
+ − 1476 @example
+ − 1477 (add-hook 'today-visible-calendar-hook 'calendar-mark-today)
+ − 1478 @end example
+ − 1479
+ − 1480 @noindent
+ − 1481 @vindex calendar-today-marker
+ − 1482 The variable @code{calendar-today-marker} specifies how to mark today's
+ − 1483 date. Its value should be a character to insert next to the date or a
+ − 1484 face name to use for displaying the date. A face named
+ − 1485 @code{calendar-today-face} is provided for this purpose; that symbol is
+ − 1486 the default for this variable when Emacs supports multiple faces on your
+ − 1487 terminal.
+ − 1488
+ − 1489 @vindex today-invisible-calendar-hook
+ − 1490 @noindent
+ − 1491 A similar normal hook, @code{today-invisible-calendar-hook} is run if
+ − 1492 the current date is @emph{not} visible in the window.
+ − 1493
+ − 1494 @node Holiday Customizing
+ − 1495 @subsubsection Customizing the Holidays
+ − 1496
+ − 1497 @vindex calendar-holidays
+ − 1498 @vindex christian-holidays
+ − 1499 @vindex hebrew-holidays
+ − 1500 @vindex islamic-holidays
+ − 1501 Emacs knows about holidays defined by entries on one of several lists.
+ − 1502 You can customize these lists of holidays to your own needs, adding or
+ − 1503 deleting holidays. The lists of holidays that Emacs uses are for
+ − 1504 general holidays (@code{general-holidays}), local holidays
+ − 1505 (@code{local-holidays}), Christian holidays (@code{christian-holidays}),
+ − 1506 Hebrew (Jewish) holidays (@code{hebrew-holidays}), Islamic (Moslem)
+ − 1507 holidays (@code{islamic-holidays}), and other holidays
+ − 1508 (@code{other-holidays}).
+ − 1509
+ − 1510 @vindex general-holidays
+ − 1511 The general holidays are, by default, holidays common throughout the
+ − 1512 United States. To eliminate these holidays, set @code{general-holidays}
+ − 1513 to @code{nil}.
+ − 1514
+ − 1515 @vindex local-holidays
+ − 1516 There are no default local holidays (but sites may supply some). You
+ − 1517 can set the variable @code{local-holidays} to any list of holidays, as
+ − 1518 described below.
+ − 1519
+ − 1520 @vindex all-christian-calendar-holidays
+ − 1521 @vindex all-hebrew-calendar-holidays
+ − 1522 @vindex all-islamic-calendar-holidays
+ − 1523 By default, Emacs does not include all the holidays of the religions
+ − 1524 that it knows, only those commonly found in secular calendars. For a
+ − 1525 more extensive collection of religious holidays, you can set any (or
+ − 1526 all) of the variables @code{all-christian-calendar-holidays},
+ − 1527 @code{all-hebrew-calendar-holidays}, or
+ − 1528 @code{all-islamic-calendar-holidays} to @code{t}. If you want to
+ − 1529 eliminate the religious holidays, set any or all of the corresponding
+ − 1530 variables @code{christian-holidays}, @code{hebrew-holidays}, and
+ − 1531 @code{islamic-holidays} to @code{nil}.@refill
+ − 1532
+ − 1533 @vindex other-holidays
+ − 1534 You can set the variable @code{other-holidays} to any list of
+ − 1535 holidays. This list, normally empty, is intended for individual use.
+ − 1536
+ − 1537 @cindex holiday forms
+ − 1538 Each of the lists (@code{general-holidays}, @code{local-holidays},
+ − 1539 @code{christian-holidays}, @code{hebrew-holidays},
+ − 1540 @code{islamic-holidays}, and @code{other-holidays}) is a list of
+ − 1541 @dfn{holiday forms}, each holiday form describing a holiday (or
+ − 1542 sometimes a list of holidays).
+ − 1543
+ − 1544 Here is a table of the possible kinds of holiday form. Day numbers
+ − 1545 and month numbers count starting from 1, but ``dayname'' numbers
+ − 1546 count Sunday as 0. The element @var{string} is always the
+ − 1547 name of the holiday, as a string.
+ − 1548
+ − 1549 @table @code
+ − 1550 @item (holiday-fixed @var{month} @var{day} @var{string})
+ − 1551 A fixed date on the Gregorian calendar. @var{month} and @var{day} are
+ − 1552 numbers, @var{string} is the name of the holiday.
+ − 1553
+ − 1554 @item (holiday-float @var{month} @var{dayname} @var{k} @var{string})
+ − 1555 The @var{k}th @var{dayname} in @var{month} on the Gregorian calendar
+ − 1556 (@var{dayname}=0 for Sunday, and so on); negative @var{k} means count back
+ − 1557 from the end of the month. @var{string} is the name of the holiday.
+ − 1558
+ − 1559 @item (holiday-hebrew @var{month} @var{day} @var{string})
+ − 1560 A fixed date on the Hebrew calendar. @var{month} and @var{day} are
+ − 1561 numbers, @var{string} is the name of the holiday.
+ − 1562
+ − 1563 @item (holiday-islamic @var{month} @var{day} @var{string})
+ − 1564 A fixed date on the Islamic calendar. @var{month} and @var{day} are
+ − 1565 numbers, @var{string} is the name of the holiday.
+ − 1566
+ − 1567 @item (holiday-julian @var{month} @var{day} @var{string})
+ − 1568 A fixed date on the Julian calendar. @var{month} and @var{day} are
+ − 1569 numbers, @var{string} is the name of the holiday.
+ − 1570
+ − 1571 @item (holiday-sexp @var{sexp} @var{string})
+ − 1572 A date calculated by the Lisp expression @var{sexp}. The expression
+ − 1573 should use the variable @code{year} to compute and return the date of a
+ − 1574 holiday, or @code{nil} if the holiday doesn't happen this year. The
+ − 1575 value of @var{sexp} must represent the date as a list of the form
+ − 1576 @code{(@var{month} @var{day} @var{year})}. @var{string} is the name of
+ − 1577 the holiday.
+ − 1578
+ − 1579 @item (if @var{condition} @var{holiday-form} &optional @var{holiday-form})
+ − 1580 A holiday that happens only if @var{condition} is true.
+ − 1581
+ − 1582 @item (@var{function} @r{[}@var{args}@r{]})
+ − 1583 A list of dates calculated by the function @var{function}, called with
+ − 1584 arguments @var{args}.
+ − 1585 @end table
+ − 1586
+ − 1587 For example, suppose you want to add Bastille Day, celebrated in
+ − 1588 France on July 14. You can do this by adding the following line
442
+ − 1589 to your init file:
428
+ − 1590
+ − 1591 @smallexample
+ − 1592 (setq other-holidays '((holiday-fixed 7 14 "Bastille Day")))
+ − 1593 @end smallexample
+ − 1594
442
+ − 1595 @xref{Init File}.
+ − 1596
428
+ − 1597 @noindent
+ − 1598 The holiday form @code{(holiday-fixed 7 14 "Bastille Day")} specifies the
+ − 1599 fourteenth day of the seventh month (July).
+ − 1600
+ − 1601 Many holidays occur on a specific day of the week, at a specific time
+ − 1602 of month. Here is a holiday form describing Hurricane Supplication Day,
+ − 1603 celebrated in the Virgin Islands on the fourth Monday in August:
+ − 1604
+ − 1605 @smallexample
+ − 1606 (holiday-float 8 1 4 "Hurricane Supplication Day")
+ − 1607 @end smallexample
+ − 1608
+ − 1609 @noindent
+ − 1610 Here the 8 specifies August, the 1 specifies Monday (Sunday is 0,
+ − 1611 Tuesday is 2, and so on), and the 4 specifies the fourth occurrence in
+ − 1612 the month (1 specifies the first occurrence, 2 the second occurrence,
+ − 1613 @minus{}1 the last occurrence, @minus{}2 the second-to-last occurrence, and
+ − 1614 so on).
+ − 1615
+ − 1616 You can specify holidays that occur on fixed days of the Hebrew,
+ − 1617 Islamic, and Julian calendars too. For example,
+ − 1618
+ − 1619 @smallexample
+ − 1620 (setq other-holidays
+ − 1621 '((holiday-hebrew 10 2 "Last day of Hanukkah")
+ − 1622 (holiday-islamic 3 12 "Mohammed's Birthday")
+ − 1623 (holiday-julian 4 2 "Jefferson's Birthday")))
+ − 1624 @end smallexample
+ − 1625
+ − 1626 @noindent
+ − 1627 adds the last day of Hanukkah (since the Hebrew months are numbered with
+ − 1628 1 starting from Nisan), the Islamic feast celebrating Mohammed's
+ − 1629 birthday (since the Islamic months are numbered from 1 starting with
+ − 1630 Muharram), and Thomas Jefferson's birthday, which is 2 April 1743 on the
+ − 1631 Julian calendar.
+ − 1632
+ − 1633 To include a holiday conditionally, use either Emacs Lisp's @code{if} or the
+ − 1634 @code{holiday-sexp} form. For example, American presidential elections
+ − 1635 occur on the first Tuesday after the first Monday in November of years
+ − 1636 divisible by 4:
+ − 1637
+ − 1638 @smallexample
+ − 1639 (holiday-sexp (if (= 0 (% year 4))
+ − 1640 (calendar-gregorian-from-absolute
+ − 1641 (1+ (calendar-dayname-on-or-before
+ − 1642 1 (+ 6 (calendar-absolute-from-gregorian
+ − 1643 (list 11 1 year))))))
+ − 1644 "US Presidential Election"))
+ − 1645 @end smallexample
+ − 1646
+ − 1647 @noindent
+ − 1648 or
+ − 1649
+ − 1650 @smallexample
+ − 1651 (if (= 0 (% displayed-year 4))
+ − 1652 (fixed 11
+ − 1653 (extract-calendar-day
+ − 1654 (calendar-gregorian-from-absolute
+ − 1655 (1+ (calendar-dayname-on-or-before
+ − 1656 1 (+ 6 (calendar-absolute-from-gregorian
+ − 1657 (list 11 1 displayed-year)))))))
+ − 1658 "US Presidential Election"))
+ − 1659 @end smallexample
+ − 1660
+ − 1661 Some holidays just don't fit into any of these forms because special
+ − 1662 calculations are involved in their determination. In such cases you
+ − 1663 must write a Lisp function to do the calculation. To include eclipses,
+ − 1664 for example, add @code{(eclipses)} to @code{other-holidays}
+ − 1665 and write an Emacs Lisp function @code{eclipses} that returns a
+ − 1666 (possibly empty) list of the relevant Gregorian dates among the range
+ − 1667 visible in the calendar window, with descriptive strings, like this:
+ − 1668
+ − 1669 @smallexample
+ − 1670 (((6 27 1991) "Lunar Eclipse") ((7 11 1991) "Solar Eclipse") ... )
+ − 1671 @end smallexample
+ − 1672
+ − 1673 @node Date Display Format
+ − 1674 @subsubsection Date Display Format
+ − 1675 @vindex calendar-date-display-form
+ − 1676
+ − 1677 You can customize the manner of displaying dates in the diary, in mode
+ − 1678 lines, and in messages by setting @code{calendar-date-display-form}.
+ − 1679 This variable holds a list of expressions that can involve the variables
+ − 1680 @code{month}, @code{day}, and @code{year}, which are all numbers in
+ − 1681 string form, and @code{monthname} and @code{dayname}, which are both
+ − 1682 alphabetic strings. In the American style, the default value of this
+ − 1683 list is as follows:
+ − 1684
+ − 1685 @smallexample
+ − 1686 ((if dayname (concat dayname ", ")) monthname " " day ", " year)
+ − 1687 @end smallexample
+ − 1688
+ − 1689 @noindent
+ − 1690 while in the European style this value is the default:
+ − 1691
+ − 1692 @smallexample
+ − 1693 ((if dayname (concat dayname ", ")) day " " monthname " " year)
+ − 1694 @end smallexample
+ − 1695
+ − 1696 +@noindent
+ − 1697 The ISO standard date representation is this:
+ − 1698
+ − 1699 @smallexample
+ − 1700 (year "-" month "-" day)
+ − 1701 @end smallexample
+ − 1702
+ − 1703 @noindent
+ − 1704 This specifies a typical American format:
+ − 1705
+ − 1706 @smallexample
+ − 1707 (month "/" day "/" (substring year -2))
+ − 1708 @end smallexample
+ − 1709
+ − 1710 @node Time Display Format
+ − 1711 @subsubsection Time Display Format
+ − 1712 @vindex calendar-time-display-form
+ − 1713
+ − 1714 The calendar and diary by default display times of day in the
+ − 1715 conventional American style with the hours from 1 through 12, minutes,
+ − 1716 and either @samp{am} or @samp{pm}. If you prefer the European style,
+ − 1717 also known in the US as military, in which the hours go from 00 to 23,
+ − 1718 you can alter the variable @code{calendar-time-display-form}. This
+ − 1719 variable is a list of expressions that can involve the variables
+ − 1720 @code{12-hours}, @code{24-hours}, and @code{minutes}, which are all
+ − 1721 numbers in string form, and @code{am-pm} and @code{time-zone}, which are
+ − 1722 both alphabetic strings. The default value of
+ − 1723 @code{calendar-time-display-form} is as follows:
+ − 1724
+ − 1725 @smallexample
+ − 1726 (12-hours ":" minutes am-pm
+ − 1727 (if time-zone " (") time-zone (if time-zone ")"))
+ − 1728 @end smallexample
+ − 1729
+ − 1730 @noindent
+ − 1731 Here is a value that provides European style times:
+ − 1732
+ − 1733 @smallexample
+ − 1734 (24-hours ":" minutes
+ − 1735 (if time-zone " (") time-zone (if time-zone ")"))
+ − 1736 @end smallexample
+ − 1737
+ − 1738 @noindent
+ − 1739 gives military-style times like @samp{21:07 (UT)} if time zone names are
+ − 1740 defined, and times like @samp{21:07} if they are not.
+ − 1741
+ − 1742 @node Daylight Savings
+ − 1743 @subsubsection Daylight Savings Time
+ − 1744 @cindex daylight savings time
+ − 1745
+ − 1746 Emacs understands the difference between standard time and daylight
+ − 1747 savings time---the times given for sunrise, sunset, solstices,
+ − 1748 equinoxes, and the phases of the moon take that into account. The rules
+ − 1749 for daylight savings time vary from place to place and have also varied
+ − 1750 historically from year to year. To do the job properly, Emacs needs to
+ − 1751 know which rules to use.
+ − 1752
+ − 1753 Some operating systems keep track of the rules that apply to the place
+ − 1754 where you are; on these systems, Emacs gets the information it needs
+ − 1755 from the system automatically. If some or all of this information is
+ − 1756 missing, Emacs fills in the gaps with the rules currently used in
+ − 1757 Cambridge, Massachusetts. If the resulting rules are not what you want,
+ − 1758 you can tell Emacs the rules to use by setting certain variables.
+ − 1759
+ − 1760 @vindex calendar-daylight-savings-starts
+ − 1761 @vindex calendar-daylight-savings-ends
+ − 1762 If the default choice of rules is not appropriate for your location,
+ − 1763 you can tell Emacs the rules to use by setting the variables
+ − 1764 @code{calendar-daylight-savings-starts} and
+ − 1765 @code{calendar-daylight-savings-ends}. Their values should be Lisp
+ − 1766 expressions that refer to the variable @code{year}, and evaluate to the
+ − 1767 Gregorian date on which daylight savings time starts or (respectively)
+ − 1768 ends, in the form of a list @code{(@var{month} @var{day} @var{year})}.
+ − 1769 The values should be @code{nil} if your area does not use daylight
+ − 1770 savings time.
+ − 1771
+ − 1772 Emacs uses these expressions to determine the starting date of
+ − 1773 daylight savings time for the holiday list and for correcting times of
+ − 1774 day in the solar and lunar calculations.
+ − 1775
+ − 1776 The values for Cambridge, Massachusetts are as follows:
+ − 1777
+ − 1778 @example
+ − 1779 @group
+ − 1780 (calendar-nth-named-day 1 0 4 year)
+ − 1781 (calendar-nth-named-day -1 0 10 year)
+ − 1782 @end group
+ − 1783 @end example
+ − 1784
+ − 1785 @noindent
+ − 1786 That is, the first 0th day (Sunday) of the fourth month (April) in
+ − 1787 the year specified by @code{year}, and the last Sunday of the tenth month
+ − 1788 (October) of that year. If daylight savings time were
+ − 1789 changed to start on October 1, you would set
+ − 1790 @code{calendar-daylight-savings-starts} to this:
+ − 1791
+ − 1792 @example
+ − 1793 (list 10 1 year)
+ − 1794 @end example
+ − 1795
+ − 1796 For a more complex example, suppose daylight savings time begins on
+ − 1797 the first of Nisan on the Hebrew calendar. You should set
+ − 1798 @code{calendar-daylight-savings-starts} to this value:
+ − 1799
+ − 1800 @example
+ − 1801 (calendar-gregorian-from-absolute
+ − 1802 (calendar-absolute-from-hebrew
+ − 1803 (list 1 1 (+ year 3760))))
+ − 1804 @end example
+ − 1805
+ − 1806 @noindent
+ − 1807 because Nisan is the first month in the Hebrew calendar and the Hebrew
+ − 1808 year differs from the Gregorian year by 3760 at Nisan.
+ − 1809
+ − 1810 If there is no daylight savings time at your location, or if you want
+ − 1811 all times in standard time, set @code{calendar-daylight-savings-starts}
+ − 1812 and @code{calendar-daylight-savings-ends} to @code{nil}.
+ − 1813
+ − 1814 @vindex calendar-daylight-time-offset
+ − 1815 The variable @code{calendar-daylight-time-offset} specifies the
+ − 1816 difference between daylight savings time and standard time, measured in
+ − 1817 minutes. The value for Cambridge, Massachusetts is 60.
+ − 1818
+ − 1819 @c @vindex calendar-daylight-savings-starts-time too long!
+ − 1820 @vindex calendar-daylight-savings-ends-time
+ − 1821 The two variables @code{calendar-daylight-savings-starts-time} and
+ − 1822 @code{calendar-daylight-savings-ends-time} specify the number of minutes
+ − 1823 after midnight local time when the transition to and from daylight
+ − 1824 savings time should occur. For Cambridge, Massachusetts both variables'
+ − 1825 values are 120.
+ − 1826
+ − 1827 @node Diary Customizing
+ − 1828 @subsubsection Customizing the Diary
+ − 1829
+ − 1830 @vindex holidays-in-diary-buffer
+ − 1831 Ordinarily, the mode line of the diary buffer window indicates any
+ − 1832 holidays that fall on the date of the diary entries. The process of
+ − 1833 checking for holidays can take several seconds, so including holiday
+ − 1834 information delays the display of the diary buffer noticeably. If you'd
+ − 1835 prefer to have a faster display of the diary buffer but without the
+ − 1836 holiday information, set the variable @code{holidays-in-diary-buffer} to
+ − 1837 @code{nil}.@refill
+ − 1838
+ − 1839 @vindex number-of-diary-entries
+ − 1840 The variable @code{number-of-diary-entries} controls the number of
+ − 1841 days of diary entries to be displayed at one time. It affects the
+ − 1842 initial display when @code{view-diary-entries-initially} is @code{t}, as
+ − 1843 well as the command @kbd{M-x diary}. For example, the default value is
+ − 1844 1, which says to display only the current day's diary entries. If the
+ − 1845 value is 2, both the current day's and the next day's entries are
+ − 1846 displayed. The value can also be a vector of seven elements: for
+ − 1847 example, if the value is @code{[0 2 2 2 2 4 1]} then no diary entries
+ − 1848 appear on Sunday, the current date's and the next day's diary entries
+ − 1849 appear Monday through Thursday, Friday through Monday's entries appear
+ − 1850 on Friday, while on Saturday only that day's entries appear.
+ − 1851
+ − 1852 @vindex print-diary-entries-hook
+ − 1853 @findex print-diary-entries
+ − 1854 The variable @code{print-diary-entries-hook} is a normal hook run
+ − 1855 after preparation of a temporary buffer containing just the diary
+ − 1856 entries currently visible in the diary buffer. (The other, irrelevant
+ − 1857 diary entries are really absent from the temporary buffer; in the diary
+ − 1858 buffer, they are merely hidden.) The default value of this hook does
+ − 1859 the printing with the command @code{lpr-buffer}. If you want to use a
+ − 1860 different command to do the printing, just change the value of this
+ − 1861 hook. Other uses might include, for example, rearranging the lines into
+ − 1862 order by day and time.
+ − 1863
+ − 1864 @vindex diary-date-forms
+ − 1865 You can customize the form of dates in your diary file, if neither the
+ − 1866 standard American nor European styles suits your needs, by setting the
+ − 1867 variable @code{diary-date-forms}. This variable is a list of patterns
+ − 1868 for recognizing a date. Each date pattern is a list whose elements may
+ − 1869 be regular expressions (@pxref{Regexps}) or the symbols
+ − 1870 @code{month}, @code{day}, @code{year}, @code{monthname}, and
+ − 1871 @code{dayname}. All these elements serve as patterns that match certain
+ − 1872 kinds of text in the diary file. In order for the date pattern, as a
+ − 1873 whole, to match, all of its elements must match consecutively.
+ − 1874
+ − 1875 A regular expression in a date pattern matches in its usual fashion,
+ − 1876 using the standard syntax table altered so that @samp{*} is a word
+ − 1877 constituent.
+ − 1878
+ − 1879 The symbols @code{month}, @code{day}, @code{year}, @code{monthname},
+ − 1880 and @code{dayname} match the month number, day number, year number,
+ − 1881 month name, and day name of the date being considered. The symbols that
+ − 1882 match numbers allow leading zeros; those that match names allow
+ − 1883 three-letter abbreviations and capitalization. All the symbols can
+ − 1884 match @samp{*}; since @samp{*} in a diary entry means ``any day'', ``any
+ − 1885 month'', and so on, it should match regardless of the date being
+ − 1886 considered.
+ − 1887
+ − 1888 The default value of @code{diary-date-forms} in the American style is
+ − 1889 this:
+ − 1890
+ − 1891 @example
+ − 1892 ((month "/" day "[^/0-9]")
+ − 1893 (month "/" day "/" year "[^0-9]")
+ − 1894 (monthname " *" day "[^,0-9]")
+ − 1895 (monthname " *" day ", *" year "[^0-9]")
+ − 1896 (dayname "\\W"))
+ − 1897 @end example
+ − 1898
+ − 1899 @noindent
+ − 1900 Emacs matches of the diary entries with the date forms is done with the
+ − 1901 standard syntax table from Fundamental mode
+ − 1902 (@pxref{Syntax Tables,,,lispref,XEmacs Lisp Reference Manual}),
+ − 1903 but with the @samp{*} changed so that it is a word constituent.@refill
+ − 1904
+ − 1905 The date patterns in the list must be @emph{mutually exclusive} and
+ − 1906 must not match any portion of the diary entry itself, just the date and
+ − 1907 one character of whitespace. If, to be mutually exclusive, the pattern
+ − 1908 must match a portion of the diary entry text---beyond the whitespace
+ − 1909 that ends the date---then the first element of the date pattern
+ − 1910 @emph{must} be @code{backup}. This causes the date recognizer to back
+ − 1911 up to the beginning of the current word of the diary entry, after
+ − 1912 finishing the match. Even if you use @code{backup}, the date pattern
+ − 1913 must absolutely not match more than a portion of the first word of the
+ − 1914 diary entry. The default value of @code{diary-date-forms} in the
+ − 1915 European style is this list:
+ − 1916
+ − 1917 @example
+ − 1918 ((day "/" month "[^/0-9]")
+ − 1919 (day "/" month "/" year "[^0-9]")
+ − 1920 (backup day " *" monthname "\\W+\\<[^*0-9]")
+ − 1921 (day " *" monthname " *" year "[^0-9]")
+ − 1922 (dayname "\\W"))
+ − 1923 @end example
+ − 1924
+ − 1925 @noindent
+ − 1926 Notice the use of @code{backup} in the third pattern, because it needs
+ − 1927 to match part of a word beyond the date itself to distinguish it from
+ − 1928 the fourth pattern.
+ − 1929
+ − 1930 @node Hebrew/Islamic Entries
+ − 1931 @subsubsection Hebrew- and Islamic-Date Diary Entries
+ − 1932
+ − 1933 Your diary file can have entries based on Hebrew or Islamic dates, as
+ − 1934 well as entries based on the world-standard Gregorian calendar.
+ − 1935 However, because recognition of such entries is time-consuming and most
+ − 1936 people don't use them, you must explicitly enable their use. If you
+ − 1937 want the diary to recognize Hebrew-date diary entries, for example,
+ − 1938 you must do this:
+ − 1939
+ − 1940 @vindex nongregorian-diary-listing-hook
+ − 1941 @vindex nongregorian-diary-marking-hook
+ − 1942 @findex list-hebrew-diary-entries
+ − 1943 @findex mark-hebrew-diary-entries
+ − 1944 @smallexample
+ − 1945 (add-hook 'nongregorian-diary-listing-hook 'list-hebrew-diary-entries)
+ − 1946 (add-hook 'nongregorian-diary-marking-hook 'mark-hebrew-diary-entries)
+ − 1947 @end smallexample
+ − 1948
+ − 1949 @noindent
+ − 1950 If you want Islamic-date entries, do this:
+ − 1951
+ − 1952 @findex list-islamic-diary-entries
+ − 1953 @findex mark-islamic-diary-entries
+ − 1954 @smallexample
+ − 1955 (add-hook 'nongregorian-diary-listing-hook 'list-islamic-diary-entries)
+ − 1956 (add-hook 'nongregorian-diary-marking-hook 'mark-islamic-diary-entries)
+ − 1957 @end smallexample
+ − 1958
+ − 1959 Hebrew- and Islamic-date diary entries have the same formats as
+ − 1960 Gregorian-date diary entries, except that @samp{H} precedes a Hebrew
+ − 1961 date and @samp{I} precedes an Islamic date. Moreover, because the
+ − 1962 Hebrew and Islamic month names are not uniquely specified by the first
+ − 1963 three letters, you may not abbreviate them. For example, a diary entry
+ − 1964 for the Hebrew date Heshvan 25 could look like this:
+ − 1965
+ − 1966 @smallexample
+ − 1967 HHeshvan 25 Happy Hebrew birthday!
+ − 1968 @end smallexample
+ − 1969
+ − 1970 @noindent
+ − 1971 and would appear in the diary for any date that corresponds to Heshvan 25
+ − 1972 on the Hebrew calendar. And here is Islamic-date diary entry that matches
+ − 1973 Dhu al-Qada 25:
+ − 1974
+ − 1975 @smallexample
+ − 1976 IDhu al-Qada 25 Happy Islamic birthday!
+ − 1977 @end smallexample
+ − 1978
+ − 1979 @noindent
+ − 1980 and would appear in the diary for any date that corresponds to Dhu al-Qada 25
+ − 1981 on the Islamic calendar.
+ − 1982
+ − 1983 As with Gregorian-date diary entries, Hebrew- and Islamic-date entries
+ − 1984 are nonmarking if they are preceded with an ampersand (@samp{&}).
+ − 1985
+ − 1986 Here is a table of commands used in the calendar to create diary entries
+ − 1987 that match the selected date and other dates that are similar in the Hebrew
+ − 1988 or Islamic calendar:
+ − 1989
+ − 1990 @table @kbd
+ − 1991 @item i h d
+ − 1992 Add a diary entry for the Hebrew date corresponding to the selected date
+ − 1993 (@code{insert-hebrew-diary-entry}).
+ − 1994 @item i h m
+ − 1995 Add a diary entry for the day of the Hebrew month corresponding to the
+ − 1996 selected date (@code{insert-monthly-hebrew-diary-entry}). This diary
+ − 1997 entry matches any date that has the same Hebrew day-within-month as the
+ − 1998 selected date.
+ − 1999 @item i h y
+ − 2000 Add a diary entry for the day of the Hebrew year corresponding to the
+ − 2001 selected date (@code{insert-yearly-hebrew-diary-entry}). This diary
+ − 2002 entry matches any date which has the same Hebrew month and day-within-month
+ − 2003 as the selected date.
+ − 2004 @item i i d
+ − 2005 Add a diary entry for the Islamic date corresponding to the selected date
+ − 2006 (@code{insert-islamic-diary-entry}).
+ − 2007 @item i i m
+ − 2008 Add a diary entry for the day of the Islamic month corresponding to the
+ − 2009 selected date (@code{insert-monthly-islamic-diary-entry}).
+ − 2010 @item i i y
+ − 2011 Add a diary entry for the day of the Islamic year corresponding to the
+ − 2012 selected date (@code{insert-yearly-islamic-diary-entry}).
+ − 2013 @end table
+ − 2014
+ − 2015 @findex insert-hebrew-diary-entry
+ − 2016 @findex insert-monthly-hebrew-diary-entry
+ − 2017 @findex insert-yearly-hebrew-diary-entry
+ − 2018 @findex insert-islamic-diary-entry
+ − 2019 @findex insert-monthly-islamic-diary-entry
+ − 2020 @findex insert-yearly-islamic-diary-entry
+ − 2021 These commands work much like the corresponding commands for ordinary
+ − 2022 diary entries: they apply to the date that point is on in the calendar
+ − 2023 window, and what they do is insert just the date portion of a diary entry
+ − 2024 at the end of your diary file. You must then insert the rest of the
+ − 2025 diary entry.
+ − 2026
+ − 2027 @node Fancy Diary Display
+ − 2028 @subsubsection Fancy Diary Display
+ − 2029 @vindex diary-display-hook
+ − 2030 @findex simple-diary-display
+ − 2031
+ − 2032 Diary display works by preparing the diary buffer and then running the
+ − 2033 hook @code{diary-display-hook}. The default value of this hook
+ − 2034 (@code{simple-diary-display}) hides the irrelevant diary entries and
+ − 2035 then displays the buffer. However, if you specify the hook as follows,
+ − 2036
+ − 2037 @cindex diary buffer
+ − 2038 @findex fancy-diary-display
+ − 2039 @example
+ − 2040 (add-hook 'diary-display-hook 'fancy-diary-display)
+ − 2041 @end example
+ − 2042
+ − 2043 @noindent
+ − 2044 this enables fancy diary display. It displays diary entries and
+ − 2045 holidays by copying them into a special buffer that exists only for the
+ − 2046 sake of display. Copying to a separate buffer provides an opportunity
+ − 2047 to change the displayed text to make it prettier---for example, to sort
+ − 2048 the entries by the dates they apply to.
+ − 2049
+ − 2050 As with simple diary display, you can print a hard copy of the buffer
+ − 2051 with @code{print-diary-entries}. To print a hard copy of a day-by-day
+ − 2052 diary for a week by positioning point on Sunday of that week, type
+ − 2053 @kbd{7 d} and then do @kbd{M-x print-diary-entries}. As usual, the
+ − 2054 inclusion of the holidays slows down the display slightly; you can speed
+ − 2055 things up by setting the variable @code{holidays-in-diary-buffer} to
+ − 2056 @code{nil}.
+ − 2057
+ − 2058 @vindex diary-list-include-blanks
+ − 2059 Ordinarily, the fancy diary buffer does not show days for which there are
+ − 2060 no diary entries, even if that day is a holiday. If you want such days to be
+ − 2061 shown in the fancy diary buffer, set the variable
+ − 2062 @code{diary-list-include-blanks} to @code{t}.@refill
+ − 2063
+ − 2064 @cindex sorting diary entries
+ − 2065 If you use the fancy diary display, you can use the normal hook
+ − 2066 @code{list-diary-entries-hook} to sort each day's diary entries by their
442
+ − 2067 time of day. Add this line to your init file:
428
+ − 2068
+ − 2069 @findex sort-diary-entries
+ − 2070 @example
+ − 2071 (add-hook 'list-diary-entries-hook 'sort-diary-entries t)
+ − 2072 @end example
+ − 2073
442
+ − 2074 @xref{Init File}.
+ − 2075
428
+ − 2076 @noindent
+ − 2077 For each day, this sorts diary entries that begin with a recognizable
+ − 2078 time of day according to their times. Diary entries without times come
+ − 2079 first within each day.
+ − 2080
+ − 2081 @node Included Diary Files
+ − 2082 @subsubsection Included Diary Files
+ − 2083
+ − 2084 Fancy diary display also has the ability to process included diary
+ − 2085 files. This permits a group of people to share a diary file for events
+ − 2086 that apply to all of them. Lines in the diary file of this form:
+ − 2087
+ − 2088 @smallexample
+ − 2089 #include "@var{filename}"
+ − 2090 @end smallexample
+ − 2091
+ − 2092 @noindent
+ − 2093 includes the diary entries from the file @var{filename} in the fancy
+ − 2094 diary buffer. The include mechanism is recursive, so that included files
+ − 2095 can include other files, and so on; you must be careful not to have a
+ − 2096 cycle of inclusions, of course. Here is how to enable the include
+ − 2097 facility:
+ − 2098
+ − 2099 @vindex list-diary-entries-hook
+ − 2100 @vindex mark-diary-entries-hook
+ − 2101 @findex include-other-diary-files
+ − 2102 @findex mark-included-diary-files
+ − 2103 @smallexample
+ − 2104 (add-hook 'list-diary-entries-hook 'include-other-diary-files)
+ − 2105 (add-hook 'mark-diary-entries-hook 'mark-included-diary-files)
+ − 2106 @end smallexample
+ − 2107
+ − 2108 The include mechanism works only with the fancy diary display, because
+ − 2109 ordinary diary display shows the entries directly from your diary file.
+ − 2110
+ − 2111 @node Sexp Diary Entries
+ − 2112 @subsubsection Sexp Entries and the Fancy Diary Display
+ − 2113 @cindex sexp diary entries
+ − 2114
+ − 2115 Sexp diary entries allow you to do more than just have complicated
+ − 2116 conditions under which a diary entry applies. If you use the fancy
+ − 2117 diary display, sexp entries can generate the text of the entry depending
+ − 2118 on the date itself. For example, an anniversary diary entry can insert
+ − 2119 the number of years since the anniversary date into the text of the
+ − 2120 diary entry. Thus the @samp{%d} in this dairy entry:
+ − 2121
+ − 2122 @findex diary-anniversary
+ − 2123 @smallexample
+ − 2124 %%(diary-anniversary 10 31 1948) Arthur's birthday (%d years old)
+ − 2125 @end smallexample
+ − 2126
+ − 2127 @noindent
+ − 2128 gets replaced by the age, so on October 31, 1990 the entry appears in
+ − 2129 the fancy diary buffer like this:
+ − 2130
+ − 2131 @smallexample
+ − 2132 Arthur's birthday (42 years old)
+ − 2133 @end smallexample
+ − 2134
+ − 2135 @noindent
+ − 2136 If the diary file instead contains this entry:
+ − 2137
+ − 2138 @smallexample
+ − 2139 %%(diary-anniversary 10 31 1948) Arthur's %d%s birthday
+ − 2140 @end smallexample
+ − 2141
+ − 2142 @noindent
+ − 2143 the entry in the fancy diary buffer for October 31, 1990 appears like this:
+ − 2144
+ − 2145 @smallexample
+ − 2146 Arthur's 42nd birthday
+ − 2147 @end smallexample
+ − 2148
+ − 2149 Similarly, cyclic diary entries can interpolate the number of repetitions
+ − 2150 that have occurred:
+ − 2151
+ − 2152 @findex diary-cyclic
+ − 2153 @smallexample
+ − 2154 %%(diary-cyclic 50 1 1 1990) Renew medication (%d%s time)
+ − 2155 @end smallexample
+ − 2156
+ − 2157 @noindent
+ − 2158 looks like this:
+ − 2159
+ − 2160 @smallexample
+ − 2161 Renew medication (5th time)
+ − 2162 @end smallexample
+ − 2163
+ − 2164 @noindent
+ − 2165 in the fancy diary display on September 8, 1990.
+ − 2166
+ − 2167 The generality of sexp diary entries lets you specify any diary entry
+ − 2168 that you can describe algorithmically. A sexp diary entry contains an
+ − 2169 expression that computes whether the entry applies to any given date.
+ − 2170 If its value is non-@code{nil}, the entry applies to that date;
+ − 2171 otherwise, it does not. The expression can use the variable @code{date}
+ − 2172 to find the date being considered; its value is a list (@var{month}
+ − 2173 @var{day} @var{year}) that refers to the Gregorian calendar.
+ − 2174
+ − 2175 Suppose you get paid on the 21st of the month if it is a weekday, and
+ − 2176 on the Friday before if the 21st is on a weekend. Here is how to write
+ − 2177 a sexp diary entry that matches those dates:
+ − 2178
+ − 2179 @smallexample
+ − 2180 &%%(let ((dayname (calendar-day-of-week date))
+ − 2181 (day (car (cdr date))))
+ − 2182 (or (and (= day 21) (memq dayname '(1 2 3 4 5)))
+ − 2183 (and (memq day '(19 20)) (= dayname 5)))
+ − 2184 ) Pay check deposited
+ − 2185 @end smallexample
+ − 2186
+ − 2187 @noindent
+ − 2188 applies to just those dates. This example illustrates how the sexp can
+ − 2189 depend on the variable @code{date}; this variable is a list (@var{month}
+ − 2190 @var{day} @var{year}) that gives the Gregorian date for which the diary
+ − 2191 entries are being found. If the value of the expression is @code{t},
+ − 2192 the entry applies to that date. If the expression evaluates to
+ − 2193 @code{nil}, the entry does @emph{not} apply to that date.
+ − 2194
+ − 2195 The following sexp diary entries take advantage of the ability (in the fancy
+ − 2196 diary display) to concoct diary entries whose text varies based on the date:
+ − 2197
+ − 2198 @findex diary-sunrise-sunset
+ − 2199 @findex diary-phases-of-moon
+ − 2200 @findex diary-day-of-year
+ − 2201 @findex diary-iso-date
+ − 2202 @findex diary-julian-date
+ − 2203 @findex diary-astro-day-number
+ − 2204 @findex diary-hebrew-date
+ − 2205 @findex diary-islamic-date
+ − 2206 @findex diary-french-date
+ − 2207 @findex diary-mayan-date
+ − 2208 @table @code
+ − 2209 @item %%(diary-sunrise-sunset)
+ − 2210 Make a diary entry for the local times of today's sunrise and sunset.
+ − 2211 @item %%(diary-phases-of-moon)
+ − 2212 Make a diary entry for the phases (quarters) of the moon.
+ − 2213 @item %%(diary-day-of-year)
+ − 2214 Make a diary entry with today's day number in the current year and the number
+ − 2215 of days remaining in the current year.
+ − 2216 @item %%(diary-iso-date)
+ − 2217 Make a diary entry with today's equivalent ISO commercial date.
+ − 2218 @item %%(diary-julian-date)
+ − 2219 Make a diary entry with today's equivalent date on the Julian calendar.
+ − 2220 @item %%(diary-astro-day-number)
+ − 2221 Make a diary entry with today's equivalent astronomical (Julian) day number.
+ − 2222 @item %%(diary-hebrew-date)
+ − 2223 Make a diary entry with today's equivalent date on the Hebrew calendar.
+ − 2224 @item %%(diary-islamic-date)
+ − 2225 Make a diary entry with today's equivalent date on the Islamic calendar.
+ − 2226 @item %%(diary-french-date)
+ − 2227 Make a diary entry with today's equivalent date on the French Revolutionary
+ − 2228 calendar.
+ − 2229 @item %%(diary-mayan-date)
+ − 2230 Make a diary entry with today's equivalent date on the Mayan calendar.
+ − 2231 @end table
+ − 2232
+ − 2233 @noindent
+ − 2234 Thus including the diary entry
+ − 2235
+ − 2236 @smallexample
+ − 2237 &%%(diary-hebrew-date)
+ − 2238 @end smallexample
+ − 2239
+ − 2240 @noindent
+ − 2241 causes every day's diary display to contain the equivalent date on the
+ − 2242 Hebrew calendar, if you are using the fancy diary display. (With simple
+ − 2243 diary display, the line @samp{&%%(diary-hebrew-date)} appears in the
+ − 2244 diary for any date, but does nothing particularly useful.)
+ − 2245
+ − 2246 These functions can be used to construct sexp diary entries based on
+ − 2247 the Hebrew calendar in certain standard ways:
+ − 2248
+ − 2249 @cindex rosh hodesh
+ − 2250 @findex diary-rosh-hodesh
+ − 2251 @cindex parasha, weekly
+ − 2252 @findex diary-parasha
+ − 2253 @cindex candle lighting times
+ − 2254 @findex diary-sabbath-candles
+ − 2255 @cindex omer count
+ − 2256 @findex diary-omer
+ − 2257 @cindex yahrzeits
+ − 2258 @findex diary-yahrzeit
+ − 2259 @table @code
+ − 2260 @item %%(diary-rosh-hodesh)
+ − 2261 Make a diary entry that tells the occurrence and ritual announcement of each
+ − 2262 new Hebrew month.
+ − 2263 @item %%(diary-parasha)
+ − 2264 Make a Saturday diary entry that tells the weekly synagogue scripture reading.
+ − 2265 @item %%(diary-sabbath-candles)
+ − 2266 Make a Friday diary entry that tells the @emph{local time} of Sabbath
+ − 2267 candle lighting.
+ − 2268 @item %%(diary-omer)
+ − 2269 Make a diary entry that gives the omer count, when appropriate.
+ − 2270 @item %%(diary-yahrzeit @var{month} @var{day} @var{year}) @var{name}
+ − 2271 Make a diary entry marking the anniversary of a date of death. The date
+ − 2272 is the @emph{Gregorian} (civil) date of death. The diary entry appears
+ − 2273 on the proper Hebrew calendar anniversary and on the day before. (In
+ − 2274 the European style, the order of the parameters is changed to @var{day},
+ − 2275 @var{month}, @var{year}.)
+ − 2276 @end table
+ − 2277
+ − 2278 @node Appt Customizing
+ − 2279 @subsubsection Customizing Appointment Reminders
+ − 2280
+ − 2281 You can specify exactly how Emacs reminds you of an appointment, and
+ − 2282 how far in advance it begins doing so, by setting these variables:
+ − 2283
+ − 2284 @vindex appt-message-warning-time
+ − 2285 @vindex appt-audible
+ − 2286 @vindex appt-visible
+ − 2287 @vindex appt-display-mode-line
+ − 2288 @vindex appt-msg-window
+ − 2289 @vindex appt-display-duration
+ − 2290 @table @code
+ − 2291 @item appt-message-warning-time
+ − 2292 The time in minutes before an appointment that the reminder begins. The
+ − 2293 default is 10 minutes.
+ − 2294 @item appt-audible
+ − 2295 If this is @code{t} (the default), Emacs rings the terminal bell for
+ − 2296 appointment reminders.
+ − 2297 @item appt-visible
+ − 2298 If this is @code{t} (the default), Emacs displays the appointment
+ − 2299 message in echo area.
+ − 2300 @item appt-display-mode-line
+ − 2301 If this is @code{t} (the default), Emacs displays the number of minutes
+ − 2302 to the appointment on the mode line.
+ − 2303 @item appt-msg-window
+ − 2304 If this is @code{t} (the default), Emacs displays the appointment
+ − 2305 message in another window.
+ − 2306 @item appt-display-duration
+ − 2307 The number of seconds an appointment message is displayed. The default
+ − 2308 is 5 seconds.
+ − 2309 @end table