-\1f
-File: xemacs.info, Node: Adding to Diary, Next: Special Diary Entries, Prev: Date Formats, Up: Diary
-
-Commands to Add to the Diary
-----------------------------
-
- While in the calendar, there are several commands to create diary
-entries:
-
-`i d'
- Add a diary entry for the selected date (`insert-diary-entry').
-
-`i w'
- Add a diary entry for the selected day of the week
- (`insert-weekly-diary-entry').
-
-`i m'
- Add a diary entry for the selected day of the month
- (`insert-monthly-diary-entry').
-
-`i y'
- Add a diary entry for the selected day of the year
- (`insert-yearly-diary-entry').
-
- You can make a diary entry for a specific date by selecting that date
-in the calendar window and typing the `i d' command. This command
-displays the end of your diary file in another window and inserts the
-date; you can then type the rest of the diary entry.
-
- If you want to make a diary entry that applies to a specific day of
-the week, select that day of the week (any occurrence will do) and type
-`i w'. This inserts the day-of-week as a generic date; you can then
-type the rest of the diary entry. You can make a monthly diary entry in
-the same fashion. Select the day of the month, use the `i m' command,
-and type rest of the entry. Similarly, you can insert a yearly diary
-entry with the `i y' command.
-
- All of the above commands make marking diary entries by default. To
-make a nonmarking diary entry, give a numeric argument to the command.
-For example, `C-u i w' makes a nonmarking weekly diary entry.
-
- When you modify the diary file, be sure to save the file before
-exiting Emacs.
-
-\1f
-File: xemacs.info, Node: Special Diary Entries, Prev: Adding to Diary, Up: Diary
-
-Special Diary Entries
----------------------
-
- In addition to entries based on calendar dates, the diary file can
-contain "sexp entries" for regular events such as anniversaries. These
-entries are based on Lisp expressions (sexps) that Emacs evaluates as
-it scans the diary file. Instead of a date, a sexp entry contains `%%'
-followed by a Lisp expression which must begin and end with
-parentheses. The Lisp expression determines which dates the entry
-applies to.
-
- Calendar mode provides commands to insert certain commonly used sexp
-entries:
-
-`i a'
- Add an anniversary diary entry for the selected date
- (`insert-anniversary-diary-entry').
-
-`i b'
- Add a block diary entry for the current region
- (`insert-block-diary-entry').
-
-`i c'
- Add a cyclic diary entry starting at the date
- (`insert-cyclic-diary-entry').
-
- If you want to make a diary entry that applies to the anniversary of
-a specific date, move point to that date and use the `i a' command.
-This displays the end of your diary file in another window and inserts
-the anniversary description; you can then type the rest of the diary
-entry. The entry looks like this:
-
- The effect of `i a' is to add a `diary-anniversary' sexp to your
-diary file. You can also add one manually, for instance:
-
- %%(diary-anniversary 10 31 1948) Arthur's birthday
-
-This entry applies to October 31 in any year after 1948; `10 31 1948'
-specifies the date. (If you are using the European calendar style, the
-month and day are interchanged.) The reason this expression requires a
-beginning year is that advanced diary functions can use it to calculate
-the number of elapsed years.
-
- A "block" diary entry applies to a specified range of consecutive
-dates. Here is a block diary entry that applies to all dates from June
-24, 1990 through July 10, 1990:
-
- %%(diary-block 6 24 1990 7 10 1990) Vacation
-
-The `6 24 1990' indicates the starting date and the `7 10 1990'
-indicates the stopping date. (Again, if you are using the European
-calendar style, the month and day are interchanged.)
-
- To insert a block entry, place point and the mark on the two dates
-that begin and end the range, and type `i b'. This command displays
-the end of your diary file in another window and inserts the block
-description; you can then type the diary entry.
-
- "Cyclic" diary entries repeat after a fixed interval of days. To
-create one, select the starting date and use the `i c' command. The
-command prompts for the length of interval, then inserts the entry,
-which looks like this:
-
- %%(diary-cyclic 50 3 1 1990) Renew medication
-
-This entry applies to March 1, 1990 and every 50th day following; `3 1
-1990' specifies the starting date. (If you are using the European
-calendar style, the month and day are interchanged.)
-
- All three of these commands make marking diary entries. To insert a
-nonmarking entry, give a numeric argument to the command. For example,
-`C-u i a' makes a nonmarking anniversary diary entry.
-
- Marking sexp diary entries in the calendar is _extremely_
-time-consuming, since every date visible in the calendar window must be
-individually checked. So it's a good idea to make sexp diary entries
-nonmarking (with `&') when possible.
-
- Another sophisticated kind of sexp entry, a "floating" diary entry,
-specifies a regularly occurring event by offsets specified in days,
-weeks, and months. It is comparable to a crontab entry interpreted by
-the `cron' utility. Here is a nonmarking, floating diary entry that
-applies to the last Thursday in November:
-
- &%%(diary-float 11 4 -1) American Thanksgiving
-
-The 11 specifies November (the eleventh month), the 4 specifies Thursday
-(the fourth day of the week, where Sunday is numbered zero), and the -1
-specifies "last" (1 would mean "first", 2 would mean "second", -2 would
-mean "second-to-last", and so on). The month can be a single month or
-a list of months. Thus you could change the 11 above to `'(1 2 3)' and
-have the entry apply to the last Thursday of January, February, and
-March. If the month is `t', the entry applies to all months of the
-year.
-
- The sexp feature of the diary allows you to specify diary entries
-based on any Emacs Lisp expression. You can use the library of built-in
-functions or you can write your own functions. The built-in functions
-include the ones shown in this section, plus a few others (*note Sexp
-Diary Entries::).
-
- The generality of sexps lets you specify any diary entry that you can
-describe algorithmically. Suppose you get paid on the 21st of the month
-if it is a weekday, and to the Friday before if the 21st is on a
-weekend. The diary entry
-
- &%%(let ((dayname (calendar-day-of-week date))
- (day (car (cdr date))))
- (or (and (= day 21) (memq dayname '(1 2 3 4 5)))
- (and (memq day '(19 20)) (= dayname 5)))
- ) Pay check deposited
-
-to just those dates. This example illustrates how the sexp can depend
-on the variable `date'; this variable is a list (MONTH DAY YEAR) that
-gives the Gregorian date for which the diary entries are being found.
-If the value of the sexp is `t', the entry applies to that date. If
-the sexp evaluates to `nil', the entry does _not_ apply to that date.
-
-\1f
-File: xemacs.info, Node: Calendar Customization, Prev: Diary, Up: Calendar/Diary
-
-Customizing the Calendar and Diary
-----------------------------------
-
- There are many customizations that you can use to make the calendar
-and diary suit your personal tastes.
-
-* Menu:
-
-* Calendar Customizing:: Defaults you can set.
-* Holiday Customizing:: Defining your own holidays.
-* Date Display Format:: Changing the format.
-* Time Display Format:: Changing the format.
-* Daylight Savings:: Changing the default.
-* Diary Customizing:: Defaults you can set.
-* Hebrew/Islamic Entries:: How to obtain them.
-* Fancy Diary Display:: Enhancing the diary display, sorting entries.
-* Included Diary Files:: Sharing a common diary file.
-* Sexp Diary Entries:: Fancy things you can do.
-* Appt Customizing:: Customizing appointment reminders.
-
-\1f
-File: xemacs.info, Node: Calendar Customizing, Next: Holiday Customizing, Up: Calendar Customization
-
-Customizing the Calendar
-........................
-
- If you set the variable `view-diary-entries-initially' to `t',
-calling up the calendar automatically displays the diary entries for
-the current date as well. The diary dates appear only if the current
-date is visible. If you add both of the following lines to your
-`.emacs' file:
-
- (setq view-diary-entries-initially t)
- (calendar)
-
-this displays both the calendar and diary windows whenever you start
-Emacs.
-
- Similarly, if you set the variable
-`view-calendar-holidays-initially' to `t', entering the calendar
-automatically displays a list of holidays for the current three-month
-period. The holiday list appears in a separate window.
-
- You can set the variable `mark-diary-entries-in-calendar' to `t' in
-order to mark any dates with diary entries. This takes effect whenever
-the calendar window contents are recomputed. There are two ways of
-marking these dates: by changing the face (*note Faces::), if the
-display supports that, or by placing a plus sign (`+') beside the date
-otherwise.
-
- Similarly, setting the variable `mark-holidays-in-calendar' to `t'
-marks holiday dates, either with a change of face or with an asterisk
-(`*').
-
- The variable `calendar-holiday-marker' specifies how to mark a date
-as being a holiday. Its value may be a character to insert next to the
-date, or a face name to use for displaying the date. Likewise, the
-variable `diary-entry-marker' specifies how to mark a date that has
-diary entries. The calendar creates faces named `holiday-face' and
-`diary-face' for these purposes; those symbols are the default values
-of these variables, when Emacs supports multiple faces on your terminal.
-
- The variable `calendar-load-hook' is a normal hook run when the
-calendar package is first loaded (before actually starting to display
-the calendar).
-
- Starting the calendar runs the normal hook
-`initial-calendar-window-hook'. Recomputation of the calendar display
-does not run this hook. But if you leave the calendar with the `q'
-command and reenter it, the hook runs again.
-
- The variable `today-visible-calendar-hook' is a normal hook run
-after the calendar buffer has been prepared with the calendar when the
-current date is visible in the window. One use of this hook is to
-replace today's date with asterisks; to do that, use the hook function
-`calendar-star-date'.
-
- (add-hook 'today-visible-calendar-hook 'calendar-star-date)
-
-Another standard hook function marks the current date, either by
-changing its face or by adding an asterisk. Here's how to use it:
-
- (add-hook 'today-visible-calendar-hook 'calendar-mark-today)
-
-The variable `calendar-today-marker' specifies how to mark today's
-date. Its value should be a character to insert next to the date or a
-face name to use for displaying the date. A face named
-`calendar-today-face' is provided for this purpose; that symbol is the
-default for this variable when Emacs supports multiple faces on your
-terminal.
-
-A similar normal hook, `today-invisible-calendar-hook' is run if the
-current date is _not_ visible in the window.
-
-\1f
-File: xemacs.info, Node: Holiday Customizing, Next: Date Display Format, Prev: Calendar Customizing, Up: Calendar Customization
-
-Customizing the Holidays
-........................
-
- Emacs knows about holidays defined by entries on one of several
-lists. You can customize these lists of holidays to your own needs,
-adding or deleting holidays. The lists of holidays that Emacs uses are
-for general holidays (`general-holidays'), local holidays
-(`local-holidays'), Christian holidays (`christian-holidays'), Hebrew
-(Jewish) holidays (`hebrew-holidays'), Islamic (Moslem) holidays
-(`islamic-holidays'), and other holidays (`other-holidays').
-
- The general holidays are, by default, holidays common throughout the
-United States. To eliminate these holidays, set `general-holidays' to
-`nil'.
-
- There are no default local holidays (but sites may supply some). You
-can set the variable `local-holidays' to any list of holidays, as
-described below.
-
- By default, Emacs does not include all the holidays of the religions
-that it knows, only those commonly found in secular calendars. For a
-more extensive collection of religious holidays, you can set any (or
-all) of the variables `all-christian-calendar-holidays',
-`all-hebrew-calendar-holidays', or `all-islamic-calendar-holidays' to
-`t'. If you want to eliminate the religious holidays, set any or all
-of the corresponding variables `christian-holidays', `hebrew-holidays',
-and `islamic-holidays' to `nil'.
-
- You can set the variable `other-holidays' to any list of holidays.
-This list, normally empty, is intended for individual use.
-
- Each of the lists (`general-holidays', `local-holidays',
-`christian-holidays', `hebrew-holidays', `islamic-holidays', and
-`other-holidays') is a list of "holiday forms", each holiday form
-describing a holiday (or sometimes a list of holidays).
-
- Here is a table of the possible kinds of holiday form. Day numbers
-and month numbers count starting from 1, but "dayname" numbers count
-Sunday as 0. The element STRING is always the name of the holiday, as
-a string.
-
-`(holiday-fixed MONTH DAY STRING)'
- A fixed date on the Gregorian calendar. MONTH and DAY are
- numbers, STRING is the name of the holiday.
-
-`(holiday-float MONTH DAYNAME K STRING)'
- The Kth DAYNAME in MONTH on the Gregorian calendar (DAYNAME=0 for
- Sunday, and so on); negative K means count back from the end of
- the month. STRING is the name of the holiday.
-
-`(holiday-hebrew MONTH DAY STRING)'
- A fixed date on the Hebrew calendar. MONTH and DAY are numbers,
- STRING is the name of the holiday.
-
-`(holiday-islamic MONTH DAY STRING)'
- A fixed date on the Islamic calendar. MONTH and DAY are numbers,
- STRING is the name of the holiday.
-
-`(holiday-julian MONTH DAY STRING)'
- A fixed date on the Julian calendar. MONTH and DAY are numbers,
- STRING is the name of the holiday.
-
-`(holiday-sexp SEXP STRING)'
- A date calculated by the Lisp expression SEXP. The expression
- should use the variable `year' to compute and return the date of a
- holiday, or `nil' if the holiday doesn't happen this year. The
- value of SEXP must represent the date as a list of the form
- `(MONTH DAY YEAR)'. STRING is the name of the holiday.
-
-`(if CONDITION HOLIDAY-FORM &optional HOLIDAY-FORM)'
- A holiday that happens only if CONDITION is true.
-
-`(FUNCTION [ARGS])'
- A list of dates calculated by the function FUNCTION, called with
- arguments ARGS.
-
- For example, suppose you want to add Bastille Day, celebrated in
-France on July 14. You can do this by adding the following line to
-your `.emacs' file:
-
- (setq other-holidays '((holiday-fixed 7 14 "Bastille Day")))
-
-The holiday form `(holiday-fixed 7 14 "Bastille Day")' specifies the
-fourteenth day of the seventh month (July).
-
- Many holidays occur on a specific day of the week, at a specific time
-of month. Here is a holiday form describing Hurricane Supplication Day,
-celebrated in the Virgin Islands on the fourth Monday in August:
-
- (holiday-float 8 1 4 "Hurricane Supplication Day")
-
-Here the 8 specifies August, the 1 specifies Monday (Sunday is 0,
-Tuesday is 2, and so on), and the 4 specifies the fourth occurrence in
-the month (1 specifies the first occurrence, 2 the second occurrence,
--1 the last occurrence, -2 the second-to-last occurrence, and so on).
-
- You can specify holidays that occur on fixed days of the Hebrew,
-Islamic, and Julian calendars too. For example,
-
- (setq other-holidays
- '((holiday-hebrew 10 2 "Last day of Hanukkah")
- (holiday-islamic 3 12 "Mohammed's Birthday")
- (holiday-julian 4 2 "Jefferson's Birthday")))
-
-adds the last day of Hanukkah (since the Hebrew months are numbered with
-1 starting from Nisan), the Islamic feast celebrating Mohammed's
-birthday (since the Islamic months are numbered from 1 starting with
-Muharram), and Thomas Jefferson's birthday, which is 2 April 1743 on the
-Julian calendar.
-
- To include a holiday conditionally, use either Emacs Lisp's `if' or
-the `holiday-sexp' form. For example, American presidential elections
-occur on the first Tuesday after the first Monday in November of years
-divisible by 4:
-
- (holiday-sexp (if (= 0 (% year 4))
- (calendar-gregorian-from-absolute
- (1+ (calendar-dayname-on-or-before
- 1 (+ 6 (calendar-absolute-from-gregorian
- (list 11 1 year))))))
- "US Presidential Election"))
-
-or
-
- (if (= 0 (% displayed-year 4))
- (fixed 11
- (extract-calendar-day
- (calendar-gregorian-from-absolute
- (1+ (calendar-dayname-on-or-before
- 1 (+ 6 (calendar-absolute-from-gregorian
- (list 11 1 displayed-year)))))))
- "US Presidential Election"))
-
- Some holidays just don't fit into any of these forms because special
-calculations are involved in their determination. In such cases you
-must write a Lisp function to do the calculation. To include eclipses,
-for example, add `(eclipses)' to `other-holidays' and write an Emacs
-Lisp function `eclipses' that returns a (possibly empty) list of the
-relevant Gregorian dates among the range visible in the calendar
-window, with descriptive strings, like this:
-
- (((6 27 1991) "Lunar Eclipse") ((7 11 1991) "Solar Eclipse") ... )
-
-\1f
-File: xemacs.info, Node: Date Display Format, Next: Time Display Format, Prev: Holiday Customizing, Up: Calendar Customization
-
-Date Display Format
-...................
-
- You can customize the manner of displaying dates in the diary, in
-mode lines, and in messages by setting `calendar-date-display-form'.
-This variable holds a list of expressions that can involve the variables
-`month', `day', and `year', which are all numbers in string form, and
-`monthname' and `dayname', which are both alphabetic strings. In the
-American style, the default value of this list is as follows:
-
- ((if dayname (concat dayname ", ")) monthname " " day ", " year)
-
-while in the European style this value is the default:
-
- ((if dayname (concat dayname ", ")) day " " monthname " " year)
-
- + The ISO standard date representation is this:
-
- (year "-" month "-" day)
-
-This specifies a typical American format:
-
- (month "/" day "/" (substring year -2))
-
-\1f
-File: xemacs.info, Node: Time Display Format, Next: Daylight Savings, Prev: Date Display Format, Up: Calendar Customization
-
-Time Display Format
-...................
-
- The calendar and diary by default display times of day in the
-conventional American style with the hours from 1 through 12, minutes,
-and either `am' or `pm'. If you prefer the European style, also known
-in the US as military, in which the hours go from 00 to 23, you can
-alter the variable `calendar-time-display-form'. This variable is a
-list of expressions that can involve the variables `12-hours',
-`24-hours', and `minutes', which are all numbers in string form, and
-`am-pm' and `time-zone', which are both alphabetic strings. The
-default value of `calendar-time-display-form' is as follows:
-
- (12-hours ":" minutes am-pm
- (if time-zone " (") time-zone (if time-zone ")"))
-
-Here is a value that provides European style times:
-
- (24-hours ":" minutes
- (if time-zone " (") time-zone (if time-zone ")"))
-
-gives military-style times like `21:07 (UT)' if time zone names are
-defined, and times like `21:07' if they are not.
-
-\1f
-File: xemacs.info, Node: Daylight Savings, Next: Diary Customizing, Prev: Time Display Format, Up: Calendar Customization
-
-Daylight Savings Time
-.....................
-
- Emacs understands the difference between standard time and daylight
-savings time--the times given for sunrise, sunset, solstices,
-equinoxes, and the phases of the moon take that into account. The rules
-for daylight savings time vary from place to place and have also varied
-historically from year to year. To do the job properly, Emacs needs to
-know which rules to use.
-
- Some operating systems keep track of the rules that apply to the
-place where you are; on these systems, Emacs gets the information it
-needs from the system automatically. If some or all of this
-information is missing, Emacs fills in the gaps with the rules
-currently used in Cambridge, Massachusetts. If the resulting rules are
-not what you want, you can tell Emacs the rules to use by setting
-certain variables.
-
- If the default choice of rules is not appropriate for your location,
-you can tell Emacs the rules to use by setting the variables
-`calendar-daylight-savings-starts' and
-`calendar-daylight-savings-ends'. Their values should be Lisp
-expressions that refer to the variable `year', and evaluate to the
-Gregorian date on which daylight savings time starts or (respectively)
-ends, in the form of a list `(MONTH DAY YEAR)'. The values should be
-`nil' if your area does not use daylight savings time.
-
- Emacs uses these expressions to determine the starting date of
-daylight savings time for the holiday list and for correcting times of
-day in the solar and lunar calculations.
-
- The values for Cambridge, Massachusetts are as follows:
-
- (calendar-nth-named-day 1 0 4 year)
- (calendar-nth-named-day -1 0 10 year)
-
-That is, the first 0th day (Sunday) of the fourth month (April) in the
-year specified by `year', and the last Sunday of the tenth month
-(October) of that year. If daylight savings time were changed to start
-on October 1, you would set `calendar-daylight-savings-starts' to this:
-
- (list 10 1 year)
-
- For a more complex example, suppose daylight savings time begins on
-the first of Nisan on the Hebrew calendar. You should set
-`calendar-daylight-savings-starts' to this value:
-
- (calendar-gregorian-from-absolute
- (calendar-absolute-from-hebrew
- (list 1 1 (+ year 3760))))
-
-because Nisan is the first month in the Hebrew calendar and the Hebrew
-year differs from the Gregorian year by 3760 at Nisan.
-
- If there is no daylight savings time at your location, or if you want
-all times in standard time, set `calendar-daylight-savings-starts' and
-`calendar-daylight-savings-ends' to `nil'.
-
- The variable `calendar-daylight-time-offset' specifies the
-difference between daylight savings time and standard time, measured in
-minutes. The value for Cambridge, Massachusetts is 60.
-
- The two variables `calendar-daylight-savings-starts-time' and
-`calendar-daylight-savings-ends-time' specify the number of minutes
-after midnight local time when the transition to and from daylight
-savings time should occur. For Cambridge, Massachusetts both variables'
-values are 120.
-