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