1 This is Info file ../../info/xemacs.info, produced by Makeinfo version
2 1.68 from the input file xemacs.texi.
4 INFO-DIR-SECTION XEmacs Editor
6 * XEmacs: (xemacs). XEmacs Editor.
9 This file documents the XEmacs editor.
11 Copyright (C) 1985, 1986, 1988 Richard M. Stallman. Copyright (C)
12 1991, 1992, 1993, 1994 Lucid, Inc. Copyright (C) 1993, 1994 Sun
13 Microsystems, Inc. Copyright (C) 1995 Amdahl Corporation.
15 Permission is granted to make and distribute verbatim copies of this
16 manual provided the copyright notice and this permission notice are
17 preserved on all copies.
19 Permission is granted to copy and distribute modified versions of
20 this manual under the conditions for verbatim copying, provided also
21 that the sections entitled "The GNU Manifesto", "Distribution" and "GNU
22 General Public License" are included exactly as in the original, and
23 provided that the entire resulting derived work is distributed under the
24 terms of a permission notice identical to this one.
26 Permission is granted to copy and distribute translations of this
27 manual into another language, under the above conditions for modified
28 versions, except that the sections entitled "The GNU Manifesto",
29 "Distribution" and "GNU General Public License" may be included in a
30 translation approved by the author instead of in the original English.
33 File: xemacs.info, Node: To Other Calendar, Next: From Other Calendar, Prev: Calendar Systems, Up: Other Calendars
35 Converting To Other Calendars
36 =============================
38 The following commands describe the selected date (the date at point)
39 in various other calendar systems:
41 `Button2 Other Calendars'
42 Display the date that you click on, expressed in various other
46 Display ISO commercial calendar equivalent for selected day
47 (`calendar-print-iso-date').
50 Display Julian date for selected day
51 (`calendar-print-julian-date').
54 Display astronomical (Julian) day number for selected day
55 (`calendar-print-astro-day-number').
58 Display Hebrew date for selected day
59 (`calendar-print-hebrew-date').
62 Display Islamic date for selected day
63 (`calendar-print-islamic-date').
66 Display French Revolutionary date for selected day
67 (`calendar-print-french-date').
70 Display Chinese date for selected day
71 (`calendar-print-chinese-date').
74 Display Coptic date for selected day
75 (`calendar-print-coptic-date').
78 Display Ethiopic date for selected day
79 (`calendar-print-ethiopic-date').
82 Display Persian date for selected day
83 (`calendar-print-persian-date').
86 Display Mayan date for selected day (`calendar-print-mayan-date').
88 If you are using X, the easiest way to translate a date into other
89 calendars is to click on it with `Button2', then choose `Other
90 Calendars' from the menu that appears. This displays the equivalent
91 forms of the date in all the calendars Emacs understands, in the form of
92 a menu. (Choosing an alternative from this menu doesn't actually do
93 anything--the menu is used only for display.)
95 Put point on the desired date of the Gregorian calendar, then type
96 the appropriate keys. The `p' is a mnemonic for "print" since Emacs
97 "prints" the equivalent date in the echo area.
100 File: xemacs.info, Node: From Other Calendar, Next: Mayan Calendar, Prev: To Other Calendar, Up: Other Calendars
102 Converting From Other Calendars
103 ===============================
105 You can use the other supported calendars to specify a date to move
106 to. This section describes the commands for doing this using calendars
107 other than Mayan; for the Mayan calendar, see the following section.
110 Move to a date specified in the ISO commercial calendar
111 (`calendar-goto-iso-date').
114 Move to a date specified in the Julian calendar
115 (`calendar-goto-julian-date').
118 Move to a date specified in astronomical (Julian) day number
119 (`calendar-goto-astro-day-number').
122 Move to a date specified in the Hebrew calendar
123 (`calendar-goto-hebrew-date').
126 Move to a date specified in the Islamic calendar
127 (`calendar-goto-islamic-date').
130 Move to a date specified in the French Revolutionary calendar
131 (`calendar-goto-french-date').
134 Move to a date specified in the Chinese calendar
135 (`calendar-goto-chinese-date').
138 Move to a date specified in the Persian calendar
139 (`calendar-goto-persian-date').
142 Move to a date specified in the Coptic calendar
143 (`calendar-goto-coptic-date').
146 Move to a date specified in the Ethiopic calendar
147 (`calendar-goto-ethiopic-date').
149 These commands ask you for a date on the other calendar, move point
150 to the Gregorian calendar date equivalent to that date, and display the
151 other calendar's date in the echo area. Emacs uses strict completion
152 (*note Completion::.) whenever it asks you to type a month name, so you
153 don't have to worry about the spelling of Hebrew, Islamic, or French
156 One common question concerning the Hebrew calendar is the computation
157 of the anniversary of a date of death, called a "yahrzeit." The Emacs
158 calendar includes a facility for such calculations. If you are in the
159 calendar, the command `M-x list-yahrzeit-dates' asks you for a range of
160 years and then displays a list of the yahrzeit dates for those years
161 for the date given by point. If you are not in the calendar, this
162 command first asks you for the date of death and the range of years,
163 and then displays the list of yahrzeit dates.
166 File: xemacs.info, Node: Mayan Calendar, Next: Diary, Prev: From Other Calendar, Up: Other Calendars
168 Converting from the Mayan Calendar
169 ----------------------------------
171 Here are the commands to select dates based on the Mayan calendar:
174 Move to a date specified by the long count calendar
175 (`calendar-goto-mayan-long-count-date').
178 Move to the next occurrence of a place in the tzolkin calendar
179 (`calendar-next-tzolkin-date').
182 Move to the previous occurrence of a place in the tzolkin calendar
183 (`calendar-previous-tzolkin-date').
186 Move to the next occurrence of a place in the haab calendar
187 (`calendar-next-haab-date').
190 Move to the previous occurrence of a place in the haab calendar
191 (`calendar-previous-haab-date').
194 Move to the next occurrence of a place in the calendar round
195 (`calendar-next-calendar-round-date').
198 Move to the previous occurrence of a place in the calendar round
199 (`calendar-previous-calendar-round-date').
201 To understand these commands, you need to understand the Mayan
202 calendars. The "long count" is a counting of days with these units:
204 1 kin = 1 day 1 uinal = 20 kin 1 tun = 18 uinal
205 1 katun = 20 tun 1 baktun = 20 katun
207 Thus, the long count date 12.16.11.16.6 means 12 baktun, 16 katun, 11
208 tun, 16 uinal, and 6 kin. The Emacs calendar can handle Mayan long
209 count dates as early as 7.17.18.13.1, but no earlier. When you use the
210 `g m l' command, type the Mayan long count date with the baktun, katun,
211 tun, uinal, and kin separated by periods.
213 The Mayan tzolkin calendar is a cycle of 260 days formed by a pair of
214 independent cycles of 13 and 20 days. Since this cycle repeats
215 endlessly, Emacs provides commands to move backward and forward to the
216 previous or next point in the cycle. Type `g m p t' to go to the
217 previous tzolkin date; Emacs asks you for a tzolkin date and moves point
218 to the previous occurrence of that date. Similarly, type `g m n t' to
219 go to the next occurrence of a tzolkin date.
221 The Mayan haab calendar is a cycle of 365 days arranged as 18 months
222 of 20 days each, followed a 5-day monthless period. Like the tzolkin
223 cycle, this cycle repeats endlessly, and there are commands to move
224 backward and forward to the previous or next point in the cycle. Type
225 `g m p h' to go to the previous haab date; Emacs asks you for a haab
226 date and moves point to the previous occurrence of that date.
227 Similarly, type `g m n h' to go to the next occurrence of a haab date.
229 The Maya also used the combination of the tzolkin date and the haab
230 date. This combination is a cycle of about 52 years called a *calendar
231 round*. If you type `g m p c', Emacs asks you for both a haab and a
232 tzolkin date and then moves point to the previous occurrence of that
233 combination. Use `g m n c' to move point to the next occurrence of a
234 combination. These commands signal an error if the haab/tzolkin date
235 combination you have typed is impossible.
237 Emacs uses strict completion (*note Completion::.) whenever it asks
238 you to type a Mayan name, so you don't have to worry about spelling.
241 File: xemacs.info, Node: Diary, Next: Calendar Customization, Prev: Mayan Calendar, Up: Calendar/Diary
246 The Emacs diary keeps track of appointments or other events on a
247 daily basis, in conjunction with the calendar. To use the diary
248 feature, you must first create a "diary file" containing a list of
249 events and their dates. Then Emacs can automatically pick out and
250 display the events for today, for the immediate future, or for any
253 By default, Emacs uses `~/diary' as the diary file. This is the
254 same file that the `calendar' utility uses. A sample `~/diary' file is:
256 12/22/1988 Twentieth wedding anniversary!!
257 &1/1. Happy New Year!
258 10/22 Ruth's birthday.
260 Tuesday--weekly meeting with grad students at 10am
261 Supowit, Shen, Bitner, and Kapoor to attend.
262 1/13/89 Friday the thirteenth!!
263 &thu 4pm squash game with Lloyd.
264 mar 16 Dad's birthday
265 April 15, 1989 Income tax due.
266 &* 15 time cards due.
268 This example uses extra spaces to align the event descriptions of most
269 of the entries. Such formatting is purely a matter of taste.
271 Although you probably will start by creating a diary manually, Emacs
272 provides a number of commands to let you view, add, and change diary
273 entries. You can also share diary entries with other users (*note
274 Included Diary Files::.).
278 * Diary Commands:: Viewing diary entries and associated calendar dates.
279 * Format of Diary File:: Entering events in your diary.
280 * Date Formats:: Various ways you can specify dates.
281 * Adding to Diary:: Commands to create diary entries.
282 * Special Diary Entries:: Anniversaries, blocks of dates, cyclic entries, etc.
285 File: xemacs.info, Node: Diary Commands, Next: Format of Diary File, Prev: Diary, Up: Diary
287 Commands Displaying Diary Entries
288 ---------------------------------
290 Once you have created a `~/diary' file, you can use the calendar to
291 view it. You can also view today's events outside of Calendar mode.
294 Display all diary entries for the selected date
295 (`view-diary-entries').
298 Display all diary entries for the date you click on.
301 Display the entire diary file (`show-all-diary-entries').
304 Mark all visible dates that have diary entries
305 (`mark-diary-entries').
308 Unmark the calendar window (`calendar-unmark').
310 `M-x print-diary-entries'
311 Print hard copy of the diary display as it appears.
314 Display all diary entries for today's date.
316 `M-x diary-mail-entries'
317 Mail yourself email reminders about upcoming diary entries.
319 Displaying the diary entries with `d' shows in a separate window the
320 diary entries for the selected date in the calendar. The mode line of
321 the new window shows the date of the diary entries and any holidays
322 that fall on that date. If you specify a numeric argument with `d', it
323 shows all the diary entries for that many successive days. Thus, `2 d'
324 displays all the entries for the selected date and for the following
327 Another way to display the diary entries for a date is to click
328 `Button2' on the date, and then choose `Diary' from the menu that
331 To get a broader view of which days are mentioned in the diary, use
332 the `m' command. This displays the dates that have diary entries in a
333 different face (or places a `+' after these dates, if display with
334 multiple faces is not available). The command applies both to the
335 currently visible months and to other months that subsequently become
336 visible by scrolling. To turn marking off and erase the current marks,
337 type `u', which also turns off holiday marks (*note Holidays::.).
339 To see the full diary file, rather than just some of the entries, use
342 Display of selected diary entries uses the selective display feature
343 to hide entries that don't apply.
345 The diary buffer as you see it is an illusion, so simply printing the
346 buffer does not print what you see on your screen. There is a special
347 command to print hard copy of the diary buffer *as it appears*; this
348 command is `M-x print-diary-entries'. It sends the data directly to
349 the printer. You can customize it like `lpr-region' (*note
352 The command `M-x diary' displays the diary entries for the current
353 date, independently of the calendar display, and optionally for the next
354 few days as well; the variable `number-of-diary-entries' specifies how
355 many days to include (*note Customization::.).
357 If you put `(diary)' in your `.emacs' file, this automatically
358 displays a window with the day's diary entries, when you enter Emacs.
359 The mode line of the displayed window shows the date and any holidays
360 that fall on that date.
362 Many users like to receive notice of events in their diary as email.
363 To send such mail to yourself, use the command `M-x
364 diary-mail-entries'. A prefix argument specifies how many days
365 (starting with today) to check; otherwise, the variable
366 `diary-mail-days' says how many days.
369 File: xemacs.info, Node: Format of Diary File, Next: Date Formats, Prev: Diary Commands, Up: Diary
374 Your "diary file" is a file that records events associated with
375 particular dates. The name of the diary file is specified by the
376 variable `diary-file'; `~/diary' is the default. The `calendar'
377 utility program supports a subset of the format allowed by the Emacs
378 diary facilities, so you can use that utility to view the diary file,
379 with reasonable results aside from the entries it cannot understand.
381 Each entry in the diary file describes one event and consists of one
382 or more lines. An entry always begins with a date specification at the
383 left margin. The rest of the entry is simply text to describe the
384 event. If the entry has more than one line, then the lines after the
385 first must begin with whitespace to indicate they continue a previous
386 entry. Lines that do not begin with valid dates and do not continue a
387 preceding entry are ignored.
389 You can inhibit the marking of certain diary entries in the calendar
390 window; to do this, insert an ampersand (`&') at the beginning of the
391 entry, before the date. This has no effect on display of the entry in
392 the diary window; it affects only marks on dates in the calendar
393 window. Nonmarking entries are especially useful for generic entries
394 that would otherwise mark many different dates.
396 If the first line of a diary entry consists only of the date or day
397 name with no following blanks or punctuation, then the diary window
398 display doesn't include that line; only the continuation lines appear.
399 For example, this entry:
402 Bill B. visits Princeton today
403 2pm Cognitive Studies Committee meeting
404 2:30-5:30 Liz at Lawrenceville
406 7:30pm Dinner at George's
409 appears in the diary window without the date line at the beginning.
410 This style of entry looks neater when you display just a single day's
411 entries, but can cause confusion if you ask for more than one day's
414 You can edit the diary entries as they appear in the window, but it
415 is important to remember that the buffer displayed contains the *entire*
416 diary file, with portions of it concealed from view. This means, for
417 instance, that the `C-f' (`forward-char') command can put point at what
418 appears to be the end of the line, but what is in reality the middle of
421 *Be careful when editing the diary entries!* Inserting additional
422 lines or adding/deleting characters in the middle of a visible line
423 cannot cause problems, but editing at the end of a line may not do what
424 you expect. Deleting a line may delete other invisible entries that
425 follow it. Before editing the diary, it is best to display the entire
426 file with `s' (`show-all-diary-entries').
429 File: xemacs.info, Node: Date Formats, Next: Adding to Diary, Prev: Format of Diary File, Up: Diary
434 Here are some sample diary entries, illustrating different ways of
435 formatting a date. The examples all show dates in American order
436 (month, day, year), but Calendar mode supports European order (day,
437 month, year) as an option.
439 4/20/93 Switch-over to new tabulation system
440 apr. 25 Start tabulating annual results
441 4/30 Results for April are due
442 */25 Monthly cycle finishes
443 Friday Don't leave without backing up files
445 The first entry appears only once, on April 20, 1993. The second and
446 third appear every year on the specified dates, and the fourth uses a
447 wildcard (asterisk) for the month, so it appears on the 25th of every
448 month. The final entry appears every week on Friday.
450 You can use just numbers to express a date, as in `MONTH/DAY' or
451 `MONTH/DAY/YEAR'. This must be followed by a nondigit. In the date
452 itself, MONTH and DAY are numbers of one or two digits. The optional
453 YEAR is also a number, and may be abbreviated to the last two digits;
454 that is, you can use `11/12/1989' or `11/12/89'.
456 Dates can also have the form `MONTHNAME DAY' or `MONTHNAME DAY,
457 YEAR', where the month's name can be spelled in full or abbreviated to
458 three characters (with or without a period). Case is not significant.
460 A date may be "generic"; that is, partially unspecified. Then the
461 entry applies to all dates that match the specification. If the date
462 does not contain a year, it is generic and applies to any year.
463 Alternatively, MONTH, DAY, or YEAR can be a `*'; this matches any
464 month, day, or year, respectively. Thus, a diary entry `3/*/*' matches
465 any day in March of any year; so does `march *'.
467 If you prefer the European style of writing dates--in which the day
468 comes before the month--type `M-x european-calendar' while in the
469 calendar, or set the variable `european-calendar-style' to `t' *before*
470 using any calendar or diary command. This mode interprets all dates in
471 the diary in the European manner, and also uses European style for
472 displaying diary dates. (Note that there is no comma after the
473 MONTHNAME in the European style.) To go back to the (default) American
474 style of writing dates, type `M-x american-calendar'.
476 You can use the name of a day of the week as a generic date which
477 applies to any date falling on that day of the week. You can abbreviate
478 the day of the week to three letters (with or without a period) or spell
479 it in full; case is not significant.
482 File: xemacs.info, Node: Adding to Diary, Next: Special Diary Entries, Prev: Date Formats, Up: Diary
484 Commands to Add to the Diary
485 ----------------------------
487 While in the calendar, there are several commands to create diary
491 Add a diary entry for the selected date (`insert-diary-entry').
494 Add a diary entry for the selected day of the week
495 (`insert-weekly-diary-entry').
498 Add a diary entry for the selected day of the month
499 (`insert-monthly-diary-entry').
502 Add a diary entry for the selected day of the year
503 (`insert-yearly-diary-entry').
505 You can make a diary entry for a specific date by selecting that date
506 in the calendar window and typing the `i d' command. This command
507 displays the end of your diary file in another window and inserts the
508 date; you can then type the rest of the diary entry.
510 If you want to make a diary entry that applies to a specific day of
511 the week, select that day of the week (any occurrence will do) and type
512 `i w'. This inserts the day-of-week as a generic date; you can then
513 type the rest of the diary entry. You can make a monthly diary entry in
514 the same fashion. Select the day of the month, use the `i m' command,
515 and type rest of the entry. Similarly, you can insert a yearly diary
516 entry with the `i y' command.
518 All of the above commands make marking diary entries by default. To
519 make a nonmarking diary entry, give a numeric argument to the command.
520 For example, `C-u i w' makes a nonmarking weekly diary entry.
522 When you modify the diary file, be sure to save the file before
526 File: xemacs.info, Node: Special Diary Entries, Prev: Adding to Diary, Up: Diary
528 Special Diary Entries
529 ---------------------
531 In addition to entries based on calendar dates, the diary file can
532 contain "sexp entries" for regular events such as anniversaries. These
533 entries are based on Lisp expressions (sexps) that Emacs evaluates as
534 it scans the diary file. Instead of a date, a sexp entry contains `%%'
535 followed by a Lisp expression which must begin and end with
536 parentheses. The Lisp expression determines which dates the entry
539 Calendar mode provides commands to insert certain commonly used sexp
543 Add an anniversary diary entry for the selected date
544 (`insert-anniversary-diary-entry').
547 Add a block diary entry for the current region
548 (`insert-block-diary-entry').
551 Add a cyclic diary entry starting at the date
552 (`insert-cyclic-diary-entry').
554 If you want to make a diary entry that applies to the anniversary of
555 a specific date, move point to that date and use the `i a' command.
556 This displays the end of your diary file in another window and inserts
557 the anniversary description; you can then type the rest of the diary
558 entry. The entry looks like this:
560 The effect of `i a' is to add a `diary-anniversary' sexp to your
561 diary file. You can also add one manually, for instance:
563 %%(diary-anniversary 10 31 1948) Arthur's birthday
565 This entry applies to October 31 in any year after 1948; `10 31 1948'
566 specifies the date. (If you are using the European calendar style, the
567 month and day are interchanged.) The reason this expression requires a
568 beginning year is that advanced diary functions can use it to calculate
569 the number of elapsed years.
571 A "block" diary entry applies to a specified range of consecutive
572 dates. Here is a block diary entry that applies to all dates from June
573 24, 1990 through July 10, 1990:
575 %%(diary-block 6 24 1990 7 10 1990) Vacation
577 The `6 24 1990' indicates the starting date and the `7 10 1990'
578 indicates the stopping date. (Again, if you are using the European
579 calendar style, the month and day are interchanged.)
581 To insert a block entry, place point and the mark on the two dates
582 that begin and end the range, and type `i b'. This command displays
583 the end of your diary file in another window and inserts the block
584 description; you can then type the diary entry.
586 "Cyclic" diary entries repeat after a fixed interval of days. To
587 create one, select the starting date and use the `i c' command. The
588 command prompts for the length of interval, then inserts the entry,
589 which looks like this:
591 %%(diary-cyclic 50 3 1 1990) Renew medication
593 This entry applies to March 1, 1990 and every 50th day following; `3 1
594 1990' specifies the starting date. (If you are using the European
595 calendar style, the month and day are interchanged.)
597 All three of these commands make marking diary entries. To insert a
598 nonmarking entry, give a numeric argument to the command. For example,
599 `C-u i a' makes a nonmarking anniversary diary entry.
601 Marking sexp diary entries in the calendar is *extremely*
602 time-consuming, since every date visible in the calendar window must be
603 individually checked. So it's a good idea to make sexp diary entries
604 nonmarking (with `&') when possible.
606 Another sophisticated kind of sexp entry, a "floating" diary entry,
607 specifies a regularly occurring event by offsets specified in days,
608 weeks, and months. It is comparable to a crontab entry interpreted by
609 the `cron' utility. Here is a nonmarking, floating diary entry that
610 applies to the last Thursday in November:
612 &%%(diary-float 11 4 -1) American Thanksgiving
614 The 11 specifies November (the eleventh month), the 4 specifies Thursday
615 (the fourth day of the week, where Sunday is numbered zero), and the -1
616 specifies "last" (1 would mean "first", 2 would mean "second", -2 would
617 mean "second-to-last", and so on). The month can be a single month or
618 a list of months. Thus you could change the 11 above to `'(1 2 3)' and
619 have the entry apply to the last Thursday of January, February, and
620 March. If the month is `t', the entry applies to all months of the
623 The sexp feature of the diary allows you to specify diary entries
624 based on any Emacs Lisp expression. You can use the library of built-in
625 functions or you can write your own functions. The built-in functions
626 include the ones shown in this section, plus a few others (*note Sexp
629 The generality of sexps lets you specify any diary entry that you can
630 describe algorithmically. Suppose you get paid on the 21st of the month
631 if it is a weekday, and to the Friday before if the 21st is on a
632 weekend. The diary entry
634 &%%(let ((dayname (calendar-day-of-week date))
635 (day (car (cdr date))))
636 (or (and (= day 21) (memq dayname '(1 2 3 4 5)))
637 (and (memq day '(19 20)) (= dayname 5)))
638 ) Pay check deposited
640 to just those dates. This example illustrates how the sexp can depend
641 on the variable `date'; this variable is a list (MONTH DAY YEAR) that
642 gives the Gregorian date for which the diary entries are being found.
643 If the value of the sexp is `t', the entry applies to that date. If
644 the sexp evaluates to `nil', the entry does *not* apply to that date.
647 File: xemacs.info, Node: Calendar Customization, Prev: Diary, Up: Calendar/Diary
649 Customizing the Calendar and Diary
650 ----------------------------------
652 There are many customizations that you can use to make the calendar
653 and diary suit your personal tastes.
657 * Calendar Customizing:: Defaults you can set.
658 * Holiday Customizing:: Defining your own holidays.
659 * Date Display Format:: Changing the format.
660 * Time Display Format:: Changing the format.
661 * Daylight Savings:: Changing the default.
662 * Diary Customizing:: Defaults you can set.
663 * Hebrew/Islamic Entries:: How to obtain them.
664 * Fancy Diary Display:: Enhancing the diary display, sorting entries.
665 * Included Diary Files:: Sharing a common diary file.
666 * Sexp Diary Entries:: Fancy things you can do.
667 * Appt Customizing:: Customizing appointment reminders.
670 File: xemacs.info, Node: Calendar Customizing, Next: Holiday Customizing, Up: Calendar Customization
672 Customizing the Calendar
673 ........................
675 If you set the variable `view-diary-entries-initially' to `t',
676 calling up the calendar automatically displays the diary entries for
677 the current date as well. The diary dates appear only if the current
678 date is visible. If you add both of the following lines to your
681 (setq view-diary-entries-initially t)
684 this displays both the calendar and diary windows whenever you start
687 Similarly, if you set the variable
688 `view-calendar-holidays-initially' to `t', entering the calendar
689 automatically displays a list of holidays for the current three-month
690 period. The holiday list appears in a separate window.
692 You can set the variable `mark-diary-entries-in-calendar' to `t' in
693 order to mark any dates with diary entries. This takes effect whenever
694 the calendar window contents are recomputed. There are two ways of
695 marking these dates: by changing the face (*note Faces::.), if the
696 display supports that, or by placing a plus sign (`+') beside the date
699 Similarly, setting the variable `mark-holidays-in-calendar' to `t'
700 marks holiday dates, either with a change of face or with an asterisk
703 The variable `calendar-holiday-marker' specifies how to mark a date
704 as being a holiday. Its value may be a character to insert next to the
705 date, or a face name to use for displaying the date. Likewise, the
706 variable `diary-entry-marker' specifies how to mark a date that has
707 diary entries. The calendar creates faces named `holiday-face' and
708 `diary-face' for these purposes; those symbols are the default values
709 of these variables, when Emacs supports multiple faces on your terminal.
711 The variable `calendar-load-hook' is a normal hook run when the
712 calendar package is first loaded (before actually starting to display
715 Starting the calendar runs the normal hook
716 `initial-calendar-window-hook'. Recomputation of the calendar display
717 does not run this hook. But if you leave the calendar with the `q'
718 command and reenter it, the hook runs again.
720 The variable `today-visible-calendar-hook' is a normal hook run
721 after the calendar buffer has been prepared with the calendar when the
722 current date is visible in the window. One use of this hook is to
723 replace today's date with asterisks; to do that, use the hook function
724 `calendar-star-date'.
726 (add-hook 'today-visible-calendar-hook 'calendar-star-date)
728 Another standard hook function marks the current date, either by
729 changing its face or by adding an asterisk. Here's how to use it:
731 (add-hook 'today-visible-calendar-hook 'calendar-mark-today)
733 The variable `calendar-today-marker' specifies how to mark today's
734 date. Its value should be a character to insert next to the date or a
735 face name to use for displaying the date. A face named
736 `calendar-today-face' is provided for this purpose; that symbol is the
737 default for this variable when Emacs supports multiple faces on your
740 A similar normal hook, `today-invisible-calendar-hook' is run if the
741 current date is *not* visible in the window.
744 File: xemacs.info, Node: Holiday Customizing, Next: Date Display Format, Prev: Calendar Customizing, Up: Calendar Customization
746 Customizing the Holidays
747 ........................
749 Emacs knows about holidays defined by entries on one of several
750 lists. You can customize these lists of holidays to your own needs,
751 adding or deleting holidays. The lists of holidays that Emacs uses are
752 for general holidays (`general-holidays'), local holidays
753 (`local-holidays'), Christian holidays (`christian-holidays'), Hebrew
754 (Jewish) holidays (`hebrew-holidays'), Islamic (Moslem) holidays
755 (`islamic-holidays'), and other holidays (`other-holidays').
757 The general holidays are, by default, holidays common throughout the
758 United States. To eliminate these holidays, set `general-holidays' to
761 There are no default local holidays (but sites may supply some). You
762 can set the variable `local-holidays' to any list of holidays, as
765 By default, Emacs does not include all the holidays of the religions
766 that it knows, only those commonly found in secular calendars. For a
767 more extensive collection of religious holidays, you can set any (or
768 all) of the variables `all-christian-calendar-holidays',
769 `all-hebrew-calendar-holidays', or `all-islamic-calendar-holidays' to
770 `t'. If you want to eliminate the religious holidays, set any or all
771 of the corresponding variables `christian-holidays', `hebrew-holidays',
772 and `islamic-holidays' to `nil'.
774 You can set the variable `other-holidays' to any list of holidays.
775 This list, normally empty, is intended for individual use.
777 Each of the lists (`general-holidays', `local-holidays',
778 `christian-holidays', `hebrew-holidays', `islamic-holidays', and
779 `other-holidays') is a list of "holiday forms", each holiday form
780 describing a holiday (or sometimes a list of holidays).
782 Here is a table of the possible kinds of holiday form. Day numbers
783 and month numbers count starting from 1, but "dayname" numbers count
784 Sunday as 0. The element STRING is always the name of the holiday, as
787 `(holiday-fixed MONTH DAY STRING)'
788 A fixed date on the Gregorian calendar. MONTH and DAY are
789 numbers, STRING is the name of the holiday.
791 `(holiday-float MONTH DAYNAME K STRING)'
792 The Kth DAYNAME in MONTH on the Gregorian calendar (DAYNAME=0 for
793 Sunday, and so on); negative K means count back from the end of
794 the month. STRING is the name of the holiday.
796 `(holiday-hebrew MONTH DAY STRING)'
797 A fixed date on the Hebrew calendar. MONTH and DAY are numbers,
798 STRING is the name of the holiday.
800 `(holiday-islamic MONTH DAY STRING)'
801 A fixed date on the Islamic calendar. MONTH and DAY are numbers,
802 STRING is the name of the holiday.
804 `(holiday-julian MONTH DAY STRING)'
805 A fixed date on the Julian calendar. MONTH and DAY are numbers,
806 STRING is the name of the holiday.
808 `(holiday-sexp SEXP STRING)'
809 A date calculated by the Lisp expression SEXP. The expression
810 should use the variable `year' to compute and return the date of a
811 holiday, or `nil' if the holiday doesn't happen this year. The
812 value of SEXP must represent the date as a list of the form
813 `(MONTH DAY YEAR)'. STRING is the name of the holiday.
815 `(if CONDITION HOLIDAY-FORM &optional HOLIDAY-FORM)'
816 A holiday that happens only if CONDITION is true.
819 A list of dates calculated by the function FUNCTION, called with
822 For example, suppose you want to add Bastille Day, celebrated in
823 France on July 14. You can do this by adding the following line to
826 (setq other-holidays '((holiday-fixed 7 14 "Bastille Day")))
828 The holiday form `(holiday-fixed 7 14 "Bastille Day")' specifies the
829 fourteenth day of the seventh month (July).
831 Many holidays occur on a specific day of the week, at a specific time
832 of month. Here is a holiday form describing Hurricane Supplication Day,
833 celebrated in the Virgin Islands on the fourth Monday in August:
835 (holiday-float 8 1 4 "Hurricane Supplication Day")
837 Here the 8 specifies August, the 1 specifies Monday (Sunday is 0,
838 Tuesday is 2, and so on), and the 4 specifies the fourth occurrence in
839 the month (1 specifies the first occurrence, 2 the second occurrence,
840 -1 the last occurrence, -2 the second-to-last occurrence, and so on).
842 You can specify holidays that occur on fixed days of the Hebrew,
843 Islamic, and Julian calendars too. For example,
846 '((holiday-hebrew 10 2 "Last day of Hanukkah")
847 (holiday-islamic 3 12 "Mohammed's Birthday")
848 (holiday-julian 4 2 "Jefferson's Birthday")))
850 adds the last day of Hanukkah (since the Hebrew months are numbered with
851 1 starting from Nisan), the Islamic feast celebrating Mohammed's
852 birthday (since the Islamic months are numbered from 1 starting with
853 Muharram), and Thomas Jefferson's birthday, which is 2 April 1743 on the
856 To include a holiday conditionally, use either Emacs Lisp's `if' or
857 the `holiday-sexp' form. For example, American presidential elections
858 occur on the first Tuesday after the first Monday in November of years
861 (holiday-sexp (if (= 0 (% year 4))
862 (calendar-gregorian-from-absolute
863 (1+ (calendar-dayname-on-or-before
864 1 (+ 6 (calendar-absolute-from-gregorian
865 (list 11 1 year))))))
866 "US Presidential Election"))
870 (if (= 0 (% displayed-year 4))
872 (extract-calendar-day
873 (calendar-gregorian-from-absolute
874 (1+ (calendar-dayname-on-or-before
875 1 (+ 6 (calendar-absolute-from-gregorian
876 (list 11 1 displayed-year)))))))
877 "US Presidential Election"))
879 Some holidays just don't fit into any of these forms because special
880 calculations are involved in their determination. In such cases you
881 must write a Lisp function to do the calculation. To include eclipses,
882 for example, add `(eclipses)' to `other-holidays' and write an Emacs
883 Lisp function `eclipses' that returns a (possibly empty) list of the
884 relevant Gregorian dates among the range visible in the calendar
885 window, with descriptive strings, like this:
887 (((6 27 1991) "Lunar Eclipse") ((7 11 1991) "Solar Eclipse") ... )
890 File: xemacs.info, Node: Date Display Format, Next: Time Display Format, Prev: Holiday Customizing, Up: Calendar Customization
895 You can customize the manner of displaying dates in the diary, in
896 mode lines, and in messages by setting `calendar-date-display-form'.
897 This variable holds a list of expressions that can involve the variables
898 `month', `day', and `year', which are all numbers in string form, and
899 `monthname' and `dayname', which are both alphabetic strings. In the
900 American style, the default value of this list is as follows:
902 ((if dayname (concat dayname ", ")) monthname " " day ", " year)
904 while in the European style this value is the default:
906 ((if dayname (concat dayname ", ")) day " " monthname " " year)
908 + The ISO standard date representation is this:
910 (year "-" month "-" day)
912 This specifies a typical American format:
914 (month "/" day "/" (substring year -2))
917 File: xemacs.info, Node: Time Display Format, Next: Daylight Savings, Prev: Date Display Format, Up: Calendar Customization
922 The calendar and diary by default display times of day in the
923 conventional American style with the hours from 1 through 12, minutes,
924 and either `am' or `pm'. If you prefer the European style, also known
925 in the US as military, in which the hours go from 00 to 23, you can
926 alter the variable `calendar-time-display-form'. This variable is a
927 list of expressions that can involve the variables `12-hours',
928 `24-hours', and `minutes', which are all numbers in string form, and
929 `am-pm' and `time-zone', which are both alphabetic strings. The
930 default value of `calendar-time-display-form' is as follows:
932 (12-hours ":" minutes am-pm
933 (if time-zone " (") time-zone (if time-zone ")"))
935 Here is a value that provides European style times:
937 (24-hours ":" minutes
938 (if time-zone " (") time-zone (if time-zone ")"))
940 gives military-style times like `21:07 (UT)' if time zone names are
941 defined, and times like `21:07' if they are not.
944 File: xemacs.info, Node: Daylight Savings, Next: Diary Customizing, Prev: Time Display Format, Up: Calendar Customization
946 Daylight Savings Time
947 .....................
949 Emacs understands the difference between standard time and daylight
950 savings time--the times given for sunrise, sunset, solstices,
951 equinoxes, and the phases of the moon take that into account. The rules
952 for daylight savings time vary from place to place and have also varied
953 historically from year to year. To do the job properly, Emacs needs to
954 know which rules to use.
956 Some operating systems keep track of the rules that apply to the
957 place where you are; on these systems, Emacs gets the information it
958 needs from the system automatically. If some or all of this
959 information is missing, Emacs fills in the gaps with the rules
960 currently used in Cambridge, Massachusetts. If the resulting rules are
961 not what you want, you can tell Emacs the rules to use by setting
964 If the default choice of rules is not appropriate for your location,
965 you can tell Emacs the rules to use by setting the variables
966 `calendar-daylight-savings-starts' and
967 `calendar-daylight-savings-ends'. Their values should be Lisp
968 expressions that refer to the variable `year', and evaluate to the
969 Gregorian date on which daylight savings time starts or (respectively)
970 ends, in the form of a list `(MONTH DAY YEAR)'. The values should be
971 `nil' if your area does not use daylight savings time.
973 Emacs uses these expressions to determine the starting date of
974 daylight savings time for the holiday list and for correcting times of
975 day in the solar and lunar calculations.
977 The values for Cambridge, Massachusetts are as follows:
979 (calendar-nth-named-day 1 0 4 year)
980 (calendar-nth-named-day -1 0 10 year)
982 That is, the first 0th day (Sunday) of the fourth month (April) in the
983 year specified by `year', and the last Sunday of the tenth month
984 (October) of that year. If daylight savings time were changed to start
985 on October 1, you would set `calendar-daylight-savings-starts' to this:
989 For a more complex example, suppose daylight savings time begins on
990 the first of Nisan on the Hebrew calendar. You should set
991 `calendar-daylight-savings-starts' to this value:
993 (calendar-gregorian-from-absolute
994 (calendar-absolute-from-hebrew
995 (list 1 1 (+ year 3760))))
997 because Nisan is the first month in the Hebrew calendar and the Hebrew
998 year differs from the Gregorian year by 3760 at Nisan.
1000 If there is no daylight savings time at your location, or if you want
1001 all times in standard time, set `calendar-daylight-savings-starts' and
1002 `calendar-daylight-savings-ends' to `nil'.
1004 The variable `calendar-daylight-time-offset' specifies the
1005 difference between daylight savings time and standard time, measured in
1006 minutes. The value for Cambridge, Massachusetts is 60.
1008 The two variables `calendar-daylight-savings-starts-time' and
1009 `calendar-daylight-savings-ends-time' specify the number of minutes
1010 after midnight local time when the transition to and from daylight
1011 savings time should occur. For Cambridge, Massachusetts both variables'
1015 File: xemacs.info, Node: Diary Customizing, Next: Hebrew/Islamic Entries, Prev: Daylight Savings, Up: Calendar Customization
1017 Customizing the Diary
1018 .....................
1020 Ordinarily, the mode line of the diary buffer window indicates any
1021 holidays that fall on the date of the diary entries. The process of
1022 checking for holidays can take several seconds, so including holiday
1023 information delays the display of the diary buffer noticeably. If you'd
1024 prefer to have a faster display of the diary buffer but without the
1025 holiday information, set the variable `holidays-in-diary-buffer' to
1028 The variable `number-of-diary-entries' controls the number of days
1029 of diary entries to be displayed at one time. It affects the initial
1030 display when `view-diary-entries-initially' is `t', as well as the
1031 command `M-x diary'. For example, the default value is 1, which says
1032 to display only the current day's diary entries. If the value is 2,
1033 both the current day's and the next day's entries are displayed. The
1034 value can also be a vector of seven elements: for example, if the value
1035 is `[0 2 2 2 2 4 1]' then no diary entries appear on Sunday, the
1036 current date's and the next day's diary entries appear Monday through
1037 Thursday, Friday through Monday's entries appear on Friday, while on
1038 Saturday only that day's entries appear.
1040 The variable `print-diary-entries-hook' is a normal hook run after
1041 preparation of a temporary buffer containing just the diary entries
1042 currently visible in the diary buffer. (The other, irrelevant diary
1043 entries are really absent from the temporary buffer; in the diary
1044 buffer, they are merely hidden.) The default value of this hook does
1045 the printing with the command `lpr-buffer'. If you want to use a
1046 different command to do the printing, just change the value of this
1047 hook. Other uses might include, for example, rearranging the lines into
1048 order by day and time.
1050 You can customize the form of dates in your diary file, if neither
1051 the standard American nor European styles suits your needs, by setting
1052 the variable `diary-date-forms'. This variable is a list of patterns
1053 for recognizing a date. Each date pattern is a list whose elements may
1054 be regular expressions (*note Regexps::.) or the symbols `month',
1055 `day', `year', `monthname', and `dayname'. All these elements serve as
1056 patterns that match certain kinds of text in the diary file. In order
1057 for the date pattern, as a whole, to match, all of its elements must
1058 match consecutively.
1060 A regular expression in a date pattern matches in its usual fashion,
1061 using the standard syntax table altered so that `*' is a word
1064 The symbols `month', `day', `year', `monthname', and `dayname' match
1065 the month number, day number, year number, month name, and day name of
1066 the date being considered. The symbols that match numbers allow
1067 leading zeros; those that match names allow three-letter abbreviations
1068 and capitalization. All the symbols can match `*'; since `*' in a
1069 diary entry means "any day", "any month", and so on, it should match
1070 regardless of the date being considered.
1072 The default value of `diary-date-forms' in the American style is
1075 ((month "/" day "[^/0-9]")
1076 (month "/" day "/" year "[^0-9]")
1077 (monthname " *" day "[^,0-9]")
1078 (monthname " *" day ", *" year "[^0-9]")
1081 Emacs matches of the diary entries with the date forms is done with the
1082 standard syntax table from Fundamental mode (*note Syntax Tables:
1083 (lispref)Syntax Tables.), but with the `*' changed so that it is a word
1086 The date patterns in the list must be *mutually exclusive* and must
1087 not match any portion of the diary entry itself, just the date and one
1088 character of whitespace. If, to be mutually exclusive, the pattern
1089 must match a portion of the diary entry text--beyond the whitespace
1090 that ends the date--then the first element of the date pattern *must*
1091 be `backup'. This causes the date recognizer to back up to the
1092 beginning of the current word of the diary entry, after finishing the
1093 match. Even if you use `backup', the date pattern must absolutely not
1094 match more than a portion of the first word of the diary entry. The
1095 default value of `diary-date-forms' in the European style is this list:
1097 ((day "/" month "[^/0-9]")
1098 (day "/" month "/" year "[^0-9]")
1099 (backup day " *" monthname "\\W+\\<[^*0-9]")
1100 (day " *" monthname " *" year "[^0-9]")
1103 Notice the use of `backup' in the third pattern, because it needs to
1104 match part of a word beyond the date itself to distinguish it from the
1108 File: xemacs.info, Node: Hebrew/Islamic Entries, Next: Fancy Diary Display, Prev: Diary Customizing, Up: Calendar Customization
1110 Hebrew- and Islamic-Date Diary Entries
1111 ......................................
1113 Your diary file can have entries based on Hebrew or Islamic dates, as
1114 well as entries based on the world-standard Gregorian calendar.
1115 However, because recognition of such entries is time-consuming and most
1116 people don't use them, you must explicitly enable their use. If you
1117 want the diary to recognize Hebrew-date diary entries, for example, you
1120 (add-hook 'nongregorian-diary-listing-hook 'list-hebrew-diary-entries)
1121 (add-hook 'nongregorian-diary-marking-hook 'mark-hebrew-diary-entries)
1123 If you want Islamic-date entries, do this:
1125 (add-hook 'nongregorian-diary-listing-hook 'list-islamic-diary-entries)
1126 (add-hook 'nongregorian-diary-marking-hook 'mark-islamic-diary-entries)
1128 Hebrew- and Islamic-date diary entries have the same formats as
1129 Gregorian-date diary entries, except that `H' precedes a Hebrew date
1130 and `I' precedes an Islamic date. Moreover, because the Hebrew and
1131 Islamic month names are not uniquely specified by the first three
1132 letters, you may not abbreviate them. For example, a diary entry for
1133 the Hebrew date Heshvan 25 could look like this:
1135 HHeshvan 25 Happy Hebrew birthday!
1137 and would appear in the diary for any date that corresponds to Heshvan
1138 25 on the Hebrew calendar. And here is Islamic-date diary entry that
1139 matches Dhu al-Qada 25:
1141 IDhu al-Qada 25 Happy Islamic birthday!
1143 and would appear in the diary for any date that corresponds to Dhu
1144 al-Qada 25 on the Islamic calendar.
1146 As with Gregorian-date diary entries, Hebrew- and Islamic-date
1147 entries are nonmarking if they are preceded with an ampersand (`&').
1149 Here is a table of commands used in the calendar to create diary
1150 entries that match the selected date and other dates that are similar
1151 in the Hebrew or Islamic calendar:
1154 Add a diary entry for the Hebrew date corresponding to the
1155 selected date (`insert-hebrew-diary-entry').
1158 Add a diary entry for the day of the Hebrew month corresponding to
1159 the selected date (`insert-monthly-hebrew-diary-entry'). This
1160 diary entry matches any date that has the same Hebrew
1161 day-within-month as the selected date.
1164 Add a diary entry for the day of the Hebrew year corresponding to
1165 the selected date (`insert-yearly-hebrew-diary-entry'). This diary
1166 entry matches any date which has the same Hebrew month and
1167 day-within-month as the selected date.
1170 Add a diary entry for the Islamic date corresponding to the
1171 selected date (`insert-islamic-diary-entry').
1174 Add a diary entry for the day of the Islamic month corresponding
1175 to the selected date (`insert-monthly-islamic-diary-entry').
1178 Add a diary entry for the day of the Islamic year corresponding to
1179 the selected date (`insert-yearly-islamic-diary-entry').
1181 These commands work much like the corresponding commands for ordinary
1182 diary entries: they apply to the date that point is on in the calendar
1183 window, and what they do is insert just the date portion of a diary
1184 entry at the end of your diary file. You must then insert the rest of