Commit | Line | Data |
---|---|---|
4d213d5a LT |
1 | \input texinfo @c -*-texinfo-*- |
2 | @comment %**start of header | |
3 | @setfilename ../info/emacs-xtra | |
4 | @settitle Specialized Emacs Features | |
5 | @syncodeindex fn cp | |
6 | @syncodeindex vr cp | |
7 | @syncodeindex ky cp | |
8 | @comment %**end of header | |
9 | ||
10 | @copying | |
331fbb7d | 11 | This manual describes specialized features of Emacs. |
4d213d5a | 12 | |
24396ac6 | 13 | Copyright (C) 2004, 2005 |
4d213d5a LT |
14 | Free Software Foundation, Inc. |
15 | ||
16 | @quotation | |
17 | Permission is granted to copy, distribute and/or modify this document | |
18 | under the terms of the GNU Free Documentation License, Version 1.1 or | |
19 | any later version published by the Free Software Foundation; with no | |
20 | Invariant Sections, with the Front-Cover texts being ``A GNU | |
21 | Manual'', and with the Back-Cover Texts as in (a) below. A copy of the | |
22 | license is included in the section entitled ``GNU Free Documentation | |
23 | License'' in the Emacs manual. | |
24 | ||
25 | (a) The FSF's Back-Cover Text is: ``You have freedom to copy and modify | |
26 | this GNU Manual, like GNU software. Copies published by the Free | |
27 | Software Foundation raise funds for GNU development.'' | |
28 | ||
29 | This document is part of a collection distributed under the GNU Free | |
30 | Documentation License. If you want to distribute this document | |
31 | separately from the collection, you can do so by adding a copy of the | |
32 | license to the document, as described in section 6 of the license. | |
33 | @end quotation | |
34 | @end copying | |
35 | ||
36 | @dircategory Emacs | |
37 | @direntry | |
38 | * Emacs-Xtra: (emacs-xtra). Specialized Emacs features. | |
39 | @end direntry | |
40 | ||
41 | @titlepage | |
42 | @title Specialized Emacs Features | |
43 | @page | |
44 | @vskip 0pt plus 1filll | |
45 | @insertcopying | |
46 | @end titlepage | |
47 | ||
48 | @contents | |
49 | ||
50 | @ifnottex | |
51 | @node Top | |
52 | @top Specialized Emacs Features | |
53 | ||
54 | @insertcopying | |
55 | ||
56 | @end ifnottex | |
57 | ||
58 | @menu | |
59 | * Introduction:: What documentation belongs here? | |
60 | * Autorevert:: Auto Reverting non-file buffers. | |
61 | * Subdir switches:: Subdirectory switches in Dired. | |
24396ac6 | 62 | * Advanced Calendar/Diary Usage:: Advanced Calendar/Diary customization. |
4d213d5a LT |
63 | * Index:: |
64 | @end menu | |
65 | ||
66 | @node Introduction | |
67 | @unnumbered Introduction | |
68 | ||
69 | This manual contains detailed information about various features that | |
70 | are too specialized to be included in the Emacs manual. It is | |
71 | intended to be readable by anyone having a basic knowledge of Emacs. | |
72 | However, certain sections may be intended for a more specialized | |
73 | audience, such as Elisp authors. This should be clearly pointed out | |
74 | at the beginning of these sections. | |
75 | ||
76 | This manual is intended as a complement, rather than an alternative, | |
77 | to other ways to gain a more detailed knowledge of Emacs than the | |
78 | Emacs manual can provide, such as browsing packages using @kbd{C-h p}, | |
79 | accessing mode documentation using @kbd{C-h m} and browsing user | |
80 | options using Custom. Also, certain packages, or collections of | |
81 | related features, have their own manuals. The present manual is | |
82 | mainly intended to be a collection of smaller specialized features, | |
83 | too small to get their own manual. | |
84 | ||
85 | Sections intended specifically for Elisp programmers can follow the | |
86 | style of the Elisp manual. Other sections should follow the style of | |
87 | the Emacs manual. | |
88 | ||
89 | @node Autorevert | |
90 | @chapter Auto Reverting non-file Buffers | |
91 | ||
92 | Normally Global Auto Revert Mode only reverts file buffers. There are | |
93 | two ways to auto-revert certain non-file buffers: enabling Auto Revert | |
94 | Mode in those buffers (using @kbd{M-x auto-revert-mode}) and setting | |
95 | @code{global-auto-revert-non-file-buffers} to @code{t}. The latter | |
96 | enables Auto Reverting for all types of buffers for which it is | |
97 | implemented, that is, for the types of buffers listed in the menu | |
98 | below. | |
99 | ||
100 | Like file buffers, non-file buffers should normally not revert while | |
101 | you are working on them, or while they contain information that might | |
102 | get lost after reverting. Therefore, they do not revert if they are | |
103 | ``modified''. This can get tricky, because deciding when a non-file | |
104 | buffer should be marked modified is usually more difficult than for | |
105 | file buffers. | |
106 | ||
107 | Another tricky detail is that, for efficiency reasons, Auto Revert | |
108 | often does not try to detect all possible changes in the buffer, only | |
109 | changes that are ``major'' or easy to detect. Hence, enabling | |
110 | auto-reverting for a non-file buffer does not always guarantee that | |
111 | all information in the buffer is up to date and does not necessarily | |
112 | make manual reverts useless. | |
113 | ||
2626389a LT |
114 | At the other extreme, certain buffers automatically auto-revert every |
115 | @code{auto-revert-interval} seconds. (This currently only applies to | |
116 | the Buffer Menu.) In this case, Auto Revert does not print any | |
117 | messages while reverting, even when @code{auto-revert-verbose} is | |
118 | non-@code{nil}. | |
119 | ||
4d213d5a LT |
120 | The details depend on the particular types of buffers and are |
121 | explained in the corresponding sections. | |
122 | ||
123 | @menu | |
124 | * Auto Reverting the Buffer Menu:: | |
125 | * Auto Reverting Dired:: | |
126 | * Supporting additional buffers:: | |
127 | @end menu | |
128 | ||
129 | @node Auto Reverting the Buffer Menu | |
130 | @section Auto Reverting the Buffer Menu | |
131 | ||
132 | If auto-reverting of non-file buffers is enabled, the Buffer Menu | |
133 | automatically reverts every @code{auto-revert-interval} seconds, | |
134 | whether there is a need for it or not. (It would probably take longer | |
135 | to check whether there is a need than to actually revert.) | |
136 | ||
137 | If the Buffer Menu inappropriately gets marked modified, just revert | |
138 | it manually using @kbd{g} and auto-reverting will resume. However, if | |
139 | you marked certain buffers to get deleted or to be displayed, you have | |
140 | to be careful, because reverting erases all marks. The fact that | |
141 | adding marks sets the buffer's modified flag prevents Auto Revert from | |
142 | automatically erasing the marks. | |
143 | ||
144 | @node Auto Reverting Dired | |
145 | @section Auto Reverting Dired buffers | |
146 | ||
236e9d7e LT |
147 | Auto-reverting Dired buffers currently works on GNU or Unix style |
148 | operating systems. It may not work satisfactorily on some other | |
149 | systems. | |
4d213d5a LT |
150 | |
151 | Dired buffers only auto-revert when the file list of the buffer's main | |
152 | directory changes. They do not auto-revert when information about a | |
153 | particular file changes or when inserted subdirectories change. To be | |
154 | sure that @emph{all} listed information is up to date, you have to | |
155 | manually revert using @kbd{g}, @emph{even} if auto-reverting is | |
156 | enabled in the Dired buffer. Sometimes, you might get the impression | |
157 | that modifying or saving files listed in the main directory actually | |
158 | does cause auto-reverting. This is because making changes to a file, | |
159 | or saving it, very often causes changes in the directory itself, for | |
160 | instance, through backup files or auto-save files. However, this is | |
161 | not guaranteed. | |
162 | ||
163 | If the Dired buffer is marked modified and there are no changes you | |
164 | want to protect, then most of the time you can make auto-reverting | |
165 | resume by manually reverting the buffer using @kbd{g}. There is one | |
236e9d7e LT |
166 | exception. If you flag or mark files, you can safely revert the |
167 | buffer. This will not erase the flags or marks (unless the marked | |
168 | file has been deleted, of course). However, the buffer will stay | |
169 | modified, even after reverting, and auto-reverting will not resume. | |
170 | This is because, if you flag or mark files, you may be working on the | |
171 | buffer and you might not want the buffer to change without warning. | |
172 | If you want auto-reverting to resume in the presence of marks and | |
173 | flags, mark the buffer non-modified using @kbd{M-~}. However, adding, | |
174 | deleting or changing marks or flags will mark it modified again. | |
4d213d5a LT |
175 | |
176 | Remote Dired buffers are not auto-reverted. Neither are Dired buffers | |
177 | for which you used shell wildcards or file arguments to list only some | |
178 | of the files. @samp{*Find*} and @samp{*Locate*} buffers do not | |
179 | auto-revert either. | |
180 | ||
181 | @node Supporting additional buffers | |
182 | @section Adding Support for Auto-Reverting additional Buffers. | |
183 | ||
184 | This section is intended for Elisp programmers who would like to add | |
185 | support for auto-reverting new types of buffers. | |
186 | ||
187 | To support auto-reverting the buffer must first of all have a | |
188 | @code{revert-buffer-function}. @xref{Definition of | |
189 | revert-buffer-function,, Reverting, elisp, the Emacs Lisp Reference Manual}. | |
190 | ||
191 | In addition, it @emph{must} have a @code{buffer-stale-function}. | |
192 | ||
193 | @defvar buffer-stale-function | |
194 | The value of this variable is a function to check whether a non-file | |
195 | buffer needs reverting. This should be a function with one optional | |
196 | argument @var{noconfirm}. The function should return non-@code{nil} | |
197 | if the buffer should be reverted. The buffer is current when this | |
198 | function is called. | |
199 | ||
200 | While this function is mainly intended for use in auto-reverting, it | |
201 | could be used for other purposes as well. For instance, if | |
202 | auto-reverting is not enabled, it could be used to warn the user that | |
203 | the buffer needs reverting. The idea behind the @var{noconfirm} | |
204 | argument is that it should be @code{t} if the buffer is going to be | |
205 | reverted without asking the user and @code{nil} if the function is | |
206 | just going to be used to warn the user that the buffer is out of date. | |
207 | In particular, for use in auto-reverting, @var{noconfirm} is @code{t}. | |
208 | If the function is only going to be used for auto-reverting, you can | |
209 | ignore the @var{noconfirm} argument. | |
210 | ||
211 | If you just want to automatically auto-revert every | |
212 | @code{auto-revert-interval} seconds, use: | |
213 | ||
214 | @example | |
215 | (set (make-local-variable 'buffer-stale-function) | |
216 | #'(lambda (&optional noconfirm) 'fast)) | |
217 | @end example | |
218 | ||
219 | @noindent | |
220 | in the buffer's mode function. | |
221 | ||
2626389a LT |
222 | The special return value @samp{fast} tells the caller that the need |
223 | for reverting was not checked, but that reverting the buffer is fast. | |
224 | It also tells Auto Revert not to print any revert messages, even if | |
225 | @code{auto-revert-verbose} is non-@code{nil}. This is important, as | |
226 | getting revert messages every @code{auto-revert-interval} seconds can | |
227 | be very annoying. The information provided by this return value could | |
228 | also be useful if the function is consulted for purposes other than | |
229 | auto-reverting. | |
4d213d5a LT |
230 | @end defvar |
231 | ||
232 | Once the buffer has a @code{revert-buffer-function} and a | |
233 | @code{buffer-stale-function}, several problems usually remain. | |
234 | ||
235 | The buffer will only auto-revert if it is marked unmodified. Hence, | |
236 | you will have to make sure that various functions mark the buffer | |
237 | modified if and only if either the buffer contains information that | |
238 | might be lost by reverting or there is reason to believe that the user | |
239 | might be inconvenienced by auto-reverting, because he is actively | |
240 | working on the buffer. The user can always override this by manually | |
241 | adjusting the modified status of the buffer. To support this, calling | |
242 | the @code{revert-buffer-function} on a buffer that is marked | |
243 | unmodified should always keep the buffer marked unmodified. | |
244 | ||
245 | It is important to assure that point does not continuously jump around | |
246 | as a consequence of auto-reverting. Of course, moving point might be | |
247 | inevitable if the buffer radically changes. | |
248 | ||
249 | You should make sure that the @code{revert-buffer-function} does not | |
250 | print messages that unnecessarily duplicate Auto Revert's own messages | |
251 | if @code{auto-revert-verbose} is @code{t} and effectively override a | |
252 | @code{nil} value for @code{auto-revert-verbose}. Hence, adapting a | |
253 | mode for auto-reverting often involves getting rid of such messages. | |
2626389a LT |
254 | This is especially important for buffers that automatically |
255 | auto-revert every @code{auto-revert-interval} seconds. | |
4d213d5a | 256 | |
331fbb7d LT |
257 | Also, you may want to update the documentation string of |
258 | @code{global-auto-revert-non-file-buffers}. | |
259 | ||
4d213d5a LT |
260 | @ifinfo |
261 | Finally, you should add a node to this chapter's menu. This node | |
262 | @end ifinfo | |
263 | @ifnotinfo | |
264 | Finally, you should add a section to this chapter. This section | |
265 | @end ifnotinfo | |
266 | should at the very least make clear whether enabling auto-reverting | |
267 | for the buffer reliably assures that all information in the buffer is | |
268 | completely up to date (or will be after @code{auto-revert-interval} | |
269 | seconds). | |
270 | ||
271 | @node Subdir switches | |
272 | @chapter Subdirectory Switches in Dired | |
273 | ||
274 | You can insert subdirectories with specified @code{ls} switches in | |
275 | Dired buffers, using @kbd{C-u i}. You can change the @code{ls} | |
276 | switches of an already inserted subdirectory using @kbd{C-u l}. | |
277 | ||
bf247b6e | 278 | In Emacs versions 22.1 and later, Dired remembers the switches, so |
4d213d5a LT |
279 | that reverting the buffer will not change them back to the main |
280 | directory's switches. Deleting a subdirectory forgets about its | |
281 | switches. | |
282 | ||
283 | Using @code{dired-undo} (usually bound to @kbd{C-_} and @kbd{C-x u}) | |
284 | to reinsert or delete subdirectories, that were inserted with explicit | |
285 | switches, can bypass Dired's machinery for remembering (or forgetting) | |
286 | switches. Deleting a subdirectory using @code{dired-undo} does not | |
287 | forget its switches. When later reinserted using @kbd{i}, it will be | |
288 | reinserted using its old switches. Using @code{dired-undo} to | |
289 | reinsert a subdirectory that was deleted using the regular | |
290 | Dired commands (not @code{dired-undo}) will originally insert it with | |
291 | its old switches. However, reverting the buffer will relist it using | |
292 | the buffer's default switches. If any of this yields problems, you | |
293 | can easily correct the situation using @kbd{C-u i} or @kbd{C-u l}. | |
294 | ||
b6d0a321 LT |
295 | Dired does not remember the @code{R} switch. Inserting a subdirectory |
296 | with switches that include the @code{R} switch is equivalent with | |
297 | inserting each of its subdirectories using all remaining switches. | |
def26fa4 LT |
298 | For instance, updating or killing a subdirectory that was inserted |
299 | with the @code{R} switch will not update or kill its subdirectories. | |
b6d0a321 | 300 | |
4d213d5a LT |
301 | The buffer's default switches do not affect subdirectories that were |
302 | inserted using explicitly specified switches. In particular, | |
303 | commands such as @kbd{s}, that change the buffer's switches do not | |
304 | affect such subdirectories. (They do affect subdirectories without | |
305 | explicitly assigned switches, however.) | |
306 | ||
307 | You can make Dired forget about all subdirectory switches and relist | |
308 | all subdirectories with the buffer's default switches using | |
309 | @kbd{M-x dired-reset-subdir-switches}. This also reverts the Dired buffer. | |
310 | ||
24396ac6 GM |
311 | |
312 | @c Moved here from the Emacs Lisp Reference Manual, 2005-03-26. | |
313 | @node Advanced Calendar/Diary Usage | |
314 | @chapter Customizing the Calendar and Diary | |
315 | ||
316 | There are many customizations that you can use to make the calendar and | |
317 | diary suit your personal tastes. | |
318 | ||
319 | @menu | |
320 | * Calendar Customizing:: Defaults you can set. | |
321 | * Holiday Customizing:: Defining your own holidays. | |
322 | * Date Display Format:: Changing the format. | |
323 | * Time Display Format:: Changing the format. | |
324 | * Daylight Savings:: Changing the default. | |
325 | * Diary Customizing:: Defaults you can set. | |
326 | * Hebrew/Islamic Entries:: How to obtain them. | |
327 | * Fancy Diary Display:: Enhancing the diary display, sorting entries, | |
328 | using included diary files. | |
329 | * Sexp Diary Entries:: Fancy things you can do. | |
24396ac6 GM |
330 | @end menu |
331 | ||
332 | @node Calendar Customizing | |
333 | @section Customizing the Calendar | |
24396ac6 GM |
334 | @vindex calendar-holiday-marker |
335 | @vindex diary-entry-marker | |
336 | The variable @code{calendar-holiday-marker} specifies how to mark a | |
337 | date as being a holiday. Its value may be a single-character string | |
338 | to insert next to the date, or a face name to use for displaying the | |
339 | date. Likewise, the variable @code{diary-entry-marker} specifies how | |
340 | to mark a date that has diary entries. The calendar creates faces | |
341 | named @code{holiday-face} and @code{diary-face} for these purposes; | |
342 | those symbols are the default values of these variables. | |
343 | ||
344 | @vindex calendar-load-hook | |
345 | The variable @code{calendar-load-hook} is a normal hook run when the | |
346 | calendar package is first loaded (before actually starting to display | |
347 | the calendar). | |
348 | ||
349 | @vindex initial-calendar-window-hook | |
350 | Starting the calendar runs the normal hook | |
351 | @code{initial-calendar-window-hook}. Recomputation of the calendar | |
352 | display does not run this hook. But if you leave the calendar with the | |
353 | @kbd{q} command and reenter it, the hook runs again.@refill | |
354 | ||
355 | @vindex today-visible-calendar-hook | |
356 | The variable @code{today-visible-calendar-hook} is a normal hook run | |
357 | after the calendar buffer has been prepared with the calendar when the | |
358 | current date is visible in the window. One use of this hook is to | |
359 | replace today's date with asterisks; to do that, use the hook function | |
360 | @code{calendar-star-date}. | |
361 | ||
362 | @findex calendar-star-date | |
363 | @example | |
364 | (add-hook 'today-visible-calendar-hook 'calendar-star-date) | |
365 | @end example | |
366 | ||
367 | @noindent | |
368 | Another standard hook function marks the current date, either by | |
369 | changing its face or by adding an asterisk. Here's how to use it: | |
370 | ||
371 | @findex calendar-mark-today | |
372 | @example | |
373 | (add-hook 'today-visible-calendar-hook 'calendar-mark-today) | |
374 | @end example | |
375 | ||
376 | @noindent | |
377 | @vindex calendar-today-marker | |
378 | The variable @code{calendar-today-marker} specifies how to mark | |
379 | today's date. Its value should be a single-character string to insert | |
380 | next to the date or a face name to use for displaying the date. A | |
381 | face named @code{calendar-today-face} is provided for this purpose; | |
382 | that symbol is the default for this variable. | |
383 | ||
384 | @vindex today-invisible-calendar-hook | |
385 | @noindent | |
386 | A similar normal hook, @code{today-invisible-calendar-hook} is run if | |
387 | the current date is @emph{not} visible in the window. | |
388 | ||
389 | @vindex calendar-move-hook | |
390 | Each of the calendar cursor motion commands runs the hook | |
391 | @code{calendar-move-hook} after it moves the cursor. | |
392 | ||
393 | @node Holiday Customizing | |
394 | @section Customizing the Holidays | |
395 | ||
396 | @vindex calendar-holidays | |
397 | @vindex christian-holidays | |
398 | @vindex hebrew-holidays | |
399 | @vindex islamic-holidays | |
400 | Emacs knows about holidays defined by entries on one of several lists. | |
401 | You can customize these lists of holidays to your own needs, adding or | |
402 | deleting holidays. The lists of holidays that Emacs uses are for | |
403 | general holidays (@code{general-holidays}), local holidays | |
404 | (@code{local-holidays}), Christian holidays (@code{christian-holidays}), | |
405 | Hebrew (Jewish) holidays (@code{hebrew-holidays}), Islamic (Muslim) | |
406 | holidays (@code{islamic-holidays}), and other holidays | |
407 | (@code{other-holidays}). | |
408 | ||
409 | @vindex general-holidays | |
410 | The general holidays are, by default, holidays common throughout the | |
411 | United States. To eliminate these holidays, set @code{general-holidays} | |
412 | to @code{nil}. | |
413 | ||
414 | @vindex local-holidays | |
415 | There are no default local holidays (but sites may supply some). You | |
416 | can set the variable @code{local-holidays} to any list of holidays, as | |
417 | described below. | |
418 | ||
419 | @vindex all-christian-calendar-holidays | |
420 | @vindex all-hebrew-calendar-holidays | |
421 | @vindex all-islamic-calendar-holidays | |
422 | By default, Emacs does not include all the holidays of the religions | |
423 | that it knows, only those commonly found in secular calendars. For a | |
424 | more extensive collection of religious holidays, you can set any (or | |
425 | all) of the variables @code{all-christian-calendar-holidays}, | |
426 | @code{all-hebrew-calendar-holidays}, or | |
427 | @code{all-islamic-calendar-holidays} to @code{t}. If you want to | |
428 | eliminate the religious holidays, set any or all of the corresponding | |
429 | variables @code{christian-holidays}, @code{hebrew-holidays}, and | |
430 | @code{islamic-holidays} to @code{nil}.@refill | |
431 | ||
432 | @vindex other-holidays | |
433 | You can set the variable @code{other-holidays} to any list of | |
434 | holidays. This list, normally empty, is intended for individual use. | |
435 | ||
436 | @cindex holiday forms | |
437 | Each of the lists (@code{general-holidays}, @code{local-holidays}, | |
438 | @code{christian-holidays}, @code{hebrew-holidays}, | |
439 | @code{islamic-holidays}, and @code{other-holidays}) is a list of | |
440 | @dfn{holiday forms}, each holiday form describing a holiday (or | |
441 | sometimes a list of holidays). | |
442 | ||
443 | Here is a table of the possible kinds of holiday form. Day numbers | |
444 | and month numbers count starting from 1, but ``dayname'' numbers | |
445 | count Sunday as 0. The element @var{string} is always the | |
446 | name of the holiday, as a string. | |
447 | ||
448 | @table @code | |
449 | @item (holiday-fixed @var{month} @var{day} @var{string}) | |
450 | A fixed date on the Gregorian calendar. | |
451 | ||
452 | @item (holiday-float @var{month} @var{dayname} @var{k} @var{string}) | |
453 | The @var{k}th @var{dayname} in @var{month} on the Gregorian calendar | |
454 | (@var{dayname}=0 for Sunday, and so on); negative @var{k} means count back | |
455 | from the end of the month. | |
456 | ||
457 | @item (holiday-hebrew @var{month} @var{day} @var{string}) | |
458 | A fixed date on the Hebrew calendar. | |
459 | ||
460 | @item (holiday-islamic @var{month} @var{day} @var{string}) | |
461 | A fixed date on the Islamic calendar. | |
462 | ||
463 | @item (holiday-julian @var{month} @var{day} @var{string}) | |
464 | A fixed date on the Julian calendar. | |
465 | ||
466 | @item (holiday-sexp @var{sexp} @var{string}) | |
467 | A date calculated by the Lisp expression @var{sexp}. The expression | |
468 | should use the variable @code{year} to compute and return the date of a | |
469 | holiday, or @code{nil} if the holiday doesn't happen this year. The | |
470 | value of @var{sexp} must represent the date as a list of the form | |
471 | @code{(@var{month} @var{day} @var{year})}. | |
472 | ||
473 | @item (if @var{condition} @var{holiday-form}) | |
474 | A holiday that happens only if @var{condition} is true. | |
475 | ||
476 | @item (@var{function} @r{[}@var{args}@r{]}) | |
477 | A list of dates calculated by the function @var{function}, called with | |
478 | arguments @var{args}. | |
479 | @end table | |
480 | ||
481 | For example, suppose you want to add Bastille Day, celebrated in | |
482 | France on July 14. You can do this as follows: | |
483 | ||
484 | @smallexample | |
485 | (setq other-holidays '((holiday-fixed 7 14 "Bastille Day"))) | |
486 | @end smallexample | |
487 | ||
488 | @noindent | |
489 | The holiday form @code{(holiday-fixed 7 14 "Bastille Day")} specifies the | |
490 | fourteenth day of the seventh month (July). | |
491 | ||
492 | Many holidays occur on a specific day of the week, at a specific time | |
493 | of month. Here is a holiday form describing Hurricane Supplication Day, | |
494 | celebrated in the Virgin Islands on the fourth Monday in August: | |
495 | ||
496 | @smallexample | |
497 | (holiday-float 8 1 4 "Hurricane Supplication Day") | |
498 | @end smallexample | |
499 | ||
500 | @noindent | |
501 | Here the 8 specifies August, the 1 specifies Monday (Sunday is 0, | |
502 | Tuesday is 2, and so on), and the 4 specifies the fourth occurrence in | |
503 | the month (1 specifies the first occurrence, 2 the second occurrence, | |
504 | @minus{}1 the last occurrence, @minus{}2 the second-to-last occurrence, and | |
505 | so on). | |
506 | ||
507 | You can specify holidays that occur on fixed days of the Hebrew, | |
508 | Islamic, and Julian calendars too. For example, | |
509 | ||
510 | @smallexample | |
511 | (setq other-holidays | |
512 | '((holiday-hebrew 10 2 "Last day of Hanukkah") | |
513 | (holiday-islamic 3 12 "Mohammed's Birthday") | |
514 | (holiday-julian 4 2 "Jefferson's Birthday"))) | |
515 | @end smallexample | |
516 | ||
517 | @noindent | |
518 | adds the last day of Hanukkah (since the Hebrew months are numbered with | |
519 | 1 starting from Nisan), the Islamic feast celebrating Mohammed's | |
520 | birthday (since the Islamic months are numbered from 1 starting with | |
521 | Muharram), and Thomas Jefferson's birthday, which is 2 April 1743 on the | |
522 | Julian calendar. | |
523 | ||
524 | To include a holiday conditionally, use either Emacs Lisp's @code{if} or the | |
525 | @code{holiday-sexp} form. For example, American presidential elections | |
526 | occur on the first Tuesday after the first Monday in November of years | |
527 | divisible by 4: | |
528 | ||
529 | @smallexample | |
530 | (holiday-sexp '(if (= 0 (% year 4)) | |
531 | (calendar-gregorian-from-absolute | |
532 | (1+ (calendar-dayname-on-or-before | |
533 | 1 (+ 6 (calendar-absolute-from-gregorian | |
534 | (list 11 1 year))))))) | |
535 | "US Presidential Election") | |
536 | @end smallexample | |
537 | ||
538 | @noindent | |
539 | or | |
540 | ||
541 | @smallexample | |
542 | (if (= 0 (% displayed-year 4)) | |
543 | (fixed 11 | |
544 | (extract-calendar-day | |
545 | (calendar-gregorian-from-absolute | |
546 | (1+ (calendar-dayname-on-or-before | |
547 | 1 (+ 6 (calendar-absolute-from-gregorian | |
548 | (list 11 1 displayed-year))))))) | |
549 | "US Presidential Election")) | |
550 | @end smallexample | |
551 | ||
552 | Some holidays just don't fit into any of these forms because special | |
553 | calculations are involved in their determination. In such cases you | |
554 | must write a Lisp function to do the calculation. To include eclipses, | |
555 | for example, add @code{(eclipses)} to @code{other-holidays} | |
556 | and write an Emacs Lisp function @code{eclipses} that returns a | |
557 | (possibly empty) list of the relevant Gregorian dates among the range | |
558 | visible in the calendar window, with descriptive strings, like this: | |
559 | ||
560 | @smallexample | |
561 | (((6 27 1991) "Lunar Eclipse") ((7 11 1991) "Solar Eclipse") ... ) | |
562 | @end smallexample | |
563 | ||
564 | @node Date Display Format | |
565 | @section Date Display Format | |
566 | @vindex calendar-date-display-form | |
567 | ||
568 | You can customize the manner of displaying dates in the diary, in mode | |
569 | lines, and in messages by setting @code{calendar-date-display-form}. | |
570 | This variable holds a list of expressions that can involve the variables | |
571 | @code{month}, @code{day}, and @code{year}, which are all numbers in | |
572 | string form, and @code{monthname} and @code{dayname}, which are both | |
573 | alphabetic strings. In the American style, the default value of this | |
574 | list is as follows: | |
575 | ||
576 | @smallexample | |
577 | ((if dayname (concat dayname ", ")) monthname " " day ", " year) | |
578 | @end smallexample | |
579 | ||
580 | @noindent | |
581 | while in the European style this value is the default: | |
582 | ||
583 | @smallexample | |
584 | ((if dayname (concat dayname ", ")) day " " monthname " " year) | |
585 | @end smallexample | |
586 | ||
587 | @noindent | |
588 | The ISO standard date representation is this: | |
589 | ||
590 | @smallexample | |
591 | (year "-" month "-" day) | |
592 | @end smallexample | |
593 | ||
594 | @noindent | |
595 | This specifies a typical American format: | |
596 | ||
597 | @smallexample | |
598 | (month "/" day "/" (substring year -2)) | |
599 | @end smallexample | |
600 | ||
601 | @node Time Display Format | |
602 | @section Time Display Format | |
603 | @vindex calendar-time-display-form | |
604 | ||
605 | The calendar and diary by default display times of day in the | |
606 | conventional American style with the hours from 1 through 12, minutes, | |
607 | and either @samp{am} or @samp{pm}. If you prefer the European style, | |
608 | also known in the US as military, in which the hours go from 00 to 23, | |
609 | you can alter the variable @code{calendar-time-display-form}. This | |
610 | variable is a list of expressions that can involve the variables | |
611 | @code{12-hours}, @code{24-hours}, and @code{minutes}, which are all | |
612 | numbers in string form, and @code{am-pm} and @code{time-zone}, which are | |
613 | both alphabetic strings. The default value of | |
614 | @code{calendar-time-display-form} is as follows: | |
615 | ||
616 | @smallexample | |
617 | (12-hours ":" minutes am-pm | |
618 | (if time-zone " (") time-zone (if time-zone ")")) | |
619 | @end smallexample | |
620 | ||
621 | @noindent | |
622 | Here is a value that provides European style times: | |
623 | ||
624 | @smallexample | |
625 | (24-hours ":" minutes | |
626 | (if time-zone " (") time-zone (if time-zone ")")) | |
627 | @end smallexample | |
628 | ||
629 | @node Daylight Savings | |
630 | @section Daylight Savings Time | |
631 | @cindex daylight savings time | |
632 | ||
633 | Emacs understands the difference between standard time and daylight | |
634 | savings time---the times given for sunrise, sunset, solstices, | |
635 | equinoxes, and the phases of the moon take that into account. The rules | |
636 | for daylight savings time vary from place to place and have also varied | |
637 | historically from year to year. To do the job properly, Emacs needs to | |
638 | know which rules to use. | |
639 | ||
640 | Some operating systems keep track of the rules that apply to the place | |
641 | where you are; on these systems, Emacs gets the information it needs | |
642 | from the system automatically. If some or all of this information is | |
643 | missing, Emacs fills in the gaps with the rules currently used in | |
644 | Cambridge, Massachusetts, which is the center of GNU's world. | |
645 | ||
646 | ||
647 | @vindex calendar-daylight-savings-starts | |
648 | @vindex calendar-daylight-savings-ends | |
649 | If the default choice of rules is not appropriate for your location, | |
650 | you can tell Emacs the rules to use by setting the variables | |
651 | @code{calendar-daylight-savings-starts} and | |
652 | @code{calendar-daylight-savings-ends}. Their values should be Lisp | |
653 | expressions that refer to the variable @code{year}, and evaluate to the | |
654 | Gregorian date on which daylight savings time starts or (respectively) | |
655 | ends, in the form of a list @code{(@var{month} @var{day} @var{year})}. | |
656 | The values should be @code{nil} if your area does not use daylight | |
657 | savings time. | |
658 | ||
659 | Emacs uses these expressions to determine the start and end dates of | |
660 | daylight savings time as holidays and for correcting times of day in the | |
661 | solar and lunar calculations. | |
662 | ||
663 | The values for Cambridge, Massachusetts are as follows: | |
664 | ||
665 | @example | |
666 | @group | |
667 | (calendar-nth-named-day 1 0 4 year) | |
668 | (calendar-nth-named-day -1 0 10 year) | |
669 | @end group | |
670 | @end example | |
671 | ||
672 | @noindent | |
673 | i.e., the first 0th day (Sunday) of the fourth month (April) in | |
674 | the year specified by @code{year}, and the last Sunday of the tenth month | |
675 | (October) of that year. If daylight savings time were | |
676 | changed to start on October 1, you would set | |
677 | @code{calendar-daylight-savings-starts} to this: | |
678 | ||
679 | @example | |
680 | (list 10 1 year) | |
681 | @end example | |
682 | ||
683 | For a more complex example, suppose daylight savings time begins on | |
684 | the first of Nisan on the Hebrew calendar. You should set | |
685 | @code{calendar-daylight-savings-starts} to this value: | |
686 | ||
687 | @example | |
688 | (calendar-gregorian-from-absolute | |
689 | (calendar-absolute-from-hebrew | |
690 | (list 1 1 (+ year 3760)))) | |
691 | @end example | |
692 | ||
693 | @noindent | |
694 | because Nisan is the first month in the Hebrew calendar and the Hebrew | |
695 | year differs from the Gregorian year by 3760 at Nisan. | |
696 | ||
697 | If there is no daylight savings time at your location, or if you want | |
698 | all times in standard time, set @code{calendar-daylight-savings-starts} | |
699 | and @code{calendar-daylight-savings-ends} to @code{nil}. | |
700 | ||
701 | @vindex calendar-daylight-time-offset | |
702 | The variable @code{calendar-daylight-time-offset} specifies the | |
703 | difference between daylight savings time and standard time, measured in | |
704 | minutes. The value for Cambridge is 60. | |
705 | ||
706 | @vindex calendar-daylight-savings-starts-time | |
707 | @vindex calendar-daylight-savings-ends-time | |
708 | The variable @code{calendar-daylight-savings-starts-time} and the | |
709 | variable @code{calendar-daylight-savings-ends-time} specify the number | |
710 | of minutes after midnight local time when the transition to and from | |
711 | daylight savings time should occur. For Cambridge, both variables' | |
712 | values are 120. | |
713 | ||
714 | @node Diary Customizing | |
715 | @section Customizing the Diary | |
716 | ||
717 | @vindex holidays-in-diary-buffer | |
718 | Ordinarily, the mode line of the diary buffer window indicates any | |
719 | holidays that fall on the date of the diary entries. The process of | |
720 | checking for holidays can take several seconds, so including holiday | |
721 | information delays the display of the diary buffer noticeably. If you'd | |
722 | prefer to have a faster display of the diary buffer but without the | |
723 | holiday information, set the variable @code{holidays-in-diary-buffer} to | |
724 | @code{nil}.@refill | |
725 | ||
726 | @vindex number-of-diary-entries | |
727 | The variable @code{number-of-diary-entries} controls the number of | |
728 | days of diary entries to be displayed at one time. It affects the | |
729 | initial display when @code{view-diary-entries-initially} is @code{t}, as | |
730 | well as the command @kbd{M-x diary}. For example, the default value is | |
731 | 1, which says to display only the current day's diary entries. If the | |
732 | value is 2, both the current day's and the next day's entries are | |
733 | displayed. The value can also be a vector of seven elements: for | |
734 | example, if the value is @code{[0 2 2 2 2 4 1]} then no diary entries | |
735 | appear on Sunday, the current date's and the next day's diary entries | |
736 | appear Monday through Thursday, Friday through Monday's entries appear | |
737 | on Friday, while on Saturday only that day's entries appear. | |
738 | ||
739 | @vindex print-diary-entries-hook | |
740 | @findex print-diary-entries | |
741 | The variable @code{print-diary-entries-hook} is a normal hook run | |
742 | after preparation of a temporary buffer containing just the diary | |
743 | entries currently visible in the diary buffer. (The other, irrelevant | |
744 | diary entries are really absent from the temporary buffer; in the diary | |
745 | buffer, they are merely hidden.) The default value of this hook does | |
746 | the printing with the command @code{lpr-buffer}. If you want to use a | |
747 | different command to do the printing, just change the value of this | |
748 | hook. Other uses might include, for example, rearranging the lines into | |
749 | order by day and time. | |
750 | ||
751 | @vindex diary-date-forms | |
752 | You can customize the form of dates in your diary file, if neither the | |
753 | standard American nor European styles suits your needs, by setting the | |
754 | variable @code{diary-date-forms}. This variable is a list of patterns | |
755 | for recognizing a date. Each date pattern is a list whose elements may | |
756 | be regular expressions (@pxref{Regular Expressions,,, elisp, the Emacs | |
757 | Lisp Reference Manual}) or the symbols @code{month}, @code{day}, | |
758 | @code{year}, @code{monthname}, and @code{dayname}. All these elements | |
759 | serve as patterns that match certain kinds of text in the diary file. | |
760 | In order for the date pattern, as a whole, to match, all of its elements | |
761 | must match consecutively. | |
762 | ||
763 | A regular expression in a date pattern matches in its usual fashion, | |
764 | using the standard syntax table altered so that @samp{*} is a word | |
765 | constituent. | |
766 | ||
767 | The symbols @code{month}, @code{day}, @code{year}, @code{monthname}, | |
768 | and @code{dayname} match the month number, day number, year number, | |
769 | month name, and day name of the date being considered. The symbols that | |
770 | match numbers allow leading zeros; those that match names allow | |
771 | three-letter abbreviations and capitalization. All the symbols can | |
772 | match @samp{*}; since @samp{*} in a diary entry means ``any day'', ``any | |
773 | month'', and so on, it should match regardless of the date being | |
774 | considered. | |
775 | ||
776 | The default value of @code{diary-date-forms} in the American style is | |
777 | this: | |
778 | ||
779 | @example | |
780 | ((month "/" day "[^/0-9]") | |
781 | (month "/" day "/" year "[^0-9]") | |
782 | (monthname " *" day "[^,0-9]") | |
783 | (monthname " *" day ", *" year "[^0-9]") | |
784 | (dayname "\\W")) | |
785 | @end example | |
786 | ||
787 | The date patterns in the list must be @emph{mutually exclusive} and | |
788 | must not match any portion of the diary entry itself, just the date and | |
789 | one character of whitespace. If, to be mutually exclusive, the pattern | |
790 | must match a portion of the diary entry text---beyond the whitespace | |
791 | that ends the date---then the first element of the date pattern | |
792 | @emph{must} be @code{backup}. This causes the date recognizer to back | |
793 | up to the beginning of the current word of the diary entry, after | |
794 | finishing the match. Even if you use @code{backup}, the date pattern | |
795 | must absolutely not match more than a portion of the first word of the | |
796 | diary entry. The default value of @code{diary-date-forms} in the | |
797 | European style is this list: | |
798 | ||
799 | @example | |
800 | ((day "/" month "[^/0-9]") | |
801 | (day "/" month "/" year "[^0-9]") | |
802 | (backup day " *" monthname "\\W+\\<[^*0-9]") | |
803 | (day " *" monthname " *" year "[^0-9]") | |
804 | (dayname "\\W")) | |
805 | @end example | |
806 | ||
807 | @noindent | |
808 | Notice the use of @code{backup} in the third pattern, because it needs | |
809 | to match part of a word beyond the date itself to distinguish it from | |
810 | the fourth pattern. | |
811 | ||
812 | @node Hebrew/Islamic Entries | |
813 | @section Hebrew- and Islamic-Date Diary Entries | |
814 | ||
815 | Your diary file can have entries based on Hebrew or Islamic dates, as | |
816 | well as entries based on the world-standard Gregorian calendar. | |
817 | However, because recognition of such entries is time-consuming and most | |
818 | people don't use them, you must explicitly enable their use. If you | |
819 | want the diary to recognize Hebrew-date diary entries, for example, | |
820 | you must do this: | |
821 | ||
822 | @vindex nongregorian-diary-listing-hook | |
823 | @vindex nongregorian-diary-marking-hook | |
824 | @findex list-hebrew-diary-entries | |
825 | @findex mark-hebrew-diary-entries | |
826 | @smallexample | |
827 | (add-hook 'nongregorian-diary-listing-hook 'list-hebrew-diary-entries) | |
828 | (add-hook 'nongregorian-diary-marking-hook 'mark-hebrew-diary-entries) | |
829 | @end smallexample | |
830 | ||
831 | @noindent | |
832 | If you want Islamic-date entries, do this: | |
833 | ||
834 | @findex list-islamic-diary-entries | |
835 | @findex mark-islamic-diary-entries | |
836 | @smallexample | |
837 | (add-hook 'nongregorian-diary-listing-hook 'list-islamic-diary-entries) | |
838 | (add-hook 'nongregorian-diary-marking-hook 'mark-islamic-diary-entries) | |
839 | @end smallexample | |
840 | ||
841 | Hebrew- and Islamic-date diary entries have the same formats as | |
842 | Gregorian-date diary entries, except that @samp{H} precedes a Hebrew | |
843 | date and @samp{I} precedes an Islamic date. Moreover, because the | |
844 | Hebrew and Islamic month names are not uniquely specified by the first | |
845 | three letters, you may not abbreviate them. For example, a diary entry | |
846 | for the Hebrew date Heshvan 25 could look like this: | |
847 | ||
848 | @smallexample | |
849 | HHeshvan 25 Happy Hebrew birthday! | |
850 | @end smallexample | |
851 | ||
852 | @noindent | |
853 | and would appear in the diary for any date that corresponds to Heshvan 25 | |
854 | on the Hebrew calendar. And here is an Islamic-date diary entry that matches | |
855 | Dhu al-Qada 25: | |
856 | ||
857 | @smallexample | |
858 | IDhu al-Qada 25 Happy Islamic birthday! | |
859 | @end smallexample | |
860 | ||
861 | As with Gregorian-date diary entries, Hebrew- and Islamic-date entries | |
862 | are nonmarking if they are preceded with an ampersand (@samp{&}). | |
863 | ||
864 | Here is a table of commands used in the calendar to create diary entries | |
865 | that match the selected date and other dates that are similar in the Hebrew | |
866 | or Islamic calendar: | |
867 | ||
868 | @table @kbd | |
869 | @item i h d | |
870 | Add a diary entry for the Hebrew date corresponding to the selected date | |
871 | (@code{insert-hebrew-diary-entry}). | |
872 | @item i h m | |
873 | Add a diary entry for the day of the Hebrew month corresponding to the | |
874 | selected date (@code{insert-monthly-hebrew-diary-entry}). This diary | |
875 | entry matches any date that has the same Hebrew day-within-month as the | |
876 | selected date. | |
877 | @item i h y | |
878 | Add a diary entry for the day of the Hebrew year corresponding to the | |
879 | selected date (@code{insert-yearly-hebrew-diary-entry}). This diary | |
880 | entry matches any date which has the same Hebrew month and day-within-month | |
881 | as the selected date. | |
882 | @item i i d | |
883 | Add a diary entry for the Islamic date corresponding to the selected date | |
884 | (@code{insert-islamic-diary-entry}). | |
885 | @item i i m | |
886 | Add a diary entry for the day of the Islamic month corresponding to the | |
887 | selected date (@code{insert-monthly-islamic-diary-entry}). | |
888 | @item i i y | |
889 | Add a diary entry for the day of the Islamic year corresponding to the | |
890 | selected date (@code{insert-yearly-islamic-diary-entry}). | |
891 | @end table | |
892 | ||
893 | @findex insert-hebrew-diary-entry | |
894 | @findex insert-monthly-hebrew-diary-entry | |
895 | @findex insert-yearly-hebrew-diary-entry | |
896 | @findex insert-islamic-diary-entry | |
897 | @findex insert-monthly-islamic-diary-entry | |
898 | @findex insert-yearly-islamic-diary-entry | |
899 | These commands work much like the corresponding commands for ordinary | |
900 | diary entries: they apply to the date that point is on in the calendar | |
901 | window, and what they do is insert just the date portion of a diary entry | |
902 | at the end of your diary file. You must then insert the rest of the | |
903 | diary entry. | |
904 | ||
905 | @node Fancy Diary Display | |
906 | @section Fancy Diary Display | |
907 | @vindex diary-display-hook | |
908 | @findex simple-diary-display | |
909 | ||
910 | Diary display works by preparing the diary buffer and then running the | |
911 | hook @code{diary-display-hook}. The default value of this hook | |
912 | (@code{simple-diary-display}) hides the irrelevant diary entries and | |
913 | then displays the buffer. However, if you specify the hook as follows, | |
914 | ||
915 | @cindex diary buffer | |
916 | @findex fancy-diary-display | |
917 | @example | |
918 | (add-hook 'diary-display-hook 'fancy-diary-display) | |
919 | @end example | |
920 | ||
921 | @noindent | |
922 | this enables fancy diary display. It displays diary entries and | |
923 | holidays by copying them into a special buffer that exists only for the | |
924 | sake of display. Copying to a separate buffer provides an opportunity | |
925 | to change the displayed text to make it prettier---for example, to sort | |
926 | the entries by the dates they apply to. | |
927 | ||
928 | As with simple diary display, you can print a hard copy of the buffer | |
929 | with @code{print-diary-entries}. To print a hard copy of a day-by-day | |
930 | diary for a week, position point on Sunday of that week, type | |
931 | @kbd{7 d}, and then do @kbd{M-x print-diary-entries}. As usual, the | |
932 | inclusion of the holidays slows down the display slightly; you can speed | |
933 | things up by setting the variable @code{holidays-in-diary-buffer} to | |
934 | @code{nil}. | |
935 | ||
936 | @vindex diary-list-include-blanks | |
937 | Ordinarily, the fancy diary buffer does not show days for which there are | |
938 | no diary entries, even if that day is a holiday. If you want such days to be | |
939 | shown in the fancy diary buffer, set the variable | |
940 | @code{diary-list-include-blanks} to @code{t}.@refill | |
941 | ||
942 | @cindex sorting diary entries | |
943 | If you use the fancy diary display, you can use the normal hook | |
944 | @code{list-diary-entries-hook} to sort each day's diary entries by their | |
945 | time of day. Here's how: | |
946 | ||
947 | @findex sort-diary-entries | |
948 | @example | |
949 | (add-hook 'list-diary-entries-hook 'sort-diary-entries t) | |
950 | @end example | |
951 | ||
952 | @noindent | |
953 | For each day, this sorts diary entries that begin with a recognizable | |
954 | time of day according to their times. Diary entries without times come | |
955 | first within each day. | |
956 | ||
957 | Fancy diary display also has the ability to process included diary | |
958 | files. This permits a group of people to share a diary file for events | |
959 | that apply to all of them. Lines in the diary file of this form: | |
960 | ||
961 | @smallexample | |
962 | #include "@var{filename}" | |
963 | @end smallexample | |
964 | ||
965 | @noindent | |
966 | includes the diary entries from the file @var{filename} in the fancy | |
967 | diary buffer. The include mechanism is recursive, so that included files | |
968 | can include other files, and so on; you must be careful not to have a | |
969 | cycle of inclusions, of course. Here is how to enable the include | |
970 | facility: | |
971 | ||
972 | @vindex list-diary-entries-hook | |
973 | @vindex mark-diary-entries-hook | |
974 | @findex include-other-diary-files | |
975 | @findex mark-included-diary-files | |
976 | @smallexample | |
977 | (add-hook 'list-diary-entries-hook 'include-other-diary-files) | |
978 | (add-hook 'mark-diary-entries-hook 'mark-included-diary-files) | |
979 | @end smallexample | |
980 | ||
981 | The include mechanism works only with the fancy diary display, because | |
982 | ordinary diary display shows the entries directly from your diary file. | |
983 | ||
984 | @node Sexp Diary Entries | |
985 | @section Sexp Entries and the Fancy Diary Display | |
986 | @cindex sexp diary entries | |
987 | ||
988 | Sexp diary entries allow you to do more than just have complicated | |
989 | conditions under which a diary entry applies. If you use the fancy | |
990 | diary display, sexp entries can generate the text of the entry depending | |
991 | on the date itself. For example, an anniversary diary entry can insert | |
992 | the number of years since the anniversary date into the text of the | |
993 | diary entry. Thus the @samp{%d} in this dairy entry: | |
994 | ||
995 | @findex diary-anniversary | |
996 | @smallexample | |
997 | %%(diary-anniversary 10 31 1948) Arthur's birthday (%d years old) | |
998 | @end smallexample | |
999 | ||
1000 | @noindent | |
1001 | gets replaced by the age, so on October 31, 1990 the entry appears in | |
1002 | the fancy diary buffer like this: | |
1003 | ||
1004 | @smallexample | |
1005 | Arthur's birthday (42 years old) | |
1006 | @end smallexample | |
1007 | ||
1008 | @noindent | |
1009 | If the diary file instead contains this entry: | |
1010 | ||
1011 | @smallexample | |
1012 | %%(diary-anniversary 10 31 1948) Arthur's %d%s birthday | |
1013 | @end smallexample | |
1014 | ||
1015 | @noindent | |
1016 | the entry in the fancy diary buffer for October 31, 1990 appears like this: | |
1017 | ||
1018 | @smallexample | |
1019 | Arthur's 42nd birthday | |
1020 | @end smallexample | |
1021 | ||
1022 | Similarly, cyclic diary entries can interpolate the number of repetitions | |
1023 | that have occurred: | |
1024 | ||
1025 | @findex diary-cyclic | |
1026 | @smallexample | |
1027 | %%(diary-cyclic 50 1 1 1990) Renew medication (%d%s time) | |
1028 | @end smallexample | |
1029 | ||
1030 | @noindent | |
1031 | looks like this: | |
1032 | ||
1033 | @smallexample | |
1034 | Renew medication (5th time) | |
1035 | @end smallexample | |
1036 | ||
1037 | @noindent | |
1038 | in the fancy diary display on September 8, 1990. | |
1039 | ||
1040 | There is an early reminder diary sexp that includes its entry in the | |
1041 | diary not only on the date of occurrence, but also on earlier dates. | |
1042 | For example, if you want a reminder a week before your anniversary, you | |
1043 | can use | |
1044 | ||
1045 | @findex diary-remind | |
1046 | @smallexample | |
1047 | %%(diary-remind '(diary-anniversary 12 22 1968) 7) Ed's anniversary | |
1048 | @end smallexample | |
1049 | ||
1050 | @noindent | |
1051 | and the fancy diary will show | |
1052 | @smallexample | |
1053 | Ed's anniversary | |
1054 | @end smallexample | |
1055 | @noindent | |
1056 | both on December 15 and on December 22. | |
1057 | ||
1058 | @findex diary-date | |
1059 | The function @code{diary-date} applies to dates described by a month, | |
1060 | day, year combination, each of which can be an integer, a list of | |
1061 | integers, or @code{t}. The value @code{t} means all values. For | |
1062 | example, | |
1063 | ||
1064 | @smallexample | |
1065 | %%(diary-date '(10 11 12) 22 t) Rake leaves | |
1066 | @end smallexample | |
1067 | ||
1068 | @noindent | |
1069 | causes the fancy diary to show | |
1070 | ||
1071 | @smallexample | |
1072 | Rake leaves | |
1073 | @end smallexample | |
1074 | ||
1075 | @noindent | |
1076 | on October 22, November 22, and December 22 of every year. | |
1077 | ||
1078 | @findex diary-float | |
1079 | The function @code{diary-float} allows you to describe diary entries | |
1080 | that apply to dates like the third Friday of November, or the last | |
1081 | Tuesday in April. The parameters are the @var{month}, @var{dayname}, | |
1082 | and an index @var{n}. The entry appears on the @var{n}th @var{dayname} | |
1083 | of @var{month}, where @var{dayname}=0 means Sunday, 1 means Monday, and | |
1084 | so on. If @var{n} is negative it counts backward from the end of | |
1085 | @var{month}. The value of @var{month} can be a list of months, a single | |
1086 | month, or @code{t} to specify all months. You can also use an optional | |
1087 | parameter @var{day} to specify the @var{n}th @var{dayname} of | |
1088 | @var{month} on or after/before @var{day}; the value of @var{day} defaults | |
1089 | to 1 if @var{n} is positive and to the last day of @var{month} if | |
1090 | @var{n} is negative. For example, | |
1091 | ||
1092 | @smallexample | |
1093 | %%(diary-float t 1 -1) Pay rent | |
1094 | @end smallexample | |
1095 | ||
1096 | @noindent | |
1097 | causes the fancy diary to show | |
1098 | ||
1099 | @smallexample | |
1100 | Pay rent | |
1101 | @end smallexample | |
1102 | ||
1103 | @noindent | |
1104 | on the last Monday of every month. | |
1105 | ||
1106 | The generality of sexp diary entries lets you specify any diary | |
1107 | entry that you can describe algorithmically. A sexp diary entry | |
1108 | contains an expression that computes whether the entry applies to any | |
1109 | given date. If its value is non-@code{nil}, the entry applies to that | |
1110 | date; otherwise, it does not. The expression can use the variable | |
1111 | @code{date} to find the date being considered; its value is a list | |
1112 | (@var{month} @var{day} @var{year}) that refers to the Gregorian | |
1113 | calendar. | |
1114 | ||
1115 | The sexp diary entry applies to a date when the expression's value | |
1116 | is non-@code{nil}, but some values have more specific meanings. If | |
1117 | the value is a string, that string is a description of the event which | |
1118 | occurs on that date. The value can also have the form | |
1119 | @code{(@var{mark} . @var{string})}; then @var{mark} specifies how to | |
1120 | mark the date in the calendar, and @var{string} is the description of | |
1121 | the event. If @var{mark} is a single-character string, that character | |
1122 | appears next to the date in the calendar. If @var{mark} is a face | |
1123 | name, the date is displayed in that face. If @var{mark} is | |
1124 | @code{nil}, that specifies no particular highlighting for the date. | |
1125 | ||
1126 | Suppose you get paid on the 21st of the month if it is a weekday, and | |
1127 | on the Friday before if the 21st is on a weekend. Here is how to write | |
1128 | a sexp diary entry that matches those dates: | |
1129 | ||
1130 | @smallexample | |
1131 | &%%(let ((dayname (calendar-day-of-week date)) | |
1132 | (day (car (cdr date)))) | |
1133 | (or (and (= day 21) (memq dayname '(1 2 3 4 5))) | |
1134 | (and (memq day '(19 20)) (= dayname 5))) | |
1135 | ) Pay check deposited | |
1136 | @end smallexample | |
1137 | ||
1138 | The following sexp diary entries take advantage of the ability (in the fancy | |
1139 | diary display) to concoct diary entries whose text varies based on the date: | |
1140 | ||
1141 | @findex diary-sunrise-sunset | |
1142 | @findex diary-phases-of-moon | |
1143 | @findex diary-day-of-year | |
1144 | @findex diary-iso-date | |
1145 | @findex diary-julian-date | |
1146 | @findex diary-astro-day-number | |
1147 | @findex diary-hebrew-date | |
1148 | @findex diary-islamic-date | |
1149 | @findex diary-french-date | |
1150 | @findex diary-mayan-date | |
1151 | @table @code | |
1152 | @item %%(diary-sunrise-sunset) | |
1153 | Make a diary entry for the local times of today's sunrise and sunset. | |
1154 | @item %%(diary-phases-of-moon) | |
1155 | Make a diary entry for the phases (quarters) of the moon. | |
1156 | @item %%(diary-day-of-year) | |
1157 | Make a diary entry with today's day number in the current year and the number | |
1158 | of days remaining in the current year. | |
1159 | @item %%(diary-iso-date) | |
1160 | Make a diary entry with today's equivalent ISO commercial date. | |
1161 | @item %%(diary-julian-date) | |
1162 | Make a diary entry with today's equivalent date on the Julian calendar. | |
1163 | @item %%(diary-astro-day-number) | |
1164 | Make a diary entry with today's equivalent astronomical (Julian) day number. | |
1165 | @item %%(diary-hebrew-date) | |
1166 | Make a diary entry with today's equivalent date on the Hebrew calendar. | |
1167 | @item %%(diary-islamic-date) | |
1168 | Make a diary entry with today's equivalent date on the Islamic calendar. | |
1169 | @item %%(diary-french-date) | |
1170 | Make a diary entry with today's equivalent date on the French Revolutionary | |
1171 | calendar. | |
1172 | @item %%(diary-mayan-date) | |
1173 | Make a diary entry with today's equivalent date on the Mayan calendar. | |
1174 | @end table | |
1175 | ||
1176 | @noindent | |
1177 | Thus including the diary entry | |
1178 | ||
1179 | @example | |
1180 | &%%(diary-hebrew-date) | |
1181 | @end example | |
1182 | ||
1183 | @noindent | |
1184 | causes every day's diary display to contain the equivalent date on the | |
1185 | Hebrew calendar, if you are using the fancy diary display. (With simple | |
1186 | diary display, the line @samp{&%%(diary-hebrew-date)} appears in the | |
1187 | diary for any date, but does nothing particularly useful.) | |
1188 | ||
1189 | These functions can be used to construct sexp diary entries based on | |
1190 | the Hebrew calendar in certain standard ways: | |
1191 | ||
1192 | @cindex rosh hodesh | |
1193 | @findex diary-rosh-hodesh | |
1194 | @cindex parasha, weekly | |
1195 | @findex diary-parasha | |
1196 | @cindex candle lighting times | |
1197 | @findex diary-sabbath-candles | |
1198 | @cindex omer count | |
1199 | @findex diary-omer | |
1200 | @cindex yahrzeits | |
1201 | @findex diary-yahrzeit | |
1202 | @table @code | |
1203 | @item %%(diary-rosh-hodesh) | |
1204 | Make a diary entry that tells the occurrence and ritual announcement of each | |
1205 | new Hebrew month. | |
1206 | @item %%(diary-parasha) | |
1207 | Make a Saturday diary entry that tells the weekly synagogue scripture reading. | |
1208 | @item %%(diary-sabbath-candles) | |
1209 | Make a Friday diary entry that tells the @emph{local time} of Sabbath | |
1210 | candle lighting. | |
1211 | @item %%(diary-omer) | |
1212 | Make a diary entry that gives the omer count, when appropriate. | |
1213 | @item %%(diary-yahrzeit @var{month} @var{day} @var{year}) @var{name} | |
1214 | Make a diary entry marking the anniversary of a date of death. The date | |
1215 | is the @emph{Gregorian} (civil) date of death. The diary entry appears | |
1216 | on the proper Hebrew calendar anniversary and on the day before. (In | |
1217 | the European style, the order of the parameters is changed to @var{day}, | |
1218 | @var{month}, @var{year}.) | |
1219 | @end table | |
1220 | ||
1221 | All the functions documented above take an optional argument | |
1222 | @var{mark} which specifies how to mark the date in the calendar display. | |
1223 | If one of these functions decides that it applies to a certain date, | |
1224 | it returns a value that contains @var{mark}. | |
1225 | ||
24396ac6 | 1226 | |
4d213d5a LT |
1227 | @node Index |
1228 | @unnumbered Index | |
1229 | ||
1230 | @printindex cp | |
1231 | ||
1232 | @bye | |
93ff1280 MB |
1233 | |
1234 | @ignore | |
1235 | arch-tag: 75c33f13-32c6-41b6-9537-847a312e2e49 | |
1236 | @end ignore |