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