Mercurial > emacs
comparison man/cal-xtra.texi @ 70440:5e1c038e4afa
New file, a portion of emacs-xtra.texi.
author | Eli Zaretskii <eliz@gnu.org> |
---|---|
date | Sat, 06 May 2006 12:45:46 +0000 |
parents | |
children | bdd0ac985d67 |
comparison
equal
deleted
inserted
replaced
70439:48fec2b642c9 | 70440:5e1c038e4afa |
---|---|
1 @c This file is included either in emacs-xtra.texi (when producing the | |
2 @c printed version) or in the main Emacs manual (for the on-line version). | |
3 | |
4 @c Moved here from the Emacs Lisp Reference Manual, 2005-03-26. | |
5 @node Advanced Calendar/Diary Usage | |
6 @section Customizing the Calendar and Diary | |
7 | |
8 There are many customizations that you can use to make the calendar and | |
9 diary suit your personal tastes. | |
10 | |
11 @menu | |
12 * Calendar Customizing:: Defaults you can set. | |
13 * Holiday Customizing:: Defining your own holidays. | |
14 * Date Display Format:: Changing the format. | |
15 * Time Display Format:: Changing the format. | |
16 * Diary Customizing:: Defaults you can set. | |
17 * Hebrew/Islamic Entries:: How to obtain them. | |
18 * Fancy Diary Display:: Enhancing the diary display, sorting entries, | |
19 using included diary files. | |
20 * Sexp Diary Entries:: Fancy things you can do. | |
21 @end menu | |
22 | |
23 @node Calendar Customizing | |
24 @subsection Customizing the Calendar | |
25 @vindex calendar-holiday-marker | |
26 @vindex diary-entry-marker | |
27 The variable @code{calendar-holiday-marker} specifies how to mark a | |
28 date as being a holiday. Its value may be a single-character string | |
29 to insert next to the date, or a face name to use for displaying the | |
30 date. Likewise, the variable @code{diary-entry-marker} specifies how | |
31 to mark a date that has diary entries. The calendar creates faces | |
32 named @code{holiday-face} and @code{diary-face} for these purposes; | |
33 those symbols are the default values of these variables. | |
34 | |
35 @vindex calendar-load-hook | |
36 The variable @code{calendar-load-hook} is a normal hook run when the | |
37 calendar package is first loaded (before actually starting to display | |
38 the calendar). | |
39 | |
40 @vindex initial-calendar-window-hook | |
41 Starting the calendar runs the normal hook | |
42 @code{initial-calendar-window-hook}. Recomputation of the calendar | |
43 display does not run this hook. But if you leave the calendar with the | |
44 @kbd{q} command and reenter it, the hook runs again.@refill | |
45 | |
46 @vindex today-visible-calendar-hook | |
47 The variable @code{today-visible-calendar-hook} is a normal hook run | |
48 after the calendar buffer has been prepared with the calendar when the | |
49 current date is visible in the window. One use of this hook is to | |
50 replace today's date with asterisks; to do that, use the hook function | |
51 @code{calendar-star-date}. | |
52 | |
53 @findex calendar-star-date | |
54 @example | |
55 (add-hook 'today-visible-calendar-hook 'calendar-star-date) | |
56 @end example | |
57 | |
58 @noindent | |
59 Another standard hook function marks the current date, either by | |
60 changing its face or by adding an asterisk. Here's how to use it: | |
61 | |
62 @findex calendar-mark-today | |
63 @example | |
64 (add-hook 'today-visible-calendar-hook 'calendar-mark-today) | |
65 @end example | |
66 | |
67 @noindent | |
68 @vindex calendar-today-marker | |
69 The variable @code{calendar-today-marker} specifies how to mark | |
70 today's date. Its value should be a single-character string to insert | |
71 next to the date or a face name to use for displaying the date. A | |
72 face named @code{calendar-today-face} is provided for this purpose; | |
73 that symbol is the default for this variable. | |
74 | |
75 @vindex today-invisible-calendar-hook | |
76 @noindent | |
77 A similar normal hook, @code{today-invisible-calendar-hook} is run if | |
78 the current date is @emph{not} visible in the window. | |
79 | |
80 @vindex calendar-move-hook | |
81 Each of the calendar cursor motion commands runs the hook | |
82 @code{calendar-move-hook} after it moves the cursor. | |
83 | |
84 @node Holiday Customizing | |
85 @subsection Customizing the Holidays | |
86 | |
87 @vindex calendar-holidays | |
88 @vindex christian-holidays | |
89 @vindex hebrew-holidays | |
90 @vindex islamic-holidays | |
91 Emacs knows about holidays defined by entries on one of several lists. | |
92 You can customize these lists of holidays to your own needs, adding or | |
93 deleting holidays. The lists of holidays that Emacs uses are for | |
94 general holidays (@code{general-holidays}), local holidays | |
95 (@code{local-holidays}), Christian holidays (@code{christian-holidays}), | |
96 Hebrew (Jewish) holidays (@code{hebrew-holidays}), Islamic (Muslim) | |
97 holidays (@code{islamic-holidays}), and other holidays | |
98 (@code{other-holidays}). | |
99 | |
100 @vindex general-holidays | |
101 The general holidays are, by default, holidays common throughout the | |
102 United States. To eliminate these holidays, set @code{general-holidays} | |
103 to @code{nil}. | |
104 | |
105 @vindex local-holidays | |
106 There are no default local holidays (but sites may supply some). You | |
107 can set the variable @code{local-holidays} to any list of holidays, as | |
108 described below. | |
109 | |
110 @vindex all-christian-calendar-holidays | |
111 @vindex all-hebrew-calendar-holidays | |
112 @vindex all-islamic-calendar-holidays | |
113 By default, Emacs does not include all the holidays of the religions | |
114 that it knows, only those commonly found in secular calendars. For a | |
115 more extensive collection of religious holidays, you can set any (or | |
116 all) of the variables @code{all-christian-calendar-holidays}, | |
117 @code{all-hebrew-calendar-holidays}, or | |
118 @code{all-islamic-calendar-holidays} to @code{t}. If you want to | |
119 eliminate the religious holidays, set any or all of the corresponding | |
120 variables @code{christian-holidays}, @code{hebrew-holidays}, and | |
121 @code{islamic-holidays} to @code{nil}.@refill | |
122 | |
123 @vindex other-holidays | |
124 You can set the variable @code{other-holidays} to any list of | |
125 holidays. This list, normally empty, is intended for individual use. | |
126 | |
127 @cindex holiday forms | |
128 Each of the lists (@code{general-holidays}, @code{local-holidays}, | |
129 @code{christian-holidays}, @code{hebrew-holidays}, | |
130 @code{islamic-holidays}, and @code{other-holidays}) is a list of | |
131 @dfn{holiday forms}, each holiday form describing a holiday (or | |
132 sometimes a list of holidays). | |
133 | |
134 Here is a table of the possible kinds of holiday form. Day numbers | |
135 and month numbers count starting from 1, but ``dayname'' numbers | |
136 count Sunday as 0. The element @var{string} is always the | |
137 name of the holiday, as a string. | |
138 | |
139 @table @code | |
140 @item (holiday-fixed @var{month} @var{day} @var{string}) | |
141 A fixed date on the Gregorian calendar. | |
142 | |
143 @item (holiday-float @var{month} @var{dayname} @var{k} @var{string}) | |
144 The @var{k}th @var{dayname} in @var{month} on the Gregorian calendar | |
145 (@var{dayname}=0 for Sunday, and so on); negative @var{k} means count back | |
146 from the end of the month. | |
147 | |
148 @item (holiday-hebrew @var{month} @var{day} @var{string}) | |
149 A fixed date on the Hebrew calendar. | |
150 | |
151 @item (holiday-islamic @var{month} @var{day} @var{string}) | |
152 A fixed date on the Islamic calendar. | |
153 | |
154 @item (holiday-julian @var{month} @var{day} @var{string}) | |
155 A fixed date on the Julian calendar. | |
156 | |
157 @item (holiday-sexp @var{sexp} @var{string}) | |
158 A date calculated by the Lisp expression @var{sexp}. The expression | |
159 should use the variable @code{year} to compute and return the date of a | |
160 holiday, or @code{nil} if the holiday doesn't happen this year. The | |
161 value of @var{sexp} must represent the date as a list of the form | |
162 @code{(@var{month} @var{day} @var{year})}. | |
163 | |
164 @item (if @var{condition} @var{holiday-form}) | |
165 A holiday that happens only if @var{condition} is true. | |
166 | |
167 @item (@var{function} @r{[}@var{args}@r{]}) | |
168 A list of dates calculated by the function @var{function}, called with | |
169 arguments @var{args}. | |
170 @end table | |
171 | |
172 For example, suppose you want to add Bastille Day, celebrated in | |
173 France on July 14. You can do this as follows: | |
174 | |
175 @smallexample | |
176 (setq other-holidays '((holiday-fixed 7 14 "Bastille Day"))) | |
177 @end smallexample | |
178 | |
179 @noindent | |
180 The holiday form @code{(holiday-fixed 7 14 "Bastille Day")} specifies the | |
181 fourteenth day of the seventh month (July). | |
182 | |
183 Many holidays occur on a specific day of the week, at a specific time | |
184 of month. Here is a holiday form describing Hurricane Supplication Day, | |
185 celebrated in the Virgin Islands on the fourth Monday in August: | |
186 | |
187 @smallexample | |
188 (holiday-float 8 1 4 "Hurricane Supplication Day") | |
189 @end smallexample | |
190 | |
191 @noindent | |
192 Here the 8 specifies August, the 1 specifies Monday (Sunday is 0, | |
193 Tuesday is 2, and so on), and the 4 specifies the fourth occurrence in | |
194 the month (1 specifies the first occurrence, 2 the second occurrence, | |
195 @minus{}1 the last occurrence, @minus{}2 the second-to-last occurrence, and | |
196 so on). | |
197 | |
198 You can specify holidays that occur on fixed days of the Hebrew, | |
199 Islamic, and Julian calendars too. For example, | |
200 | |
201 @smallexample | |
202 (setq other-holidays | |
203 '((holiday-hebrew 10 2 "Last day of Hanukkah") | |
204 (holiday-islamic 3 12 "Mohammed's Birthday") | |
205 (holiday-julian 4 2 "Jefferson's Birthday"))) | |
206 @end smallexample | |
207 | |
208 @noindent | |
209 adds the last day of Hanukkah (since the Hebrew months are numbered with | |
210 1 starting from Nisan), the Islamic feast celebrating Mohammed's | |
211 birthday (since the Islamic months are numbered from 1 starting with | |
212 Muharram), and Thomas Jefferson's birthday, which is 2 April 1743 on the | |
213 Julian calendar. | |
214 | |
215 To include a holiday conditionally, use either Emacs Lisp's @code{if} or the | |
216 @code{holiday-sexp} form. For example, American presidential elections | |
217 occur on the first Tuesday after the first Monday in November of years | |
218 divisible by 4: | |
219 | |
220 @smallexample | |
221 (holiday-sexp '(if (= 0 (% year 4)) | |
222 (calendar-gregorian-from-absolute | |
223 (1+ (calendar-dayname-on-or-before | |
224 1 (+ 6 (calendar-absolute-from-gregorian | |
225 (list 11 1 year))))))) | |
226 "US Presidential Election") | |
227 @end smallexample | |
228 | |
229 @noindent | |
230 or | |
231 | |
232 @smallexample | |
233 (if (= 0 (% displayed-year 4)) | |
234 (fixed 11 | |
235 (extract-calendar-day | |
236 (calendar-gregorian-from-absolute | |
237 (1+ (calendar-dayname-on-or-before | |
238 1 (+ 6 (calendar-absolute-from-gregorian | |
239 (list 11 1 displayed-year))))))) | |
240 "US Presidential Election")) | |
241 @end smallexample | |
242 | |
243 Some holidays just don't fit into any of these forms because special | |
244 calculations are involved in their determination. In such cases you | |
245 must write a Lisp function to do the calculation. To include eclipses, | |
246 for example, add @code{(eclipses)} to @code{other-holidays} | |
247 and write an Emacs Lisp function @code{eclipses} that returns a | |
248 (possibly empty) list of the relevant Gregorian dates among the range | |
249 visible in the calendar window, with descriptive strings, like this: | |
250 | |
251 @smallexample | |
252 (((6 27 1991) "Lunar Eclipse") ((7 11 1991) "Solar Eclipse") ... ) | |
253 @end smallexample | |
254 | |
255 @node Date Display Format | |
256 @subsection Date Display Format | |
257 @vindex calendar-date-display-form | |
258 | |
259 You can customize the manner of displaying dates in the diary, in mode | |
260 lines, and in messages by setting @code{calendar-date-display-form}. | |
261 This variable holds a list of expressions that can involve the variables | |
262 @code{month}, @code{day}, and @code{year}, which are all numbers in | |
263 string form, and @code{monthname} and @code{dayname}, which are both | |
264 alphabetic strings. In the American style, the default value of this | |
265 list is as follows: | |
266 | |
267 @smallexample | |
268 ((if dayname (concat dayname ", ")) monthname " " day ", " year) | |
269 @end smallexample | |
270 | |
271 @noindent | |
272 while in the European style this value is the default: | |
273 | |
274 @smallexample | |
275 ((if dayname (concat dayname ", ")) day " " monthname " " year) | |
276 @end smallexample | |
277 | |
278 @noindent | |
279 The ISO standard date representation is this: | |
280 | |
281 @smallexample | |
282 (year "-" month "-" day) | |
283 @end smallexample | |
284 | |
285 @noindent | |
286 This specifies a typical American format: | |
287 | |
288 @smallexample | |
289 (month "/" day "/" (substring year -2)) | |
290 @end smallexample | |
291 | |
292 @node Time Display Format | |
293 @subsection Time Display Format | |
294 @vindex calendar-time-display-form | |
295 | |
296 The calendar and diary by default display times of day in the | |
297 conventional American style with the hours from 1 through 12, minutes, | |
298 and either @samp{am} or @samp{pm}. If you prefer the European style, | |
299 also known in the US as military, in which the hours go from 00 to 23, | |
300 you can alter the variable @code{calendar-time-display-form}. This | |
301 variable is a list of expressions that can involve the variables | |
302 @code{12-hours}, @code{24-hours}, and @code{minutes}, which are all | |
303 numbers in string form, and @code{am-pm} and @code{time-zone}, which are | |
304 both alphabetic strings. The default value of | |
305 @code{calendar-time-display-form} is as follows: | |
306 | |
307 @smallexample | |
308 (12-hours ":" minutes am-pm | |
309 (if time-zone " (") time-zone (if time-zone ")")) | |
310 @end smallexample | |
311 | |
312 @noindent | |
313 Here is a value that provides European style times: | |
314 | |
315 @smallexample | |
316 (24-hours ":" minutes | |
317 (if time-zone " (") time-zone (if time-zone ")")) | |
318 @end smallexample | |
319 | |
320 @node Diary Customizing | |
321 @subsection Customizing the Diary | |
322 | |
323 @vindex holidays-in-diary-buffer | |
324 Ordinarily, the mode line of the diary buffer window indicates any | |
325 holidays that fall on the date of the diary entries. The process of | |
326 checking for holidays can take several seconds, so including holiday | |
327 information delays the display of the diary buffer noticeably. If you'd | |
328 prefer to have a faster display of the diary buffer but without the | |
329 holiday information, set the variable @code{holidays-in-diary-buffer} to | |
330 @code{nil}.@refill | |
331 | |
332 @vindex number-of-diary-entries | |
333 The variable @code{number-of-diary-entries} controls the number of | |
334 days of diary entries to be displayed at one time. It affects the | |
335 initial display when @code{view-diary-entries-initially} is @code{t}, as | |
336 well as the command @kbd{M-x diary}. For example, the default value is | |
337 1, which says to display only the current day's diary entries. If the | |
338 value is 2, both the current day's and the next day's entries are | |
339 displayed. The value can also be a vector of seven elements: for | |
340 example, if the value is @code{[0 2 2 2 2 4 1]} then no diary entries | |
341 appear on Sunday, the current date's and the next day's diary entries | |
342 appear Monday through Thursday, Friday through Monday's entries appear | |
343 on Friday, while on Saturday only that day's entries appear. | |
344 | |
345 @vindex print-diary-entries-hook | |
346 @findex print-diary-entries | |
347 The variable @code{print-diary-entries-hook} is a normal hook run | |
348 after preparation of a temporary buffer containing just the diary | |
349 entries currently visible in the diary buffer. (The other, irrelevant | |
350 diary entries are really absent from the temporary buffer; in the diary | |
351 buffer, they are merely hidden.) The default value of this hook does | |
352 the printing with the command @code{lpr-buffer}. If you want to use a | |
353 different command to do the printing, just change the value of this | |
354 hook. Other uses might include, for example, rearranging the lines into | |
355 order by day and time. | |
356 | |
357 @vindex diary-date-forms | |
358 You can customize the form of dates in your diary file, if neither the | |
359 standard American nor European styles suits your needs, by setting the | |
360 variable @code{diary-date-forms}. This variable is a list of patterns | |
361 for recognizing a date. Each date pattern is a list whose elements may | |
362 be regular expressions (@pxref{Regular Expressions,,, elisp, the Emacs | |
363 Lisp Reference Manual}) or the symbols @code{month}, @code{day}, | |
364 @code{year}, @code{monthname}, and @code{dayname}. All these elements | |
365 serve as patterns that match certain kinds of text in the diary file. | |
366 In order for the date pattern, as a whole, to match, all of its elements | |
367 must match consecutively. | |
368 | |
369 A regular expression in a date pattern matches in its usual fashion, | |
370 using the standard syntax table altered so that @samp{*} is a word | |
371 constituent. | |
372 | |
373 The symbols @code{month}, @code{day}, @code{year}, @code{monthname}, | |
374 and @code{dayname} match the month number, day number, year number, | |
375 month name, and day name of the date being considered. The symbols that | |
376 match numbers allow leading zeros; those that match names allow | |
377 three-letter abbreviations and capitalization. All the symbols can | |
378 match @samp{*}; since @samp{*} in a diary entry means ``any day'', ``any | |
379 month'', and so on, it should match regardless of the date being | |
380 considered. | |
381 | |
382 The default value of @code{diary-date-forms} in the American style is | |
383 this: | |
384 | |
385 @example | |
386 ((month "/" day "[^/0-9]") | |
387 (month "/" day "/" year "[^0-9]") | |
388 (monthname " *" day "[^,0-9]") | |
389 (monthname " *" day ", *" year "[^0-9]") | |
390 (dayname "\\W")) | |
391 @end example | |
392 | |
393 The date patterns in the list must be @emph{mutually exclusive} and | |
394 must not match any portion of the diary entry itself, just the date and | |
395 one character of whitespace. If, to be mutually exclusive, the pattern | |
396 must match a portion of the diary entry text---beyond the whitespace | |
397 that ends the date---then the first element of the date pattern | |
398 @emph{must} be @code{backup}. This causes the date recognizer to back | |
399 up to the beginning of the current word of the diary entry, after | |
400 finishing the match. Even if you use @code{backup}, the date pattern | |
401 must absolutely not match more than a portion of the first word of the | |
402 diary entry. The default value of @code{diary-date-forms} in the | |
403 European style is this list: | |
404 | |
405 @example | |
406 ((day "/" month "[^/0-9]") | |
407 (day "/" month "/" year "[^0-9]") | |
408 (backup day " *" monthname "\\W+\\<[^*0-9]") | |
409 (day " *" monthname " *" year "[^0-9]") | |
410 (dayname "\\W")) | |
411 @end example | |
412 | |
413 @noindent | |
414 Notice the use of @code{backup} in the third pattern, because it needs | |
415 to match part of a word beyond the date itself to distinguish it from | |
416 the fourth pattern. | |
417 | |
418 @node Hebrew/Islamic Entries | |
419 @subsection Hebrew- and Islamic-Date Diary Entries | |
420 | |
421 Your diary file can have entries based on Hebrew or Islamic dates, as | |
422 well as entries based on the world-standard Gregorian calendar. | |
423 However, because recognition of such entries is time-consuming and most | |
424 people don't use them, you must explicitly enable their use. If you | |
425 want the diary to recognize Hebrew-date diary entries, for example, | |
426 you must do this: | |
427 | |
428 @vindex nongregorian-diary-listing-hook | |
429 @vindex nongregorian-diary-marking-hook | |
430 @findex list-hebrew-diary-entries | |
431 @findex mark-hebrew-diary-entries | |
432 @smallexample | |
433 (add-hook 'nongregorian-diary-listing-hook 'list-hebrew-diary-entries) | |
434 (add-hook 'nongregorian-diary-marking-hook 'mark-hebrew-diary-entries) | |
435 @end smallexample | |
436 | |
437 @noindent | |
438 If you want Islamic-date entries, do this: | |
439 | |
440 @findex list-islamic-diary-entries | |
441 @findex mark-islamic-diary-entries | |
442 @smallexample | |
443 (add-hook 'nongregorian-diary-listing-hook 'list-islamic-diary-entries) | |
444 (add-hook 'nongregorian-diary-marking-hook 'mark-islamic-diary-entries) | |
445 @end smallexample | |
446 | |
447 Hebrew- and Islamic-date diary entries have the same formats as | |
448 Gregorian-date diary entries, except that @samp{H} precedes a Hebrew | |
449 date and @samp{I} precedes an Islamic date. Moreover, because the | |
450 Hebrew and Islamic month names are not uniquely specified by the first | |
451 three letters, you may not abbreviate them. For example, a diary entry | |
452 for the Hebrew date Heshvan 25 could look like this: | |
453 | |
454 @smallexample | |
455 HHeshvan 25 Happy Hebrew birthday! | |
456 @end smallexample | |
457 | |
458 @noindent | |
459 and would appear in the diary for any date that corresponds to Heshvan 25 | |
460 on the Hebrew calendar. And here is an Islamic-date diary entry that matches | |
461 Dhu al-Qada 25: | |
462 | |
463 @smallexample | |
464 IDhu al-Qada 25 Happy Islamic birthday! | |
465 @end smallexample | |
466 | |
467 As with Gregorian-date diary entries, Hebrew- and Islamic-date entries | |
468 are nonmarking if they are preceded with an ampersand (@samp{&}). | |
469 | |
470 Here is a table of commands used in the calendar to create diary entries | |
471 that match the selected date and other dates that are similar in the Hebrew | |
472 or Islamic calendar: | |
473 | |
474 @table @kbd | |
475 @item i h d | |
476 Add a diary entry for the Hebrew date corresponding to the selected date | |
477 (@code{insert-hebrew-diary-entry}). | |
478 @item i h m | |
479 Add a diary entry for the day of the Hebrew month corresponding to the | |
480 selected date (@code{insert-monthly-hebrew-diary-entry}). This diary | |
481 entry matches any date that has the same Hebrew day-within-month as the | |
482 selected date. | |
483 @item i h y | |
484 Add a diary entry for the day of the Hebrew year corresponding to the | |
485 selected date (@code{insert-yearly-hebrew-diary-entry}). This diary | |
486 entry matches any date which has the same Hebrew month and day-within-month | |
487 as the selected date. | |
488 @item i i d | |
489 Add a diary entry for the Islamic date corresponding to the selected date | |
490 (@code{insert-islamic-diary-entry}). | |
491 @item i i m | |
492 Add a diary entry for the day of the Islamic month corresponding to the | |
493 selected date (@code{insert-monthly-islamic-diary-entry}). | |
494 @item i i y | |
495 Add a diary entry for the day of the Islamic year corresponding to the | |
496 selected date (@code{insert-yearly-islamic-diary-entry}). | |
497 @end table | |
498 | |
499 @findex insert-hebrew-diary-entry | |
500 @findex insert-monthly-hebrew-diary-entry | |
501 @findex insert-yearly-hebrew-diary-entry | |
502 @findex insert-islamic-diary-entry | |
503 @findex insert-monthly-islamic-diary-entry | |
504 @findex insert-yearly-islamic-diary-entry | |
505 These commands work much like the corresponding commands for ordinary | |
506 diary entries: they apply to the date that point is on in the calendar | |
507 window, and what they do is insert just the date portion of a diary entry | |
508 at the end of your diary file. You must then insert the rest of the | |
509 diary entry. | |
510 | |
511 @node Fancy Diary Display | |
512 @subsection Fancy Diary Display | |
513 @vindex diary-display-hook | |
514 @findex simple-diary-display | |
515 | |
516 Diary display works by preparing the diary buffer and then running the | |
517 hook @code{diary-display-hook}. The default value of this hook | |
518 (@code{simple-diary-display}) hides the irrelevant diary entries and | |
519 then displays the buffer. However, if you specify the hook as follows, | |
520 | |
521 @cindex diary buffer | |
522 @findex fancy-diary-display | |
523 @example | |
524 (add-hook 'diary-display-hook 'fancy-diary-display) | |
525 @end example | |
526 | |
527 @noindent | |
528 this enables fancy diary display. It displays diary entries and | |
529 holidays by copying them into a special buffer that exists only for the | |
530 sake of display. Copying to a separate buffer provides an opportunity | |
531 to change the displayed text to make it prettier---for example, to sort | |
532 the entries by the dates they apply to. | |
533 | |
534 As with simple diary display, you can print a hard copy of the buffer | |
535 with @code{print-diary-entries}. To print a hard copy of a day-by-day | |
536 diary for a week, position point on Sunday of that week, type | |
537 @kbd{7 d}, and then do @kbd{M-x print-diary-entries}. As usual, the | |
538 inclusion of the holidays slows down the display slightly; you can speed | |
539 things up by setting the variable @code{holidays-in-diary-buffer} to | |
540 @code{nil}. | |
541 | |
542 @vindex diary-list-include-blanks | |
543 Ordinarily, the fancy diary buffer does not show days for which there are | |
544 no diary entries, even if that day is a holiday. If you want such days to be | |
545 shown in the fancy diary buffer, set the variable | |
546 @code{diary-list-include-blanks} to @code{t}.@refill | |
547 | |
548 @cindex sorting diary entries | |
549 If you use the fancy diary display, you can use the normal hook | |
550 @code{list-diary-entries-hook} to sort each day's diary entries by their | |
551 time of day. Here's how: | |
552 | |
553 @findex sort-diary-entries | |
554 @example | |
555 (add-hook 'list-diary-entries-hook 'sort-diary-entries t) | |
556 @end example | |
557 | |
558 @noindent | |
559 For each day, this sorts diary entries that begin with a recognizable | |
560 time of day according to their times. Diary entries without times come | |
561 first within each day. | |
562 | |
563 Fancy diary display also has the ability to process included diary | |
564 files. This permits a group of people to share a diary file for events | |
565 that apply to all of them. Lines in the diary file of this form: | |
566 | |
567 @smallexample | |
568 #include "@var{filename}" | |
569 @end smallexample | |
570 | |
571 @noindent | |
572 includes the diary entries from the file @var{filename} in the fancy | |
573 diary buffer. The include mechanism is recursive, so that included files | |
574 can include other files, and so on; you must be careful not to have a | |
575 cycle of inclusions, of course. Here is how to enable the include | |
576 facility: | |
577 | |
578 @vindex list-diary-entries-hook | |
579 @vindex mark-diary-entries-hook | |
580 @findex include-other-diary-files | |
581 @findex mark-included-diary-files | |
582 @smallexample | |
583 (add-hook 'list-diary-entries-hook 'include-other-diary-files) | |
584 (add-hook 'mark-diary-entries-hook 'mark-included-diary-files) | |
585 @end smallexample | |
586 | |
587 The include mechanism works only with the fancy diary display, because | |
588 ordinary diary display shows the entries directly from your diary file. | |
589 | |
590 @node Sexp Diary Entries | |
591 @subsection Sexp Entries and the Fancy Diary Display | |
592 @cindex sexp diary entries | |
593 | |
594 Sexp diary entries allow you to do more than just have complicated | |
595 conditions under which a diary entry applies. If you use the fancy | |
596 diary display, sexp entries can generate the text of the entry depending | |
597 on the date itself. For example, an anniversary diary entry can insert | |
598 the number of years since the anniversary date into the text of the | |
599 diary entry. Thus the @samp{%d} in this dairy entry: | |
600 | |
601 @findex diary-anniversary | |
602 @smallexample | |
603 %%(diary-anniversary 10 31 1948) Arthur's birthday (%d years old) | |
604 @end smallexample | |
605 | |
606 @noindent | |
607 gets replaced by the age, so on October 31, 1990 the entry appears in | |
608 the fancy diary buffer like this: | |
609 | |
610 @smallexample | |
611 Arthur's birthday (42 years old) | |
612 @end smallexample | |
613 | |
614 @noindent | |
615 If the diary file instead contains this entry: | |
616 | |
617 @smallexample | |
618 %%(diary-anniversary 10 31 1948) Arthur's %d%s birthday | |
619 @end smallexample | |
620 | |
621 @noindent | |
622 the entry in the fancy diary buffer for October 31, 1990 appears like this: | |
623 | |
624 @smallexample | |
625 Arthur's 42nd birthday | |
626 @end smallexample | |
627 | |
628 Similarly, cyclic diary entries can interpolate the number of repetitions | |
629 that have occurred: | |
630 | |
631 @findex diary-cyclic | |
632 @smallexample | |
633 %%(diary-cyclic 50 1 1 1990) Renew medication (%d%s time) | |
634 @end smallexample | |
635 | |
636 @noindent | |
637 looks like this: | |
638 | |
639 @smallexample | |
640 Renew medication (5th time) | |
641 @end smallexample | |
642 | |
643 @noindent | |
644 in the fancy diary display on September 8, 1990. | |
645 | |
646 There is an early reminder diary sexp that includes its entry in the | |
647 diary not only on the date of occurrence, but also on earlier dates. | |
648 For example, if you want a reminder a week before your anniversary, you | |
649 can use | |
650 | |
651 @findex diary-remind | |
652 @smallexample | |
653 %%(diary-remind '(diary-anniversary 12 22 1968) 7) Ed's anniversary | |
654 @end smallexample | |
655 | |
656 @noindent | |
657 and the fancy diary will show | |
658 @smallexample | |
659 Ed's anniversary | |
660 @end smallexample | |
661 @noindent | |
662 both on December 15 and on December 22. | |
663 | |
664 @findex diary-date | |
665 The function @code{diary-date} applies to dates described by a month, | |
666 day, year combination, each of which can be an integer, a list of | |
667 integers, or @code{t}. The value @code{t} means all values. For | |
668 example, | |
669 | |
670 @smallexample | |
671 %%(diary-date '(10 11 12) 22 t) Rake leaves | |
672 @end smallexample | |
673 | |
674 @noindent | |
675 causes the fancy diary to show | |
676 | |
677 @smallexample | |
678 Rake leaves | |
679 @end smallexample | |
680 | |
681 @noindent | |
682 on October 22, November 22, and December 22 of every year. | |
683 | |
684 @findex diary-float | |
685 The function @code{diary-float} allows you to describe diary entries | |
686 that apply to dates like the third Friday of November, or the last | |
687 Tuesday in April. The parameters are the @var{month}, @var{dayname}, | |
688 and an index @var{n}. The entry appears on the @var{n}th @var{dayname} | |
689 of @var{month}, where @var{dayname}=0 means Sunday, 1 means Monday, and | |
690 so on. If @var{n} is negative it counts backward from the end of | |
691 @var{month}. The value of @var{month} can be a list of months, a single | |
692 month, or @code{t} to specify all months. You can also use an optional | |
693 parameter @var{day} to specify the @var{n}th @var{dayname} of | |
694 @var{month} on or after/before @var{day}; the value of @var{day} defaults | |
695 to 1 if @var{n} is positive and to the last day of @var{month} if | |
696 @var{n} is negative. For example, | |
697 | |
698 @smallexample | |
699 %%(diary-float t 1 -1) Pay rent | |
700 @end smallexample | |
701 | |
702 @noindent | |
703 causes the fancy diary to show | |
704 | |
705 @smallexample | |
706 Pay rent | |
707 @end smallexample | |
708 | |
709 @noindent | |
710 on the last Monday of every month. | |
711 | |
712 The generality of sexp diary entries lets you specify any diary | |
713 entry that you can describe algorithmically. A sexp diary entry | |
714 contains an expression that computes whether the entry applies to any | |
715 given date. If its value is non-@code{nil}, the entry applies to that | |
716 date; otherwise, it does not. The expression can use the variable | |
717 @code{date} to find the date being considered; its value is a list | |
718 (@var{month} @var{day} @var{year}) that refers to the Gregorian | |
719 calendar. | |
720 | |
721 The sexp diary entry applies to a date when the expression's value | |
722 is non-@code{nil}, but some values have more specific meanings. If | |
723 the value is a string, that string is a description of the event which | |
724 occurs on that date. The value can also have the form | |
725 @code{(@var{mark} . @var{string})}; then @var{mark} specifies how to | |
726 mark the date in the calendar, and @var{string} is the description of | |
727 the event. If @var{mark} is a single-character string, that character | |
728 appears next to the date in the calendar. If @var{mark} is a face | |
729 name, the date is displayed in that face. If @var{mark} is | |
730 @code{nil}, that specifies no particular highlighting for the date. | |
731 | |
732 Suppose you get paid on the 21st of the month if it is a weekday, and | |
733 on the Friday before if the 21st is on a weekend. Here is how to write | |
734 a sexp diary entry that matches those dates: | |
735 | |
736 @smallexample | |
737 &%%(let ((dayname (calendar-day-of-week date)) | |
738 (day (car (cdr date)))) | |
739 (or (and (= day 21) (memq dayname '(1 2 3 4 5))) | |
740 (and (memq day '(19 20)) (= dayname 5))) | |
741 ) Pay check deposited | |
742 @end smallexample | |
743 | |
744 The following sexp diary entries take advantage of the ability (in the fancy | |
745 diary display) to concoct diary entries whose text varies based on the date: | |
746 | |
747 @findex diary-sunrise-sunset | |
748 @findex diary-phases-of-moon | |
749 @findex diary-day-of-year | |
750 @findex diary-iso-date | |
751 @findex diary-julian-date | |
752 @findex diary-astro-day-number | |
753 @findex diary-hebrew-date | |
754 @findex diary-islamic-date | |
755 @findex diary-french-date | |
756 @findex diary-mayan-date | |
757 @table @code | |
758 @item %%(diary-sunrise-sunset) | |
759 Make a diary entry for the local times of today's sunrise and sunset. | |
760 @item %%(diary-phases-of-moon) | |
761 Make a diary entry for the phases (quarters) of the moon. | |
762 @item %%(diary-day-of-year) | |
763 Make a diary entry with today's day number in the current year and the number | |
764 of days remaining in the current year. | |
765 @item %%(diary-iso-date) | |
766 Make a diary entry with today's equivalent ISO commercial date. | |
767 @item %%(diary-julian-date) | |
768 Make a diary entry with today's equivalent date on the Julian calendar. | |
769 @item %%(diary-astro-day-number) | |
770 Make a diary entry with today's equivalent astronomical (Julian) day number. | |
771 @item %%(diary-hebrew-date) | |
772 Make a diary entry with today's equivalent date on the Hebrew calendar. | |
773 @item %%(diary-islamic-date) | |
774 Make a diary entry with today's equivalent date on the Islamic calendar. | |
775 @item %%(diary-french-date) | |
776 Make a diary entry with today's equivalent date on the French Revolutionary | |
777 calendar. | |
778 @item %%(diary-mayan-date) | |
779 Make a diary entry with today's equivalent date on the Mayan calendar. | |
780 @end table | |
781 | |
782 @noindent | |
783 Thus including the diary entry | |
784 | |
785 @example | |
786 &%%(diary-hebrew-date) | |
787 @end example | |
788 | |
789 @noindent | |
790 causes every day's diary display to contain the equivalent date on the | |
791 Hebrew calendar, if you are using the fancy diary display. (With simple | |
792 diary display, the line @samp{&%%(diary-hebrew-date)} appears in the | |
793 diary for any date, but does nothing particularly useful.) | |
794 | |
795 These functions can be used to construct sexp diary entries based on | |
796 the Hebrew calendar in certain standard ways: | |
797 | |
798 @cindex rosh hodesh | |
799 @findex diary-rosh-hodesh | |
800 @cindex parasha, weekly | |
801 @findex diary-parasha | |
802 @cindex candle lighting times | |
803 @findex diary-sabbath-candles | |
804 @cindex omer count | |
805 @findex diary-omer | |
806 @cindex yahrzeits | |
807 @findex diary-yahrzeit | |
808 @table @code | |
809 @item %%(diary-rosh-hodesh) | |
810 Make a diary entry that tells the occurrence and ritual announcement of each | |
811 new Hebrew month. | |
812 @item %%(diary-parasha) | |
813 Make a Saturday diary entry that tells the weekly synagogue scripture reading. | |
814 @item %%(diary-sabbath-candles) | |
815 Make a Friday diary entry that tells the @emph{local time} of Sabbath | |
816 candle lighting. | |
817 @item %%(diary-omer) | |
818 Make a diary entry that gives the omer count, when appropriate. | |
819 @item %%(diary-yahrzeit @var{month} @var{day} @var{year}) @var{name} | |
820 Make a diary entry marking the anniversary of a date of death. The date | |
821 is the @emph{Gregorian} (civil) date of death. The diary entry appears | |
822 on the proper Hebrew calendar anniversary and on the day before. (In | |
823 the European style, the order of the parameters is changed to @var{day}, | |
824 @var{month}, @var{year}.) | |
825 @end table | |
826 | |
827 All the functions documented above take an optional argument | |
828 @var{mark} which specifies how to mark the date in the calendar display. | |
829 If one of these functions decides that it applies to a certain date, | |
830 it returns a value that contains @var{mark}. |