Commit | Line | Data |
---|---|---|
681ebc33 | 1 | @c This is part of the Emacs manual. -*- coding: utf-8 -*- |
ba318903 | 2 | @c Copyright (C) 2004-2014 Free Software Foundation, Inc. |
6f585e44 EZ |
3 | @c See file emacs.texi for copying conditions. |
4 | @c | |
c5184807 EZ |
5 | @c This file is included either in emacs-xtra.texi (when producing the |
6 | @c printed version) or in the main Emacs manual (for the on-line version). | |
7 | ||
8 | @c Moved here from the Emacs Lisp Reference Manual, 2005-03-26. | |
9 | @node Advanced Calendar/Diary Usage | |
4695c850 | 10 | @section More advanced features of the Calendar and Diary |
c5184807 | 11 | |
4695c850 GM |
12 | This section describes some of the more advanced/specialized |
13 | features of the calendar and diary. It starts with some of the | |
14 | many ways in which you can customize the calendar and diary to suit | |
15 | your personal tastes. | |
c5184807 EZ |
16 | |
17 | @menu | |
f9b4c05d | 18 | * Calendar Customizing:: Calendar layout and hooks. |
c5184807 | 19 | * Holiday Customizing:: Defining your own holidays. |
65b36413 | 20 | * Mayan Calendar:: Moving to a date specified in a Mayan calendar. |
c5184807 EZ |
21 | * Date Display Format:: Changing the format. |
22 | * Time Display Format:: Changing the format. | |
23 | * Diary Customizing:: Defaults you can set. | |
f9b4c05d | 24 | * Non-Gregorian Diary:: Diary entries based on other calendars. |
cad04c66 GM |
25 | * Diary Display:: A choice of ways to display the diary. |
26 | * Fancy Diary Display:: Sorting diary entries, using included diary files. | |
27 | * Sexp Diary Entries:: More flexible diary entries. | |
c5184807 EZ |
28 | @end menu |
29 | ||
30 | @node Calendar Customizing | |
31 | @subsection Customizing the Calendar | |
a43a8a2e GM |
32 | |
33 | @vindex calendar-intermonth-text | |
34 | @cindex calendar layout | |
f9b4c05d GM |
35 | @cindex calendar week numbers |
36 | The calendar display unfortunately cannot be changed from three | |
37 | months, but you can customize the whitespace used by setting the | |
38 | variables: @code{calendar-left-margin}, | |
c1e67aad GM |
39 | @code{calendar-day-header-width}, @code{calendar-day-digit-width}, |
40 | @code{calendar-column-width}, and @code{calendar-intermonth-spacing}. | |
f9b4c05d GM |
41 | To display text @emph{between} the months, for example week numbers, |
42 | customize the variables @code{calendar-intermonth-header} and | |
43 | @code{calendar-intermonth-text} as described in their documentation. | |
a43a8a2e | 44 | |
cad4f290 | 45 | @vindex calendar-month-header |
11c06c77 | 46 | @vindex calendar-day-header-array |
cad4f290 GM |
47 | The variable @code{calendar-month-header} controls the text that |
48 | appears above each month in the calendar. By default, it shows the | |
11c06c77 GM |
49 | month and year. The variable @code{calendar-day-header-array} |
50 | controls the text that appears above each day's column in every month. | |
51 | By default, it shows the first two letters of each day's name. | |
cad4f290 | 52 | |
c5184807 EZ |
53 | @vindex calendar-holiday-marker |
54 | @vindex diary-entry-marker | |
301b181a | 55 | @vindex calendar-today-marker |
c5184807 | 56 | The variable @code{calendar-holiday-marker} specifies how to mark a |
a5987767 | 57 | date that is a holiday. Its value may be a single-character string to |
f9b4c05d GM |
58 | insert next to the date, or a face name to use for displaying the date. |
59 | Likewise, the variable @code{diary-entry-marker} specifies how to mark a | |
a5987767 GM |
60 | date that has diary entries. The function @code{calendar-mark-today} |
61 | uses @code{calendar-today-marker} to mark today's date. By default, | |
62 | the calendar uses faces named @code{holiday}, @code{diary}, and | |
f9b4c05d | 63 | @code{calendar-today} for these purposes. |
c5184807 EZ |
64 | |
65 | @vindex calendar-load-hook | |
66 | The variable @code{calendar-load-hook} is a normal hook run when the | |
67 | calendar package is first loaded (before actually starting to display | |
68 | the calendar). | |
69 | ||
36c0514c | 70 | @vindex calendar-initial-window-hook |
c5184807 | 71 | Starting the calendar runs the normal hook |
36c0514c | 72 | @code{calendar-initial-window-hook}. Recomputation of the calendar |
c5184807 | 73 | display does not run this hook. But if you leave the calendar with the |
9548391c | 74 | @kbd{q} command and reenter it, the hook runs again. |
c5184807 | 75 | |
36c0514c | 76 | @vindex calendar-today-visible-hook |
f9b4c05d | 77 | @findex calendar-star-date |
36c0514c | 78 | The variable @code{calendar-today-visible-hook} is a normal hook run |
a5987767 | 79 | after the calendar buffer has been prepared with the calendar, when the |
c5184807 | 80 | current date is visible in the window. One use of this hook is to |
f9b4c05d GM |
81 | mark today's date; to do that use either of the functions |
82 | @code{calendar-mark-today} or @code{calendar-star-date}: | |
c5184807 EZ |
83 | |
84 | @findex calendar-mark-today | |
f9b4c05d | 85 | @smallexample |
36c0514c | 86 | (add-hook 'calendar-today-visible-hook 'calendar-mark-today) |
f9b4c05d | 87 | @end smallexample |
c5184807 | 88 | |
36c0514c | 89 | @vindex calendar-today-invisible-hook |
c5184807 | 90 | @noindent |
36c0514c | 91 | A similar normal hook, @code{calendar-today-invisible-hook} is run if |
c5184807 EZ |
92 | the current date is @emph{not} visible in the window. |
93 | ||
94 | @vindex calendar-move-hook | |
95 | Each of the calendar cursor motion commands runs the hook | |
96 | @code{calendar-move-hook} after it moves the cursor. | |
97 | ||
98 | @node Holiday Customizing | |
99 | @subsection Customizing the Holidays | |
100 | ||
101 | @vindex calendar-holidays | |
f9b4c05d GM |
102 | @vindex holiday-oriental-holidays |
103 | @vindex holiday-solar-holidays | |
a5987767 GM |
104 | There are several variables listing the default holidays that Emacs |
105 | knows about. These are: @code{holiday-general-holidays}, | |
106 | @code{holiday-local-holidays}, @code{holiday-solar-holidays}, | |
107 | @code{holiday-bahai-holidays}, @code{holiday-christian-holidays}, | |
108 | @code{holiday-hebrew-holidays}, @code{holiday-islamic-holidays}, | |
109 | @code{holiday-oriental-holidays}, and @code{holiday-other-holidays}. | |
1df7defd | 110 | The names should be self-explanatory; e.g., @code{holiday-solar-holidays} |
a5987767 | 111 | lists sun- and moon-related holidays. |
36c0514c | 112 | |
f9b4c05d GM |
113 | You can customize these lists of holidays to your own needs, deleting or |
114 | adding holidays as described below. Set any of them to @code{nil} to | |
a5987767 | 115 | not show the associated holidays. |
f9b4c05d | 116 | |
36c0514c | 117 | @vindex holiday-general-holidays |
36c0514c | 118 | @vindex holiday-local-holidays |
a5987767 GM |
119 | @vindex holiday-other-holidays |
120 | The general holidays are, by default, holidays common throughout the | |
121 | United States. In contrast, @code{holiday-local-holidays} and | |
122 | @code{holiday-other-holidays} are both empty by default. These are | |
123 | intended for system-wide settings and your individual use, | |
124 | respectively. | |
c5184807 | 125 | |
f9b4c05d GM |
126 | @vindex holiday-bahai-holidays |
127 | @vindex holiday-christian-holidays | |
128 | @vindex holiday-hebrew-holidays | |
129 | @vindex holiday-islamic-holidays | |
36c0514c GM |
130 | @vindex calendar-bahai-all-holidays-flag |
131 | @vindex calendar-christian-all-holidays-flag | |
132 | @vindex calendar-hebrew-all-holidays-flag | |
133 | @vindex calendar-islamic-all-holidays-flag | |
c5184807 EZ |
134 | By default, Emacs does not include all the holidays of the religions |
135 | that it knows, only those commonly found in secular calendars. For a | |
136 | more extensive collection of religious holidays, you can set any (or | |
36c0514c GM |
137 | all) of the variables @code{calendar-bahai-all-holidays-flag}, |
138 | @code{calendar-christian-all-holidays-flag}, | |
139 | @code{calendar-hebrew-all-holidays-flag}, or | |
f9b4c05d | 140 | @code{calendar-islamic-all-holidays-flag} to @code{t}. |
c5184807 | 141 | |
c5184807 | 142 | @cindex holiday forms |
f9b4c05d | 143 | Each of the holiday variables is a list of @dfn{holiday forms}, each |
a5987767 GM |
144 | form describing a holiday (or sometimes a list of holidays). Here is |
145 | a table of the possible kinds of holiday form. Day numbers and month | |
146 | numbers count starting from 1, but ``dayname'' numbers count Sunday as | |
147 | 0. The argument @var{string} is always the description of the | |
148 | holiday, as a string. | |
c5184807 EZ |
149 | |
150 | @table @code | |
151 | @item (holiday-fixed @var{month} @var{day} @var{string}) | |
152 | A fixed date on the Gregorian calendar. | |
153 | ||
f9b4c05d GM |
154 | @item (holiday-float @var{month} @var{dayname} @var{k} @var{string} |
155 | &optional @var{day}) | |
156 | The @var{k}th @var{dayname} (@var{dayname}=0 for Sunday, and so on) | |
157 | after or before Gregorian date @var{month}, @var{day}. Negative @var{k} | |
158 | means count back from the end of the month. Optional @var{day} defaults | |
159 | to 1 if @var{k} is positive, and the last day of @var{month} otherwise. | |
c5184807 | 160 | |
a43a8a2e GM |
161 | @item (holiday-chinese @var{month} @var{day} @var{string}) |
162 | A fixed date on the Chinese calendar. | |
163 | ||
c5184807 EZ |
164 | @item (holiday-hebrew @var{month} @var{day} @var{string}) |
165 | A fixed date on the Hebrew calendar. | |
166 | ||
167 | @item (holiday-islamic @var{month} @var{day} @var{string}) | |
168 | A fixed date on the Islamic calendar. | |
169 | ||
170 | @item (holiday-julian @var{month} @var{day} @var{string}) | |
171 | A fixed date on the Julian calendar. | |
172 | ||
173 | @item (holiday-sexp @var{sexp} @var{string}) | |
174 | A date calculated by the Lisp expression @var{sexp}. The expression | |
175 | should use the variable @code{year} to compute and return the date of a | |
f9b4c05d GM |
176 | holiday in the form of a list @code{(@var{month} @var{day} @var{year})}, |
177 | or @code{nil} if the holiday doesn't happen this year. | |
c5184807 EZ |
178 | |
179 | @item (if @var{condition} @var{holiday-form}) | |
180 | A holiday that happens only if @var{condition} is true. | |
181 | ||
182 | @item (@var{function} @r{[}@var{args}@r{]}) | |
183 | A list of dates calculated by the function @var{function}, called with | |
184 | arguments @var{args}. | |
185 | @end table | |
186 | ||
187 | For example, suppose you want to add Bastille Day, celebrated in | |
f9b4c05d GM |
188 | France on July 14 (i.e., the fourteenth day of the seventh month). You |
189 | can do this as follows: | |
c5184807 EZ |
190 | |
191 | @smallexample | |
98ad1bae | 192 | (setq holiday-other-holidays '((holiday-fixed 7 14 "Bastille Day"))) |
c5184807 EZ |
193 | @end smallexample |
194 | ||
c5184807 EZ |
195 | Many holidays occur on a specific day of the week, at a specific time |
196 | of month. Here is a holiday form describing Hurricane Supplication Day, | |
197 | celebrated in the Virgin Islands on the fourth Monday in August: | |
198 | ||
199 | @smallexample | |
200 | (holiday-float 8 1 4 "Hurricane Supplication Day") | |
201 | @end smallexample | |
202 | ||
203 | @noindent | |
204 | Here the 8 specifies August, the 1 specifies Monday (Sunday is 0, | |
205 | Tuesday is 2, and so on), and the 4 specifies the fourth occurrence in | |
206 | the month (1 specifies the first occurrence, 2 the second occurrence, | |
207 | @minus{}1 the last occurrence, @minus{}2 the second-to-last occurrence, and | |
208 | so on). | |
209 | ||
681ebc33 | 210 | You can specify holidays that occur on fixed days of the Bahá'í, |
a43a8a2e | 211 | Chinese, Hebrew, Islamic, and Julian calendars too. For example, |
c5184807 EZ |
212 | |
213 | @smallexample | |
98ad1bae | 214 | (setq holiday-other-holidays |
c5184807 EZ |
215 | '((holiday-hebrew 10 2 "Last day of Hanukkah") |
216 | (holiday-islamic 3 12 "Mohammed's Birthday") | |
217 | (holiday-julian 4 2 "Jefferson's Birthday"))) | |
218 | @end smallexample | |
219 | ||
220 | @noindent | |
221 | adds the last day of Hanukkah (since the Hebrew months are numbered with | |
222 | 1 starting from Nisan), the Islamic feast celebrating Mohammed's | |
223 | birthday (since the Islamic months are numbered from 1 starting with | |
224 | Muharram), and Thomas Jefferson's birthday, which is 2 April 1743 on the | |
225 | Julian calendar. | |
226 | ||
f9b4c05d GM |
227 | To include a holiday conditionally, use either Emacs Lisp's @code{if} |
228 | or the @code{holiday-sexp} form. For example, American presidential | |
229 | elections occur on the first Tuesday after the first Monday in November | |
230 | of years divisible by 4: | |
c5184807 EZ |
231 | |
232 | @smallexample | |
f9b4c05d | 233 | (holiday-sexp '(if (zerop (% year 4)) |
c5184807 EZ |
234 | (calendar-gregorian-from-absolute |
235 | (1+ (calendar-dayname-on-or-before | |
236 | 1 (+ 6 (calendar-absolute-from-gregorian | |
237 | (list 11 1 year))))))) | |
238 | "US Presidential Election") | |
239 | @end smallexample | |
240 | ||
241 | @noindent | |
242 | or | |
243 | ||
244 | @smallexample | |
f9b4c05d GM |
245 | (if (zerop (% displayed-year 4)) |
246 | (holiday-fixed 11 | |
36c0514c | 247 | (calendar-extract-day |
c5184807 EZ |
248 | (calendar-gregorian-from-absolute |
249 | (1+ (calendar-dayname-on-or-before | |
250 | 1 (+ 6 (calendar-absolute-from-gregorian | |
251 | (list 11 1 displayed-year))))))) | |
252 | "US Presidential Election")) | |
253 | @end smallexample | |
254 | ||
255 | Some holidays just don't fit into any of these forms because special | |
256 | calculations are involved in their determination. In such cases you | |
257 | must write a Lisp function to do the calculation. To include eclipses, | |
36c0514c | 258 | for example, add @code{(eclipses)} to @code{holiday-other-holidays} |
c5184807 EZ |
259 | and write an Emacs Lisp function @code{eclipses} that returns a |
260 | (possibly empty) list of the relevant Gregorian dates among the range | |
261 | visible in the calendar window, with descriptive strings, like this: | |
262 | ||
263 | @smallexample | |
a5987767 | 264 | (((6 4 2012) "Lunar Eclipse") ((11 13 2012) "Solar Eclipse") ... ) |
c5184807 EZ |
265 | @end smallexample |
266 | ||
65b36413 XF |
267 | @node Mayan Calendar |
268 | @subsection Converting from the Mayan Calendar | |
269 | @cindex Mayan calendar | |
270 | ||
271 | Here are the commands to select dates based on the Mayan calendar: | |
272 | ||
273 | @table @kbd | |
274 | @item g m l | |
275 | Move to a date specified by the long count calendar | |
276 | (@code{calendar-mayan-goto-long-count-date}). | |
277 | @item g m n t | |
278 | Move to the next occurrence of a place in the | |
279 | tzolkin calendar (@code{calendar-mayan-next-tzolkin-date}). | |
280 | @item g m p t | |
281 | Move to the previous occurrence of a place in the | |
282 | tzolkin calendar (@code{calendar-mayan-previous-tzolkin-date}). | |
283 | @item g m n h | |
284 | Move to the next occurrence of a place in the | |
285 | haab calendar (@code{calendar-mayan-next-haab-date}). | |
286 | @item g m p h | |
287 | Move to the previous occurrence of a place in the | |
288 | haab calendar (@code{calendar-mayan-previous-haab-date}). | |
289 | @item g m n c | |
290 | Move to the next occurrence of a place in the | |
291 | calendar round (@code{calendar-mayan-next-calendar-round-date}). | |
292 | @item g m p c | |
293 | Move to the previous occurrence of a place in the | |
294 | calendar round (@code{calendar-mayan-previous-calendar-round-date}). | |
295 | @end table | |
296 | ||
297 | @cindex Mayan long count | |
298 | To understand these commands, you need to understand the Mayan calendars. | |
299 | The @dfn{long count} is a counting of days with these units: | |
300 | ||
301 | @display | |
302 | 1 kin = 1 day@ @ @ 1 uinal = 20 kin@ @ @ 1 tun = 18 uinal | |
303 | 1 katun = 20 tun@ @ @ 1 baktun = 20 katun | |
304 | @end display | |
305 | ||
306 | @kindex g m @r{(Calendar mode)} | |
307 | @findex calendar-mayan-goto-long-count-date | |
308 | @noindent | |
309 | Thus, the long count date 12.16.11.16.6 means 12 baktun, 16 katun, 11 | |
310 | tun, 16 uinal, and 6 kin. The Emacs calendar can handle Mayan long | |
311 | count dates as early as 7.17.18.13.3, but no earlier. When you use the | |
312 | @kbd{g m l} command, type the Mayan long count date with the baktun, | |
313 | katun, tun, uinal, and kin separated by periods. | |
314 | ||
315 | @findex calendar-mayan-previous-tzolkin-date | |
316 | @findex calendar-mayan-next-tzolkin-date | |
317 | @cindex Mayan tzolkin calendar | |
318 | The Mayan tzolkin calendar is a cycle of 260 days formed by a pair of | |
319 | independent cycles of 13 and 20 days. Since this cycle repeats | |
320 | endlessly, Emacs provides commands to move backward and forward to the | |
321 | previous or next point in the cycle. Type @kbd{g m p t} to go to the | |
322 | previous tzolkin date; Emacs asks you for a tzolkin date and moves point | |
323 | to the previous occurrence of that date. Similarly, type @kbd{g m n t} | |
324 | to go to the next occurrence of a tzolkin date. | |
325 | ||
326 | @findex calendar-mayan-previous-haab-date | |
327 | @findex calendar-mayan-next-haab-date | |
328 | @cindex Mayan haab calendar | |
329 | The Mayan haab calendar is a cycle of 365 days arranged as 18 months | |
330 | of 20 days each, followed by a 5-day monthless period. Like the tzolkin | |
331 | cycle, this cycle repeats endlessly, and there are commands to move | |
332 | backward and forward to the previous or next point in the cycle. Type | |
333 | @kbd{g m p h} to go to the previous haab date; Emacs asks you for a haab | |
334 | date and moves point to the previous occurrence of that date. | |
335 | Similarly, type @kbd{g m n h} to go to the next occurrence of a haab | |
336 | date. | |
337 | ||
338 | @c This is omitted because it is too long for smallbook format. | |
339 | @c @findex calendar-mayan-previous-calendar-round-date | |
340 | @findex calendar-mayan-next-calendar-round-date | |
341 | @cindex Mayan calendar round | |
342 | The Maya also used the combination of the tzolkin date and the haab | |
343 | date. This combination is a cycle of about 52 years called a | |
344 | @emph{calendar round}. If you type @kbd{g m p c}, Emacs asks you for | |
345 | both a haab and a tzolkin date and then moves point to the previous | |
346 | occurrence of that combination. Use @kbd{g m n c} to move point to the | |
347 | next occurrence of a combination. These commands signal an error if the | |
348 | haab/tzolkin date combination you have typed is impossible. | |
349 | ||
350 | Emacs uses strict completion | |
351 | @iftex | |
352 | (@pxref{Completion Exit,,, emacs, the Emacs Manual}) | |
353 | @end iftex | |
354 | @ifnottex | |
355 | (@pxref{Completion Exit}) | |
356 | @end ifnottex | |
357 | whenever it asks you to type a Mayan name, so you don't have to worry | |
358 | about spelling. | |
359 | ||
c5184807 EZ |
360 | @node Date Display Format |
361 | @subsection Date Display Format | |
362 | @vindex calendar-date-display-form | |
363 | ||
a5987767 GM |
364 | You can customize the way dates are displayed in the diary, mode |
365 | lines, and messages by setting @code{calendar-date-display-form}. | |
c5184807 EZ |
366 | This variable holds a list of expressions that can involve the variables |
367 | @code{month}, @code{day}, and @code{year}, which are all numbers in | |
368 | string form, and @code{monthname} and @code{dayname}, which are both | |
369 | alphabetic strings. In the American style, the default value of this | |
370 | list is as follows: | |
371 | ||
372 | @smallexample | |
373 | ((if dayname (concat dayname ", ")) monthname " " day ", " year) | |
374 | @end smallexample | |
375 | ||
376 | @noindent | |
377 | while in the European style this value is the default: | |
378 | ||
379 | @smallexample | |
380 | ((if dayname (concat dayname ", ")) day " " monthname " " year) | |
381 | @end smallexample | |
382 | ||
383 | @noindent | |
f9b4c05d | 384 | The default ISO date representation is: |
c5184807 EZ |
385 | |
386 | @smallexample | |
f9b4c05d GM |
387 | ((format "%s-%.2d-%.2d" year (string-to-number month) |
388 | (string-to-number day))) | |
c5184807 EZ |
389 | @end smallexample |
390 | ||
391 | @noindent | |
a5987767 | 392 | Another typical American format is: |
c5184807 EZ |
393 | |
394 | @smallexample | |
395 | (month "/" day "/" (substring year -2)) | |
396 | @end smallexample | |
397 | ||
398 | @node Time Display Format | |
399 | @subsection Time Display Format | |
400 | @vindex calendar-time-display-form | |
401 | ||
402 | The calendar and diary by default display times of day in the | |
403 | conventional American style with the hours from 1 through 12, minutes, | |
404 | and either @samp{am} or @samp{pm}. If you prefer the European style, | |
405 | also known in the US as military, in which the hours go from 00 to 23, | |
406 | you can alter the variable @code{calendar-time-display-form}. This | |
407 | variable is a list of expressions that can involve the variables | |
408 | @code{12-hours}, @code{24-hours}, and @code{minutes}, which are all | |
409 | numbers in string form, and @code{am-pm} and @code{time-zone}, which are | |
f9b4c05d | 410 | both alphabetic strings. The default value is: |
c5184807 EZ |
411 | |
412 | @smallexample | |
413 | (12-hours ":" minutes am-pm | |
414 | (if time-zone " (") time-zone (if time-zone ")")) | |
415 | @end smallexample | |
416 | ||
417 | @noindent | |
418 | Here is a value that provides European style times: | |
419 | ||
420 | @smallexample | |
421 | (24-hours ":" minutes | |
422 | (if time-zone " (") time-zone (if time-zone ")")) | |
423 | @end smallexample | |
424 | ||
f9b4c05d GM |
425 | Note that few calendar functions return a time of day (at present, only |
426 | solar functions). | |
427 | ||
c5184807 EZ |
428 | @node Diary Customizing |
429 | @subsection Customizing the Diary | |
430 | ||
36c0514c | 431 | @vindex diary-show-holidays-flag |
cad04c66 GM |
432 | Ordinarily, the diary window indicates any holidays that fall on the |
433 | date of the diary entries, either in the mode line or the buffer itself. | |
434 | The process of checking for holidays can be slow, depending on the | |
435 | defined holidays. In that case, setting @code{diary-show-holidays-flag} | |
436 | to @code{nil} will speed up the diary display. | |
c5184807 | 437 | |
36c0514c GM |
438 | @vindex diary-number-of-entries |
439 | The variable @code{diary-number-of-entries} controls the number of | |
c5184807 | 440 | days of diary entries to be displayed at one time. It affects the |
36c0514c | 441 | initial display when @code{calendar-view-diary-initially-flag} is |
f9b4c05d GM |
442 | @code{t}, as well as the command @kbd{M-x diary}. For example, a value |
443 | of 1 (the default) displays only the current day's diary entries, | |
444 | whereas a value of 2 will also show the next day's entries. The value | |
445 | can also be a vector of seven integers: for example, if the value is | |
446 | @code{[0 2 2 2 2 4 1]} then no diary entries appear on Sunday, the | |
447 | current date's and the next day's diary entries appear Monday through | |
448 | Thursday, Friday through Monday's entries appear on Friday, while on | |
449 | Saturday only that day's entries appear. | |
36c0514c | 450 | |
c5184807 | 451 | @vindex diary-date-forms |
f9b4c05d | 452 | You can customize the form of dates in your diary file by setting the |
c5184807 EZ |
453 | variable @code{diary-date-forms}. This variable is a list of patterns |
454 | for recognizing a date. Each date pattern is a list whose elements may | |
455 | be regular expressions (@pxref{Regular Expressions,,, elisp, the Emacs | |
456 | Lisp Reference Manual}) or the symbols @code{month}, @code{day}, | |
457 | @code{year}, @code{monthname}, and @code{dayname}. All these elements | |
458 | serve as patterns that match certain kinds of text in the diary file. | |
a5987767 | 459 | In order for the date pattern as a whole to match, all of its elements |
c5184807 EZ |
460 | must match consecutively. |
461 | ||
462 | A regular expression in a date pattern matches in its usual fashion, | |
463 | using the standard syntax table altered so that @samp{*} is a word | |
464 | constituent. | |
465 | ||
466 | The symbols @code{month}, @code{day}, @code{year}, @code{monthname}, | |
467 | and @code{dayname} match the month number, day number, year number, | |
468 | month name, and day name of the date being considered. The symbols that | |
469 | match numbers allow leading zeros; those that match names allow | |
f9b4c05d GM |
470 | capitalization and abbreviation (as specified by |
471 | @code{calendar-month-abbrev-array} and | |
472 | @code{calendar-day-abbrev-array}). All the symbols can match @samp{*}; | |
473 | since @samp{*} in a diary entry means ``any day'', ``any month'', and so | |
474 | on, it should match regardless of the date being considered. | |
c5184807 EZ |
475 | |
476 | The default value of @code{diary-date-forms} in the American style is | |
f9b4c05d | 477 | provided by @code{diary-american-date-forms}: |
c5184807 EZ |
478 | |
479 | @example | |
480 | ((month "/" day "[^/0-9]") | |
481 | (month "/" day "/" year "[^0-9]") | |
482 | (monthname " *" day "[^,0-9]") | |
483 | (monthname " *" day ", *" year "[^0-9]") | |
484 | (dayname "\\W")) | |
485 | @end example | |
486 | ||
f9b4c05d | 487 | @noindent |
a5987767 GM |
488 | The variables @code{diary-european-date-forms} and |
489 | @code{diary-iso-date-forms} provide other default styles. | |
f9b4c05d | 490 | |
c5184807 EZ |
491 | The date patterns in the list must be @emph{mutually exclusive} and |
492 | must not match any portion of the diary entry itself, just the date and | |
493 | one character of whitespace. If, to be mutually exclusive, the pattern | |
494 | must match a portion of the diary entry text---beyond the whitespace | |
495 | that ends the date---then the first element of the date pattern | |
496 | @emph{must} be @code{backup}. This causes the date recognizer to back | |
497 | up to the beginning of the current word of the diary entry, after | |
498 | finishing the match. Even if you use @code{backup}, the date pattern | |
499 | must absolutely not match more than a portion of the first word of the | |
f9b4c05d GM |
500 | diary entry. For example, the default value of |
501 | @code{diary-european-date-forms} is: | |
c5184807 EZ |
502 | |
503 | @example | |
504 | ((day "/" month "[^/0-9]") | |
505 | (day "/" month "/" year "[^0-9]") | |
f9b4c05d | 506 | (backup day " *" monthname "\\W+\\<\\([^*0-9]\\|\\([0-9]+[:aApP]\\)\\)") |
c5184807 EZ |
507 | (day " *" monthname " *" year "[^0-9]") |
508 | (dayname "\\W")) | |
509 | @end example | |
510 | ||
511 | @noindent | |
512 | Notice the use of @code{backup} in the third pattern, because it needs | |
513 | to match part of a word beyond the date itself to distinguish it from | |
514 | the fourth pattern. | |
515 | ||
f9b4c05d | 516 | @node Non-Gregorian Diary |
c216ec2b | 517 | @subsection Diary Entries Using non-Gregorian Calendars |
c5184807 | 518 | |
f9b4c05d | 519 | As well as entries based on the standard Gregorian calendar, your |
bbdcf64f | 520 | diary can have entries based on Bahá'í, Chinese, Hebrew, or Islamic dates. |
f9b4c05d GM |
521 | Recognition of such entries can be time-consuming, however, and since |
522 | most people don't use them, you must explicitly enable their use. If | |
523 | you want the diary to recognize Hebrew-date diary entries, for example, | |
524 | you must do this: | |
36c0514c GM |
525 | |
526 | @vindex diary-nongregorian-listing-hook | |
527 | @vindex diary-nongregorian-marking-hook | |
528 | @findex diary-hebrew-list-entries | |
529 | @findex diary-hebrew-mark-entries | |
f9b4c05d GM |
530 | @findex diary-islamic-list-entries |
531 | @findex diary-islamic-mark-entries | |
532 | @findex diary-bahai-list-entries | |
533 | @findex diary-bahai-mark-entries | |
bbdcf64f LL |
534 | @findex diary-chinese-list-entries |
535 | @findex diary-chinese-mark-entries | |
c5184807 | 536 | @smallexample |
36c0514c GM |
537 | (add-hook 'diary-nongregorian-listing-hook 'diary-hebrew-list-entries) |
538 | (add-hook 'diary-nongregorian-marking-hook 'diary-hebrew-mark-entries) | |
c5184807 EZ |
539 | @end smallexample |
540 | ||
541 | @noindent | |
bbdcf64f LL |
542 | Similarly, for Islamic, Bahá'í and Chinese entries, add |
543 | @code{diary-islamic-list-entries} and @code{diary-islamic-mark-entries}, | |
544 | @code{diary-bahai-list-entries} and @code{diary-bahai-mark-entries}, | |
545 | or @code{diary-chinese-list-entries} and @code{diary-chinese-mark-entries}. | |
f9b4c05d GM |
546 | |
547 | @vindex diary-bahai-entry-symbol | |
bbdcf64f | 548 | @vindex diary-chinese-entry-symbol |
f9b4c05d GM |
549 | @vindex diary-hebrew-entry-symbol |
550 | @vindex diary-islamic-entry-symbol | |
551 | These diary entries have the same formats as Gregorian-date diary | |
552 | entries; except that @code{diary-bahai-entry-symbol} (default @samp{B}) | |
bbdcf64f LL |
553 | must precede a Bahá'í date, @code{diary-chinese-entry-symbol} (default |
554 | @samp{C}) a Chinese date, @code{diary-hebrew-entry-symbol} (default | |
f9b4c05d GM |
555 | @samp{H}) a Hebrew date, and @code{diary-islamic-entry-symbol} (default |
556 | @samp{I}) an Islamic date. Moreover, non-Gregorian month names may not | |
557 | be abbreviated (because the first three letters are often not unique). | |
fb89fad9 GM |
558 | (Note also that you must use ``Adar I'' if you want Adar of a common |
559 | Hebrew year.) For example, a diary entry for the Hebrew date Heshvan 25 | |
560 | could look like this: | |
c5184807 EZ |
561 | |
562 | @smallexample | |
563 | HHeshvan 25 Happy Hebrew birthday! | |
564 | @end smallexample | |
565 | ||
566 | @noindent | |
567 | and would appear in the diary for any date that corresponds to Heshvan 25 | |
568 | on the Hebrew calendar. And here is an Islamic-date diary entry that matches | |
569 | Dhu al-Qada 25: | |
570 | ||
571 | @smallexample | |
572 | IDhu al-Qada 25 Happy Islamic birthday! | |
573 | @end smallexample | |
574 | ||
f9b4c05d GM |
575 | As with Gregorian-date diary entries, non-Gregorian entries are |
576 | nonmarking if preceded by @code{diary-nonmarking-symbol} (default | |
577 | @samp{&}). | |
c5184807 | 578 | |
f9b4c05d GM |
579 | Here is a table of commands used in the calendar to create diary |
580 | entries that match the selected date and other dates that are similar in | |
bbdcf64f | 581 | the Bahá'í, Chinese, Hebrew, or Islamic calendars: |
c5184807 EZ |
582 | |
583 | @table @kbd | |
584 | @item i h d | |
f9b4c05d | 585 | @code{diary-hebrew-insert-entry} |
c5184807 | 586 | @item i h m |
f9b4c05d | 587 | @code{diary-hebrew-insert-monthly-entry} |
c5184807 | 588 | @item i h y |
f9b4c05d | 589 | @code{diary-hebrew-insert-yearly-entry} |
c5184807 | 590 | @item i i d |
f9b4c05d | 591 | @code{diary-islamic-insert-entry} |
c5184807 | 592 | @item i i m |
f9b4c05d | 593 | @code{diary-islamic-insert-monthly-entry} |
c5184807 | 594 | @item i i y |
f9b4c05d GM |
595 | @code{diary-islamic-insert-yearly-entry} |
596 | @item i B d | |
597 | @code{diary-bahai-insert-entry} | |
598 | @item i B m | |
599 | @code{diary-bahai-insert-monthly-entry} | |
600 | @item i B y | |
601 | @code{diary-bahai-insert-yearly-entry} | |
bbdcf64f LL |
602 | @item i C d |
603 | @code{diary-chinese-insert-entry} | |
604 | @item i C m | |
605 | @code{diary-chinese-insert-monthly-entry} | |
606 | @item i C y | |
607 | @code{diary-chinese-insert-yearly-entry} | |
608 | @item i C a | |
609 | @code{diary-chinese-insert-anniversary-entry} | |
c5184807 EZ |
610 | @end table |
611 | ||
36c0514c GM |
612 | @findex diary-hebrew-insert-entry |
613 | @findex diary-hebrew-insert-monthly-entry | |
614 | @findex diary-hebrew-insert-yearly-entry | |
615 | @findex diary-islamic-insert-entry | |
616 | @findex diary-islamic-insert-monthly-entry | |
617 | @findex diary-islamic-insert-yearly-entry | |
f9b4c05d GM |
618 | @findex diary-bahai-insert-entry |
619 | @findex diary-bahai-insert-monthly-entry | |
620 | @findex diary-bahai-insert-yearly-entry | |
bbdcf64f LL |
621 | @findex diary-chinese-insert-entry |
622 | @findex diary-chinese-insert-monthly-entry | |
623 | @findex diary-chinese-insert-yearly-entry | |
624 | @findex diary-chinese-insert-anniversary-entry | |
625 | ||
c5184807 EZ |
626 | These commands work much like the corresponding commands for ordinary |
627 | diary entries: they apply to the date that point is on in the calendar | |
f9b4c05d GM |
628 | window, and what they do is insert just the date portion of a diary |
629 | entry at the end of your diary file. You must then insert the rest of | |
630 | the diary entry. The basic commands add an entry for the specific | |
631 | non-Gregorian date, the @samp{monthly} commands for the given | |
632 | non-Gregorian day-within-month in every month, and the @samp{yearly} | |
633 | commands for the given non-Gregorian day and month in every year. | |
c5184807 | 634 | |
cad04c66 GM |
635 | @node Diary Display |
636 | @subsection Diary Display | |
d21d2618 | 637 | @vindex diary-display-function |
36c0514c | 638 | @findex diary-simple-display |
daf7e339 GM |
639 | @findex diary-fancy-display |
640 | @cindex diary buffer | |
c5184807 | 641 | |
cad04c66 GM |
642 | Diary display works by preparing the list of diary entries and then |
643 | running the function specified by the variable | |
644 | @code{diary-display-function}. The default value | |
daf7e339 GM |
645 | @code{diary-fancy-display} displays diary entries and holidays by |
646 | copying them into a special buffer that exists only for the sake of | |
cad04c66 GM |
647 | display. Copying diary entries to a separate buffer provides an |
648 | opportunity to change the displayed text to make it prettier---for | |
649 | example, to sort the entries by the dates they apply to. | |
c5184807 EZ |
650 | |
651 | @vindex diary-list-include-blanks | |
cad04c66 GM |
652 | Ordinarily, the fancy diary buffer does not show days for which there |
653 | are no diary entries, even if that day is a holiday. If you want such | |
654 | days to be shown in the fancy diary buffer, set the variable | |
9548391c | 655 | @code{diary-list-include-blanks} to @code{t}. |
c5184807 | 656 | |
5f9756ec GM |
657 | The fancy diary buffer enables View mode |
658 | @iftex | |
659 | (@pxref{View Mode,,, emacs, the Emacs Manual}). | |
660 | @end iftex | |
661 | @ifnottex | |
662 | (@pxref{View Mode}). | |
663 | @end ifnottex | |
e11adbd8 GM |
664 | |
665 | The alternative display method @code{diary-simple-display} shows the | |
666 | actual diary buffer, and uses invisible text to hide entries that don't | |
667 | apply. Holidays are shown in the mode line. The advantage of this | |
668 | method is that you can edit the buffer and save your changes directly to | |
669 | the diary file. This method is not as flexible as the fancy method, | |
670 | however. For example, it cannot sort entries. Another disadvantage is | |
671 | that invisible text can be confusing. For example, if you copy a region | |
672 | of text in order to paste it elsewhere, invisible text may be included. | |
673 | Similarly, since the diary buffer as you see it is an illusion, simply | |
674 | printing the buffer may not print what you see on your screen. | |
cad04c66 GM |
675 | |
676 | @vindex diary-print-entries-hook | |
677 | @findex diary-print-entries | |
678 | For this reason, there is a special command to print hard copy of the | |
679 | diary buffer @emph{as it appears}; this command is @kbd{M-x | |
680 | diary-print-entries}. It works with either display method, although | |
681 | with the fancy display you can also print the buffer like any other. To | |
682 | print a hard copy of a day-by-day diary for a week, position point on | |
683 | the first day of the week, type @kbd{7 d}, and then do @kbd{M-x | |
684 | diary-print-entries}. As usual, the inclusion of the holidays slows | |
685 | down the display slightly; you can speed things up by setting the | |
686 | variable @code{diary-show-holidays-flag} to @code{nil}. | |
687 | ||
688 | This command prepares a temporary buffer that contains only the diary | |
689 | entries currently visible in the diary buffer. Unlike with the simple | |
690 | display, the other irrelevant entries are really absent, not just | |
691 | hidden. After preparing the buffer, it runs the hook | |
692 | @code{diary-print-entries-hook}. The default value of this hook sends | |
693 | the data directly to the printer with the command @code{lpr-buffer} | |
5f9756ec GM |
694 | @iftex |
695 | (@pxref{Printing,,, emacs, the Emacs Manual}). | |
696 | @end iftex | |
697 | @ifnottex | |
698 | (@pxref{Printing}). | |
699 | @end ifnottex | |
700 | If you want to use a different command to do the | |
cad04c66 GM |
701 | printing, just change the value of this hook. Other uses might include, |
702 | for example, rearranging the lines into order by day and time. | |
703 | ||
704 | You can edit the diary entries as they appear in the simple diary | |
705 | window, but it is important to remember that the buffer displayed | |
706 | contains the @emph{entire} diary file, with portions of it concealed | |
707 | from view. This means, for instance, that the @kbd{C-f} | |
708 | (@code{forward-char}) command can put point at what appears to be the | |
709 | end of the line, but what is in reality the middle of some concealed | |
710 | line. | |
711 | ||
712 | @emph{Be careful when editing the diary entries in the simple display!} | |
713 | Inserting additional lines or adding/deleting characters in the middle | |
714 | of a visible line cannot cause problems, but editing at the end of a | |
715 | line may not do what you expect. Deleting a line may delete other | |
716 | invisible entries that follow it. Before editing the simple diary | |
717 | buffer, it is best to display the entire file with @kbd{s} | |
718 | (@code{diary-show-all-entries}). | |
719 | ||
720 | @node Fancy Diary Display | |
721 | @subsection Fancy Diary Display | |
722 | ||
723 | The following features only work with the fancy diary display. | |
724 | ||
c5184807 | 725 | @cindex sorting diary entries |
cad04c66 GM |
726 | You can use the normal hook @code{diary-list-entries-hook} to sort |
727 | each day's diary entries by their time of day. Here's how: | |
c5184807 | 728 | |
36c0514c | 729 | @findex diary-sort-entries |
c5184807 | 730 | @example |
36c0514c | 731 | (add-hook 'diary-list-entries-hook 'diary-sort-entries t) |
c5184807 EZ |
732 | @end example |
733 | ||
734 | @noindent | |
735 | For each day, this sorts diary entries that begin with a recognizable | |
736 | time of day according to their times. Diary entries without times come | |
67ae9766 GM |
737 | first within each day. Note how the sort command is placed at the end |
738 | of the hook list, in case earlier members of the list change the order | |
739 | of the diary entries, or add items. | |
c5184807 | 740 | |
548d0a63 GM |
741 | @vindex diary-comment-start |
742 | You can write @samp{comments} in diary entries, by setting the | |
743 | variables @code{diary-comment-start} and @code{diary-comment-end} to | |
744 | strings that delimit comments. The fancy display does not print | |
745 | comments. You might want to put meta-data for the use of other packages | |
1df7defd | 746 | (e.g., the appointment package, |
548d0a63 GM |
747 | @iftex |
748 | @pxref{Appointments,,,emacs, the Emacs Manual}) | |
749 | @end iftex | |
750 | @ifnottex | |
751 | @pxref{Appointments}) | |
752 | @end ifnottex | |
753 | inside comments. | |
754 | ||
f9b4c05d | 755 | @vindex diary-include-string |
cad04c66 GM |
756 | Your main diary file can include other files. This permits a group of |
757 | people to share a diary file for events that apply to all of them. | |
758 | Lines in the diary file starting with @code{diary-include-string}: | |
c5184807 EZ |
759 | |
760 | @smallexample | |
761 | #include "@var{filename}" | |
762 | @end smallexample | |
763 | ||
764 | @noindent | |
f9b4c05d GM |
765 | include the diary entries from the file @var{filename} in the fancy |
766 | diary buffer. The include mechanism is recursive, so that included | |
767 | files can include other files, and so on (you must be careful not to | |
768 | have a cycle of inclusions, of course). Here is how to enable the | |
769 | include facility: | |
c5184807 | 770 | |
36c0514c GM |
771 | @vindex diary-list-entries-hook |
772 | @vindex diary-mark-entries-hook | |
773 | @findex diary-include-other-diary-files | |
774 | @findex diary-mark-included-diary-files | |
c5184807 | 775 | @smallexample |
36c0514c GM |
776 | (add-hook 'diary-list-entries-hook 'diary-include-other-diary-files) |
777 | (add-hook 'diary-mark-entries-hook 'diary-mark-included-diary-files) | |
c5184807 EZ |
778 | @end smallexample |
779 | ||
780 | The include mechanism works only with the fancy diary display, because | |
cad04c66 | 781 | simple diary display shows the entries directly from your diary file. |
c5184807 EZ |
782 | |
783 | @node Sexp Diary Entries | |
784 | @subsection Sexp Entries and the Fancy Diary Display | |
785 | @cindex sexp diary entries | |
786 | ||
f9b4c05d | 787 | @vindex diary-sexp-entry-symbol |
c5184807 | 788 | Sexp diary entries allow you to do more than just have complicated |
f9b4c05d GM |
789 | conditions under which a diary entry applies. Sexp entries should be |
790 | preceded by @code{diary-sexp-entry-symbol} (default @samp{%%}) in the | |
cad04c66 GM |
791 | diary file. With the fancy diary display, sexp entries can generate the |
792 | text of the entry depending on the date itself. | |
f9b4c05d GM |
793 | |
794 | For example, an anniversary diary entry can insert | |
c5184807 | 795 | the number of years since the anniversary date into the text of the |
5de4980c | 796 | diary entry. Thus the @samp{%d} in this diary entry: |
c5184807 EZ |
797 | |
798 | @findex diary-anniversary | |
799 | @smallexample | |
800 | %%(diary-anniversary 10 31 1948) Arthur's birthday (%d years old) | |
801 | @end smallexample | |
802 | ||
803 | @noindent | |
804 | gets replaced by the age, so on October 31, 1990 the entry appears in | |
805 | the fancy diary buffer like this: | |
806 | ||
807 | @smallexample | |
808 | Arthur's birthday (42 years old) | |
809 | @end smallexample | |
810 | ||
811 | @noindent | |
812 | If the diary file instead contains this entry: | |
813 | ||
814 | @smallexample | |
815 | %%(diary-anniversary 10 31 1948) Arthur's %d%s birthday | |
816 | @end smallexample | |
817 | ||
818 | @noindent | |
819 | the entry in the fancy diary buffer for October 31, 1990 appears like this: | |
820 | ||
821 | @smallexample | |
822 | Arthur's 42nd birthday | |
823 | @end smallexample | |
824 | ||
825 | Similarly, cyclic diary entries can interpolate the number of repetitions | |
826 | that have occurred: | |
827 | ||
828 | @findex diary-cyclic | |
829 | @smallexample | |
a5987767 | 830 | %%(diary-cyclic 50 1 1 2012) Renew medication (%d%s time) |
c5184807 EZ |
831 | @end smallexample |
832 | ||
833 | @noindent | |
834 | looks like this: | |
835 | ||
836 | @smallexample | |
837 | Renew medication (5th time) | |
838 | @end smallexample | |
839 | ||
840 | @noindent | |
a5987767 | 841 | in the fancy diary display on September 7, 2012. |
c5184807 | 842 | |
a5987767 | 843 | There is an ``early reminder'' diary sexp that includes its entry in the |
c5184807 EZ |
844 | diary not only on the date of occurrence, but also on earlier dates. |
845 | For example, if you want a reminder a week before your anniversary, you | |
846 | can use | |
847 | ||
848 | @findex diary-remind | |
849 | @smallexample | |
850 | %%(diary-remind '(diary-anniversary 12 22 1968) 7) Ed's anniversary | |
851 | @end smallexample | |
852 | ||
853 | @noindent | |
f9b4c05d GM |
854 | and the fancy diary will show @samp{Ed's anniversary} both on December |
855 | 15 and on December 22. | |
c5184807 EZ |
856 | |
857 | @findex diary-date | |
858 | The function @code{diary-date} applies to dates described by a month, | |
859 | day, year combination, each of which can be an integer, a list of | |
f9b4c05d | 860 | integers, or @code{t} (meaning all values). For example, |
c5184807 EZ |
861 | |
862 | @smallexample | |
863 | %%(diary-date '(10 11 12) 22 t) Rake leaves | |
864 | @end smallexample | |
865 | ||
866 | @noindent | |
867 | causes the fancy diary to show | |
868 | ||
869 | @smallexample | |
870 | Rake leaves | |
871 | @end smallexample | |
872 | ||
873 | @noindent | |
874 | on October 22, November 22, and December 22 of every year. | |
875 | ||
876 | @findex diary-float | |
877 | The function @code{diary-float} allows you to describe diary entries | |
878 | that apply to dates like the third Friday of November, or the last | |
879 | Tuesday in April. The parameters are the @var{month}, @var{dayname}, | |
f9b4c05d | 880 | and an index @var{n}. The entry appears on the @var{n}th @var{dayname} |
ff2c14fc GM |
881 | after the first day of @var{month}, where @var{dayname}=0 means Sunday, |
882 | 1 means Monday, and so on. If @var{n} is negative it counts backward | |
883 | from the end of @var{month}. The value of @var{month} can be a list of | |
884 | months, a single month, or @code{t} to specify all months. You can also | |
885 | use an optional parameter @var{day} to specify the @var{n}th | |
886 | @var{dayname} on or after/before @var{day} of @var{month}; the value of | |
887 | @var{day} defaults to 1 if @var{n} is positive and to the last day of | |
888 | @var{month} if @var{n} is negative. For example, | |
c5184807 EZ |
889 | |
890 | @smallexample | |
891 | %%(diary-float t 1 -1) Pay rent | |
892 | @end smallexample | |
893 | ||
894 | @noindent | |
895 | causes the fancy diary to show | |
896 | ||
897 | @smallexample | |
898 | Pay rent | |
899 | @end smallexample | |
900 | ||
901 | @noindent | |
902 | on the last Monday of every month. | |
903 | ||
904 | The generality of sexp diary entries lets you specify any diary | |
905 | entry that you can describe algorithmically. A sexp diary entry | |
906 | contains an expression that computes whether the entry applies to any | |
907 | given date. If its value is non-@code{nil}, the entry applies to that | |
908 | date; otherwise, it does not. The expression can use the variable | |
909 | @code{date} to find the date being considered; its value is a list | |
910 | (@var{month} @var{day} @var{year}) that refers to the Gregorian | |
911 | calendar. | |
912 | ||
913 | The sexp diary entry applies to a date when the expression's value | |
914 | is non-@code{nil}, but some values have more specific meanings. If | |
915 | the value is a string, that string is a description of the event which | |
916 | occurs on that date. The value can also have the form | |
917 | @code{(@var{mark} . @var{string})}; then @var{mark} specifies how to | |
918 | mark the date in the calendar, and @var{string} is the description of | |
919 | the event. If @var{mark} is a single-character string, that character | |
920 | appears next to the date in the calendar. If @var{mark} is a face | |
921 | name, the date is displayed in that face. If @var{mark} is | |
922 | @code{nil}, that specifies no particular highlighting for the date. | |
923 | ||
924 | Suppose you get paid on the 21st of the month if it is a weekday, and | |
925 | on the Friday before if the 21st is on a weekend. Here is how to write | |
926 | a sexp diary entry that matches those dates: | |
927 | ||
928 | @smallexample | |
929 | &%%(let ((dayname (calendar-day-of-week date)) | |
f9b4c05d | 930 | (day (cadr date))) |
c5184807 EZ |
931 | (or (and (= day 21) (memq dayname '(1 2 3 4 5))) |
932 | (and (memq day '(19 20)) (= dayname 5))) | |
933 | ) Pay check deposited | |
934 | @end smallexample | |
935 | ||
936 | The following sexp diary entries take advantage of the ability (in the fancy | |
937 | diary display) to concoct diary entries whose text varies based on the date: | |
938 | ||
939 | @findex diary-sunrise-sunset | |
8ce2c66f | 940 | @findex diary-lunar-phases |
c5184807 EZ |
941 | @findex diary-day-of-year |
942 | @findex diary-iso-date | |
943 | @findex diary-julian-date | |
944 | @findex diary-astro-day-number | |
36c0514c | 945 | @findex diary-bahai-date |
f9b4c05d GM |
946 | @findex diary-chinese-date |
947 | @findex diary-coptic-date | |
948 | @findex diary-ethiopic-date | |
c5184807 EZ |
949 | @findex diary-hebrew-date |
950 | @findex diary-islamic-date | |
951 | @findex diary-french-date | |
952 | @findex diary-mayan-date | |
f9b4c05d | 953 | @findex diary-persian-date |
c5184807 EZ |
954 | @table @code |
955 | @item %%(diary-sunrise-sunset) | |
f9b4c05d | 956 | Make a diary entry for today's local times of sunrise and sunset. |
8ce2c66f | 957 | @item %%(diary-lunar-phases) |
c5184807 EZ |
958 | Make a diary entry for the phases (quarters) of the moon. |
959 | @item %%(diary-day-of-year) | |
960 | Make a diary entry with today's day number in the current year and the number | |
961 | of days remaining in the current year. | |
962 | @item %%(diary-iso-date) | |
963 | Make a diary entry with today's equivalent ISO commercial date. | |
964 | @item %%(diary-julian-date) | |
f9b4c05d | 965 | Make a diary entry with today's equivalent Julian calendar date. |
c5184807 EZ |
966 | @item %%(diary-astro-day-number) |
967 | Make a diary entry with today's equivalent astronomical (Julian) day number. | |
36c0514c | 968 | @item %%(diary-bahai-date) |
681ebc33 | 969 | Make a diary entry with today's equivalent Bahá'í calendar date. |
f9b4c05d GM |
970 | @item %%(diary-chinese-date) |
971 | Make a diary entry with today's equivalent Chinese calendar date. | |
972 | @item %%(diary-coptic-date) | |
973 | Make a diary entry with today's equivalent Coptic calendar date. | |
974 | @item %%(diary-ethiopic-date) | |
975 | Make a diary entry with today's equivalent Ethiopic calendar date. | |
c5184807 EZ |
976 | @item %%(diary-french-date) |
977 | Make a diary entry with today's equivalent date on the French Revolutionary | |
978 | calendar. | |
f9b4c05d GM |
979 | @item %%(diary-hebrew-date) |
980 | Make a diary entry with today's equivalent Hebrew calendar date. | |
981 | @item %%(diary-islamic-date) | |
982 | Make a diary entry with today's equivalent Islamic calendar date. | |
c5184807 | 983 | @item %%(diary-mayan-date) |
f9b4c05d GM |
984 | Make a diary entry with today's equivalent Mayan calendar date. |
985 | @item %%(diary-persian-date) | |
986 | Make a diary entry with today's equivalent Persian calendar date. | |
c5184807 EZ |
987 | @end table |
988 | ||
989 | @noindent | |
f9b4c05d | 990 | For example, including the diary entry |
c5184807 | 991 | |
f9b4c05d | 992 | @smallexample |
c5184807 | 993 | &%%(diary-hebrew-date) |
f9b4c05d | 994 | @end smallexample |
c5184807 EZ |
995 | |
996 | @noindent | |
997 | causes every day's diary display to contain the equivalent date on the | |
998 | Hebrew calendar, if you are using the fancy diary display. (With simple | |
f9b4c05d GM |
999 | diary display, the literal line @samp{&%%(diary-hebrew-date)} appears in |
1000 | the diary for any date.) | |
c5184807 | 1001 | |
f9b4c05d GM |
1002 | This function has been used to construct certain standard Hebrew sexp |
1003 | diary entries: | |
c5184807 EZ |
1004 | |
1005 | @cindex rosh hodesh | |
36c0514c | 1006 | @findex diary-hebrew-rosh-hodesh |
c5184807 | 1007 | @cindex parasha, weekly |
36c0514c | 1008 | @findex diary-hebrew-parasha |
c5184807 | 1009 | @cindex candle lighting times |
36c0514c | 1010 | @findex diary-hebrew-sabbath-candles |
c5184807 | 1011 | @cindex omer count |
36c0514c | 1012 | @findex diary-hebrew-omer |
c5184807 | 1013 | @cindex yahrzeits |
36c0514c | 1014 | @findex diary-hebrew-yahrzeit |
d306b4da | 1015 | @findex diary-hebrew-birthday |
c5184807 | 1016 | @table @code |
36c0514c | 1017 | @item %%(diary-hebrew-rosh-hodesh) |
c5184807 EZ |
1018 | Make a diary entry that tells the occurrence and ritual announcement of each |
1019 | new Hebrew month. | |
36c0514c | 1020 | @item %%(diary-hebrew-parasha) |
c5184807 | 1021 | Make a Saturday diary entry that tells the weekly synagogue scripture reading. |
36c0514c | 1022 | @item %%(diary-hebrew-sabbath-candles) |
c5184807 EZ |
1023 | Make a Friday diary entry that tells the @emph{local time} of Sabbath |
1024 | candle lighting. | |
36c0514c | 1025 | @item %%(diary-hebrew-omer) |
c5184807 | 1026 | Make a diary entry that gives the omer count, when appropriate. |
36c0514c | 1027 | @item %%(diary-hebrew-yahrzeit @var{month} @var{day} @var{year}) @var{name} |
c5184807 EZ |
1028 | Make a diary entry marking the anniversary of a date of death. The date |
1029 | is the @emph{Gregorian} (civil) date of death. The diary entry appears | |
f9b4c05d GM |
1030 | on the proper Hebrew calendar anniversary and on the day before. (The |
1031 | order of the parameters changes according to the calendar date style; | |
1032 | for example in the European style to @var{day}, @var{month}, @var{year}.) | |
d306b4da GM |
1033 | @item %%(diary-hebrew-birthday @var{month} @var{day} @var{year}) |
1034 | Make a diary entry for a birthday on the Hebrew calendar. | |
c5184807 EZ |
1035 | @end table |
1036 | ||
1037 | All the functions documented above take an optional argument | |
1038 | @var{mark} which specifies how to mark the date in the calendar display. | |
1039 | If one of these functions decides that it applies to a certain date, | |
f9b4c05d | 1040 | it returns a value that contains @var{mark}, as described above. |