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