xemacs-beta: man/xemacs/calendar.texi comparison

comparison man/xemacs/calendar.texi @ 0:376386a54a3c r19-14

Import from CVS: tag r19-14

author	cvs
date	Mon, 13 Aug 2007 08:45:50 +0200
parents
children	ac2d302a0011

comparison

equal deleted inserted replaced

--1:000000000000
+:376386a54a3c
+@node Calendar/Diary, Sorting, Reading Mail, Top
+@section Calendar Mode and the Diary
+@cindex calendar
+@findex calendar
+Emacs provides the functions of a desk calendar, with a diary of past
+or planned events.  Display the calendar by typing @kbd{M-x calendar}.
+This command creates a window containing a three-month calendar centered
+on the current month, with point on the current date.  Or, provide a
+prefix argument by typing @kbd{C-u M-x calendar}; then you are prompted
+for the month and year to be the center of the three-month calendar.  In
+either case, you are now in Calendar mode.
+Calendar mode makes it easy to look at the holidays or diary entries
+associated with various dates, and to change the diary entries.  You can move
+freely between the Calendar window and other windows.  To exit the calendar,
+type @kbd{q}.
+@menu
+* Calendar Motion::        Moving through the calendar; selecting a date.
+* Scroll Calendar::        Bringing earlier or later months onto the screen.
+* Mark and Region::        Remembering dates, the mark ring.
+* General Calendar::       Conveniences for moving about.
+* Holidays::               Displaying dates of holidays.
+* Sunrise/Sunset::         Displaying local times of sunrise and sunset.
+* Lunar Phases::           Displaying phases of the moon.
+* Other Calendars::        Converting dates to other calendar systems.
+* Diary::                  Displaying events from your diary.
+* Calendar Customization:: Altering the behavior of the features above.
+@end menu
+@node Calendar Motion, Scroll Calendar, Calendar/Diary, Calendar/Diary
+@subsection Movement in the Calendar
+Calendar mode lets you move in logical units of time such as days,
+weeks, months, and years.  Sometimes you need to move to a specific date
+in order to enter commands affecting its display or the associated diary
+entries.  If you move outside the three months originally displayed, the
+calendar display scrolls automatically through time.
+@menu
+* Calendar Unit Motion::       Moving by days, weeks, months, and years.
+* Move to Beginning or End::   Moving to start/end of weeks, months, and years.
+* Specified Dates::            Moving to the current date or another specific date.
+@end menu
+@node Calendar Unit Motion, Move to Beginning or End, Calendar Motion, Calendar Motion
+@subsubsection Motion by Integral Days, Weeks, Months, Years
+The commands for movement in the calendar buffer parallel the
+commands for movement in text.  You can move forward and backward by
+days, weeks, months, and years.
+@table @kbd
+@item C-f
+Move point one day forward (@code{calendar-forward-day}).
+@item C-b
+Move point one day backward (@code{calendar-backward-day}).
+@item C-n
+Move point one week forward (@code{calendar-forward-week}).
+@item C-p
+Move point one week backward (@code{calendar-backward-week}).
+@item M-@}
+Move point one month forward (@code{calendar-forward-month}).
+@item M-@{
+Move point one month backward (@code{calendar-backward-month}).
+@item C-x ]
+Move point one year forward (@code{calendar-forward-year}).
+@item C-x [
+Move point one year backward (@code{calendar-forward-year}).
+@end table
+@kindex C-f (Calendar mode)
+@findex calendar-forward-day
+@kindex C-b (Calendar mode)
+@findex calendar-backward-day
+@kindex C-n (Calendar mode)
+@findex calendar-forward-week
+@kindex C-p (Calendar mode)
+@findex calendar-backward-week
+The day and week commands are natural analogues of the usual Emacs
+commands for moving by characters and by lines.  Just as @kbd{C-n}
+usually moves to the same column in the following line, in Calendar
+mode it moves to the same day in the following week.  And @kbd{C-p}
+moves to the same day in the previous week.
+@kindex M-@} (Calendar mode)
+@findex calendar-forward-month
+@kindex M-@{ (Calendar mode)
+@findex calendar-backward-month
+@kindex C-x ] (Calendar mode)
+@findex calendar-forward-year
+@kindex C-x [ (Calendar mode)
+@findex calendar-forward-year
+The commands for motion by months and years work like those for
+weeks, but move a larger distance.  The month commands @kbd{M-@}} and
+@kbd{M-@{} move forward or backward by an entire month's time.  The
+year commands @kbd{C-x ]} and @kbd{C-x [} move forward or backward a
+whole year.
+The easiest way to remember these commands is to consider months and
+years analogous to paragraphs and pages of text, respectively.  But the
+commands themselves are not quite analogous.  The ordinary Emacs paragraph
+commands move to the beginning or end of a paragraph, whereas these month
+and year commands move by an entire month or an entire year, which usually
+involves skipping across the end of a month or year.
+Each of these commands accepts a numeric argument as a repeat count.  For
+convenience, the digit keys and the minus sign are bound in Calendar mode so
+that it is unnecessary to type the @kbd{M-} prefix.  For example, @kbd{100
+C-f} moves point 100 days forward from its present location.
+@node Move to Beginning or End, Specified Dates, Calendar Unit Motion, Calendar Motion
+@subsubsection Beginning or End of Week, Month or Year
+A week (or month, or year) is not just a quantity of days; we think
+of new weeks (months, years) as starting on particular days.  So
+Calendar mode provides commands to move to the beginning or end of the
+week, month or year:
+@table @kbd
+@kindex C-a (Calendar mode)
+@findex calendar-beginning-of-week
+@item C-a
+Move point to beginning of week (@code{calendar-beginning-of-week}).
+@kindex C-e (Calendar mode)
+@findex calendar-end-of-week
+@item C-e
+Move point to end of week (@code{calendar-end-of-week}).
+@kindex M-a (Calendar mode)
+@findex calendar-beginning-of-month
+@item M-a
+Move point to beginning of month (@code{calendar-beginning-of-month}).
+@kindex M-e (Calendar mode)
+@findex calendar-end-of-month
+@item M-e
+Move point to end of month (@code{calendar-end-of-month}).
+@kindex M-< (Calendar mode)
+@findex calendar-beginning-of-year
+@item M-<
+Move point to beginning of year (@code{calendar-beginning-of-year}).
+@kindex M-> (Calendar mode)
+@findex calendar-end-of-year
+@item M->
+Move point to end of year (@code{calendar-end-of-year}).
+@end table
+These commands also take numeric arguments as repeat counts, with the
+repeat count indicating how many weeks, months, or years to move
+backward or forward.
+@node Specified Dates,,Move to Beginning or End, Calendar Motion
+@subsubsection Particular Dates
+Calendar mode provides some commands for getting to a particular date
+quickly.
+@table @kbd
+@item g d
+Move point to specified date (@code{calendar-goto-date}).
+@item o
+Center calendar around specified month (@code{calendar-other-month}).
+@item .
+Move point to today's date (@code{calendar-current-month}).
+@end table
+@kindex g d (Calendar mode)
+@findex calendar-goto-date
+@kbd{g d} (@code{calendar-goto-date}) prompts for a year, a month, and a day
+of the month, and then goes to that date.  Because the calendar includes all
+dates from the beginning of the current era, you must type the year in its
+entirety; that is, type @samp{1990}, not @samp{90}.
+@kindex o (Calendar mode)
+@findex calendar-other-month
+@kbd{o} (@code{calendar-other-month}) prompts for a month and year,
+then centers the three-month calendar around that month.
+@kindex . (Calendar mode)
+@findex calendar-current-month
+You can return to the current date with @kbd{.}
+(@code{calendar-current-month}).
+@node Scroll Calendar, Mark and Region, Calendar Motion, Calendar/Diary
+@subsection Scrolling the Calendar through Time
+The calendar display scrolls automatically through time when you move out
+of the visible portion.  You can also scroll it manually.  Imagine that the
+calendar window contains a long strip of paper with the months on it.
+Scrolling it means moving the strip so that new months become visible in
+the window.
+@table @kbd
+@item C-x <
+Scroll calendar one month forward (@code{scroll-calendar-left}).
+@item C-x >
+Scroll calendar one month backward (@code{scroll-calendar-right}).
+@item C-v
+Scroll calendar three months forward
+(@code{scroll-calendar-left-three-months}).
+@item M-v
+Scroll calendar three months backward
+(@code{scroll-calendar-right-three-months}).
+@end table
+@kindex C-x < (Calendar mode)
+@findex scroll-calendar-left
+@kindex C-x > (Calendar mode)
+@findex scroll-calendar-right
+The most basic calendar scroll commands scroll by one month at a
+time.  This means that there are two months of overlap between the
+display before the command and the display after.  @kbd{C-x <} scrolls
+the calendar contents one month to the left; that is, it moves the
+display forward in time.  @kbd{C-x >} scrolls the contents to the
+right, which moves backwards in time.
+@kindex C-v (Calendar mode)
+@findex scroll-calendar-left-three-months
+@kindex M-v (Calendar mode)
+@findex scroll-calendar-right-three-months
+The commands @kbd{C-v} and @kbd{M-v} scroll the calendar by an entire
+``screenful''---three months---in analogy with the usual meaning of these
+commands.  @kbd{C-v} makes later dates visible and @kbd{M-v} makes earlier
+dates visible.  These commands also take a numeric argument as a repeat
+count; in particular, since @kbd{C-u} (@code{universal-argument}) multiplies
+the next command by four, typing @kbd{C-u C-v} scrolls the calendar forward by
+a year and typing @kbd{C-u M-v} scrolls the calendar backward by a year.
+Any of the special Calendar mode commands scrolls the calendar automatically
+as necessary to ensure that the date you have moved to is visible.
+@node Mark and Region, General Calendar, Scroll Calendar, Calendar/Diary
+@subsection The Mark and the Region
+The concept of the mark applies to the calendar just as to any other
+buffer, but it marks a @emph{date}, not a @emph{position} in the buffer.
+The region consists of the days between the mark and point (including
+the starting and stopping dates).
+@table @kbd
+@item C-SPC
+Set the mark to today's date (@code{calendar-set-mark}).
+@item C-@@
+The same.
+@item C-x C-x
+Interchange mark and point (@code{calendar-exchange-point-and-mark}).
+@item M-=
+Display the number of days in the current region
+(@code{calendar-count-days-region}).
+@end table
+@kindex C-@@ (Calendar mode)
+@kindex C-SPC (Calendar mode)
+@findex calendar-set-mark
+@kindex C-x C-x (Calendar mode)
+@findex calendar-exchange-point-and-mark
+You set the mark in the calendar, as in any other buffer, by using @kbd{C-@@}
+or @kbd{C-SPC} (@code{calendar-set-mark}).  You return to the marked date
+with the command @kbd{C-x C-x} (@code{calendar-exchange-point-and-mark})
+which puts the mark where point was and point where mark was.  The calendar
+is scrolled as necessary, if the marked date was not visible on the
+screen.  This does not change the extent of the region.
+@kindex M-= (Calendar mode)
+@findex calendar-count-days-region
+To determine the number of days in the region, type @kbd{M-=}
+(@code{calendar-count-days-region}).  The numbers of days printed is
+@emph{inclusive}, that is, includes the days specified by mark and point.
+@cindex mark ring
+The main use of the mark in the calendar is to remember dates that you may
+want to go back to.  To make this feature more useful, the mark ring
+(@pxref{Mark Ring}) operates exactly as in other buffers:  Emacs remembers
+16 previous locations of the mark.  To return to a marked date, type @kbd{C-u
+C-SPC} (or @kbd{C-u C-@@}); this is the command @code{calendar-set-mark} given
+a numeric argument.  It moves point to where the mark was, restores the mark
+from the ring of former marks, and stores the previous point at the end of
+the mark ring.  So, repeated use of this command moves point through all
+the old marks on the ring, one by one.
+@node General Calendar, Holidays, Mark and Region, Calendar/Diary
+@subsection Miscellaneous Calendar Commands
+@table @kbd
+@item p d
+Display day-in-year (@code{calendar-print-day-of-year}).
+@item ?
+Briefly describe calendar commands (@code{describe-calendar-mode}).
+@item SPC
+Scroll the next window (@code{scroll-other-window}).
+@item C-c C-l
+Regenerate the calendar window (@code{redraw-calendar}).
+@item q
+Exit from calendar (@code{exit-calendar}).
+@end table
+@kindex p d (Calendar mode)
+@cindex day of year
+@findex calendar-print-day-of-year
+If you want to know how many days have elapsed since the start of
+the year, or the number of days remaining in the year, type the @kbd{p d}
+command (@code{calendar-print-day-of-year}).  This displays both
+of those numbers in the echo area.
+@kindex ? (Calendar mode)
+@findex describe-calendar-mode
+To display a brief description of the calendar commands, type @kbd{?}
+(@code{describe-calendar-mode}).  For a fuller description, type @kbd{C-h m}.
+@kindex SPC (Calendar mode)
+@findex scroll-other-window
+You can use @kbd{SPC} (@code{scroll-other-window}) to scroll the other
+window.  This is handy when you display a list of holidays or diary entries
+in another window.
+@kindex C-c C-l (Calendar mode)
+@findex redraw-calendar
+If the calendar window gets corrupted, type @kbd{C-c C-l}
+(@code{redraw-calendar}) to redraw it.
+@kindex q (Calendar mode)
+@findex exit-calendar
+To exit from the calendar, type @kbd{q} (@code{exit-calendar}).  This
+buries all buffers related to the calendar and returns the window display
+to what it was when you entered the calendar.
+@node Holidays, Sunrise/Sunset, General Calendar, Calendar/Diary
+@subsection Holidays
+@cindex holidays
+The Emacs calendar knows about all major and many minor holidays.
+@table @kbd
+@item h
+Display holidays for the date indicated by point
+(@code{calendar-cursor-holidays}).
+@item x
+Mark holidays in the calendar window (@code{mark-calendar-holidays}).
+@item u
+Unmark calendar window (@code{calendar-unmark}).
+@item a
+List all holidays for the displayed three months in another window
+(@code{list-calendar-holidays}).
+@item M-x holidays
+List all holidays for three months around today's date in another
+window.
+@end table
+@kindex h (Calendar mode)
+@findex calendar-cursor-holidays
+To see if any holidays fall on a given date, position point on that
+date in the calendar window and use the @kbd{h} command.  The holidays
+are usually listed in the echo area, but if there are too many to fit in
+one line, then they are displayed in a separate window.
+@kindex x (Calendar mode)
+@findex mark-calendar-holidays
+@kindex u (Calendar mode)
+@findex calendar-unmark
+To find the distribution of holidays for a wider period, you can use the
+@kbd{x} command.  This places a @samp{*} next to every date on which a holiday
+falls.  The command applies both to the currently visible dates and to new
+dates that become visible by scrolling.  To turn marking off and erase the
+current marks, type @kbd{u}, which also erases any diary marks (@pxref{Diary}).
+@kindex a (Calendar mode)
+@findex list-calendar-holidays
+To get even more detailed information, use the @kbd{a} command, which
+displays a separate buffer containing a list of all holidays in the
+current three-month range.
+@findex holidays
+You can display the list of holidays for the current month and the
+preceding and succeeding months even if you don't have a calendar
+window.  Use the command @kbd{M-x holidays}.  If you want the list of
+holidays centered around a different month, use @kbd{C-u M-x holidays}
+and type the month and year.
+The holidays known to Emacs include American holidays and the major
+Christian, Jewish, and Islamic holidays; when floating point is available,
+Emacs also knows about solstices and equinoxes.  The dates used by Emacs
+for holidays are based on @emph{current practice}, not historical fact.
+Historically, for instance, the start of daylight savings time and even
+its existence have varied from year to year.  However present American
+law mandates that daylight savings time begins on the first Sunday in
+April; this is the definition that Emacs uses, even though it is wrong
+for some prior years.
+@node Sunrise/Sunset, Lunar Phases, Holidays, Calendar/Diary
+@subsection Times of Sunrise and Sunset
+@cindex sunrise
+@cindex sunset
+Emacs can tell you, to within a minute or two, the times of sunrise and
+sunset for any date, if floating point is available.
+@table @kbd
+@item S
+Display times of sunrise and sunset for the date indicated by point
+(@code{calendar-sunrise-sunset}).
+@item M-x sunrise-sunset
+Display times of sunrise and sunset for today's date.
+@end table
+@kindex S (Calendar mode)
+@findex calendar-sunrise-sunset
+@findex sunrise-sunset
+Move point to the date you want, and type @kbd{S}, to display the
+@emph{local times} of sunrise and sunset in the echo area.
+You can display the times of sunrise and sunset for the current date
+even if you don't have a calendar window.  Use the command @kbd{M-x
+sunrise-sunset}.  If you want the times of sunrise and sunset for a
+different date, use @kbd{C-u M-x sunrise-sunset} and type the year,
+month, and day.
+Because the times of sunrise and sunset depend on the location on
+earth, you need to tell Emacs your latitude, longitude, and location
+name.  Here is an example of what to set:
+@vindex calendar-location-name
+@vindex calendar-longitude
+@vindex calendar-latitude
+@example
+(setq calendar-latitude 40.1)
+(setq calendar-longitude -88.2)
+(setq calendar-location-name "Urbana, IL")
+@end example
+@noindent
+Use one decimal place in the values of @code{calendar-latitude} and
+@code{calendar-longitude}.
+Your time zone also affects the local time of sunrise and sunset.
+Emacs usually gets this information from the operating system, but if
+these values are not what you want (or if the operating system does not
+supply them), you'll need to set them yourself, like this:
+@vindex calendar-time-zone
+@vindex calendar-standard-time-zone-name
+@vindex calendar-daylight-time-zone-name
+@example
+(setq calendar-time-zone -360)
+(setq calendar-standard-time-zone-name "CST")
+(setq calendar-daylight-time-zone-name "CDT")
+@end example
+@noindent
+The value of @code{calendar-time-zone} is the number of minutes
+difference between your local standard time and Universal Time
+(Greenwich time).  The values of @code{calendar-standard-time-zone-name}
+and @code{calendar-daylight-time-zone-name} are the abbreviations used
+in your time zone.
+Emacs displays the times of sunrise and sunset @emph{corrected for
+daylight savings time} (this convenience is unusual; most tables of
+sunrise and sunset use standard time).  The default rule for the
+starting and stopping dates of daylight savings time is the American
+rule.  @xref{Daylight Savings}
+You can display the times of sunrise and sunset for any location and
+any date with @kbd{C-u C-u M-x sunrise-sunset}.  Emacs asks you for a
+longitude, latitude, number of minutes difference from Universal time,
+and date, and then tells you the times of sunrise and sunset for that
+location on that date.  The times are usually given in the echo area,
+but if the message is too long fit in one line, they are displayed in a
+separate window.
+@node Lunar Phases, Other Calendars, Sunrise/Sunset, Calendar/Diary
+@subsection Phases of the Moon
+@cindex phases of the moon
+@cindex moon, phases of
+Emacs can tell you the dates and times of the phases of the moon (new
+moon, first quarter, full moon, last quarter), if floating point is available.
+@table @kbd
+@item M
+List, in another window, the dates and times for all the quarters of the
+moon for the three-month period shown in the calendar window
+(@code{calendar-phases-of-moon}).
+@item M-x phases-of-moon
+List dates and times of the quarters of the moon for three months around
+today's date in another window.
+@end table
+@kindex M (Calendar mode)
+@findex calendar-phases-of-moon
+Use the @kbd{M} command to display a separate buffer of the phases of
+the moon for the current three-month range.  The dates and times listed
+are accurate to within a few minutes.
+@findex phases-of-moon
+You can display the list of the phases of the moon for the current
+month and the preceding and succeeding months even if you don't have a
+calendar window.  Use the command @kbd{M-x phases-of-moon}.  If you want
+the phases of the moon centered around a different month, use @kbd{C-u
+M-x phases-of-moon} and type the month and year.
+@vindex calendar-time-zone
+The dates and times given for the phases of the moon are given in
+local time (corrected for daylight savings, when appropriate); but if
+the variable @code{calendar-time-zone} is void, Universal Time (the
+Greenwich time zone) is used.  @xref{Daylight Savings}
+@node Other Calendars, Diary, Lunar Phases, Calendar/Diary
+@subsection Our Calendar and Other Calendars
+@cindex Gregorian calendar
+The Emacs calendar displayed is @emph{always} the Gregorian calendar,
+sometimes called the ``new style'' calendar, which is used in most of
+the world today.  However, this calendar did not exist before the
+sixteenth century and was not widely used before the eighteenth century;
+it did not fully displace the Julian calendar and gain universal
+acceptance until the early twentieth century.  This poses a problem for
+the Emacs calendar: you can ask for the calendar of any month starting
+with January, year 1 of the current era, but the calendar displayed is
+the Gregorian, even for a date at which the Gregorian calendar did not
+exist!
+Emacs knows about several different calendars, though, not just the
+Gregorian calendar.  The following commands describe the date indicated
+by point in various calendar notations:
+@table @kbd
+@item p c
+Display ISO commercial calendar equivalent for selected day
+(@code{calendar-print-iso-date}).
+@item p j
+Display Julian date for selected day (@code{calendar-print-julian-date}).
+@item p a
+Display astronomical (Julian) day number for selected day
+(@code{calendar-print-astro-day-number}).
+@item p h
+Display Hebrew date for selected day (@code{calendar-print-hebrew-date}).
+@item p i
+Display Islamic date for selected day (@code{calendar-print-islamic-date}).
+@item p f
+Display French Revolutionary date for selected day
+(@code{calendar-print-french-date}).
+@item p m
+Display Mayan date for selected day (@code{calendar-print-mayan-date}).
+@end table
+If you are interested in these calendars, you can convert dates one at a
+time.  Put point on the desired date of the Gregorian calendar and press the
+appropriate keys.  The @kbd{p} is a mnemonic for ``print'' since Emacs
+``prints' the equivalent date in the echo area.
+@kindex p c (Calendar mode)
+@findex calendar-print-iso-date
+@cindex ISO commercial calendar
+The ISO commercial calendar is used largely in Europe.
+@kindex p j (Calendar mode)
+@findex calendar-print-julian-date
+@cindex Julian calendar
+The Julian calendar, named after Julius Caesar, was the one used in Europe
+throughout medieval times, and in many countries up until the nineteenth
+century.
+@kindex p a (Calendar mode)
+@findex calendar-print-astro-day-number
+@cindex Julian day numbers
+@cindex astronomical day numbers
+Astronomers use a simple counting of days elapsed since noon, Monday,
+January 1, 4713 B.C. on the Julian calendar.  The number of days elapsed
+is called the @emph{Julian day number} or the @emph{Astronomical day number}.
+@kindex p h (Calendar mode)
+@findex calendar-print-hebrew-date
+@cindex Hebrew calendar
+The Hebrew calendar is the one used to determine the dates of Jewish
+holidays.  Hebrew calendar dates begin and end at sunset.
+@kindex p i (Calendar mode)
+@findex calendar-print-islamic-date
+@cindex Islamic calendar
+The Islamic (Moslem) calendar is the one used to determine the dates
+of Moslem holidays.  There is no universal agreement in the Islamic
+world about the calendar; Emacs uses a widely accepted version, but the
+precise dates of Islamic holidays often depend on proclamation by
+religious authorities, not on calculations.  As a consequence, the
+actual dates of occurrence can vary slightly from the dates computed by
+Emacs.  Islamic calendar dates begin and end at sunset.
+@kindex p f (Calendar mode)
+@findex calendar-print-french-date
+@cindex French Revolutionary calendar
+The French Revolutionary calendar was created by the Jacobins after the 1789
+revolution, to represent a more secular and nature-based view of the annual
+cycle, and to install a 10-day week in a rationalization measure similar to
+the metric system.  The French government officially abandoned this
+calendar at the end of 1805.
+@kindex p m (Calendar mode)
+@findex calendar-print-mayan-date
+@cindex Mayan calendar
+The Maya of Central America used three separate, overlapping calendar
+systems, the @emph{long count}, the @emph{tzolkin}, and the @emph{haab}.
+Emacs knows about all three of these calendars.  Experts dispute the
+exact correlation between the Mayan calendar and our calendar; Emacs uses the
+Goodman-Martinez-Thompson correlation in its calculations.
+You can move to dates that you specify on the Commercial, Julian,
+astronomical, Hebrew, Islamic, or French calendars:
+@kindex g c (Calendar mode)
+@findex calendar-goto-iso-date
+@kindex g j (Calendar mode)
+@findex calendar-goto-julian-date
+@kindex g a (Calendar mode)
+@findex calendar-goto-astro-day-number
+@kindex g h (Calendar mode)
+@findex calendar-goto-hebrew-date
+@kindex g i (Calendar mode)
+@findex calendar-goto-islamic-date
+@kindex g f (Calendar mode)
+@findex calendar-goto-french-date
+@table @kbd
+@item g c
+Move point to a date specified by the ISO commercial calendar
+(@code{calendar-goto-iso-date}).
+@item g j
+Move point to a date specified by the Julian calendar
+(@code{calendar-goto-julian-date}).
+@item g a
+Move point to a date specified by astronomical (Julian) day number
+(@code{calendar-goto-astro-day-number}).
+@item g h
+Move point to a date specified by the Hebrew calendar
+(@code{calendar-goto-hebrew-date}).
+@item g i
+Move point to a date specified by the Islamic calendar
+(@code{calendar-goto-islamic-date}).
+@item g f
+Move point to a date specified by the French Revolutionary calendar
+(@code{calendar-goto-french-date}).
+@end table
+These commands ask you for a date on the other calendar, move point to
+the Gregorian calendar date equivalent to that date, and display the
+other calendar's date in the echo area.  Emacs uses strict completion
+(@pxref{Completion}) whenever it asks you to type a month name, so you
+don't have to worry about the spelling of Hebrew, Islamic, or French names.
+@findex list-yahrzeit-dates
+@cindex yahrzeits
+One common question concerning the Hebrew calendar is the computation
+of the anniversary of a date of death, called a ``yahrzeit.''  The Emacs
+calendar includes a facility for such calculations.  If you are in the
+calendar, the command @kbd{M-x list-yahrzeit-dates} asks you for a
+range of years and then displays a list of the yahrzeit dates for those
+years for the date given by point.  If you are not in the calendar,
+this command first asks you for the date of death and the range of
+years, and then displays the list of yahrzeit dates.
+Emacs also has many commands for movement on the Mayan calendars.
+@table @kbd
+@item g m l
+Move point to a date specified by the Mayan long count calendar
+(@code{calendar-goto-mayan-long-count-date}).
+@item g m p t
+Move point to the previous occurrence of a date specified by the Mayan
+tzolkin calendar (@code{calendar-previous-tzolkin-date}).
+@item g m n t
+Move point to the next occurrence of a date specified by the Mayan
+tzolkin calendar (@code{calendar-next-tzolkin-date}).
+@item g m p h
+Move point to the previous occurrence of a date specified by the Mayan
+haab calendar (@code{calendar-previous-haab-date}).
+@item g m n h
+Move point to the next occurrence of a date specified by the Mayan
+haab calendar (@code{calendar-next-haab-date}).
+@item g m p c
+Move point to the previous occurrence of a date specified by the Mayan
+calendar round (@code{calendar-previous-calendar-round-date}).
+@item g m n c
+Move point to the next occurrence of a date specified by the Mayan
+calendar round (@code{calendar-next-calendar-round-date}).
+@end table
+@cindex Mayan long count
+To understand these commands, you need to understand the Mayan calendars.
+The long count is a counting of days with units
+@table @asis
+@item 1 kin
+= 1  day
+@item 1 uinal
+= 20 kin
+@item 1 tun
+= 18 uinal
+@item 1 katun
+= 20 tun
+@item 1 baktun
+= 20 katun
+@end table
+@kindex g m l (Calendar mode)
+@findex calendar-goto-mayan-long-count-date
+@noindent
+Thus, the long count date 12.16.11.16.6 means 12 baktun, 16 katun, 11
+tun, 16 uinal, and 6 kin.  The Emacs calendar can handle Mayan long
+count dates as early as 7.17.18.13.1, but no earlier.  When you use the
+@kbd{g m l} command, type the Mayan long count date with the baktun,
+katun, tun, uinal, and kin separated by periods.
+@kindex g m p t (Calendar mode)
+@findex calendar-previous-tzolkin-date
+@kindex g m n t (Calendar mode)
+@findex calendar-next-tzolkin-date
+@cindex Mayan tzolkin calendar
+The Mayan tzolkin calendar is a cycle of 260 days formed by a pair of
+independent cycles of 13 and 20 days.  Like the haab cycle, this cycle
+repeats endlessly, and you can go backward and forward to the previous
+or next (respectively) point in the cycle.  When you type @kbd{g m p t},
+Emacs asks you for a tzolkin date and moves point to the
+previous occurrence of that date; type @kbd{g m n t} to go to the next
+occurrence.
+@kindex g m p h (Calendar mode)
+@findex calendar-previous-haab-date
+@kindex g m n h (Calendar mode)
+@findex calendar-next-haab-date
+@cindex Mayan haab calendar
+The Mayan haab calendar is a cycle of 365 days arranged as 18 months
+of 20 days each, followed a 5-day monthless period.  Since this cycle
+repeats endlessly, Emacs lets you go backward and forward to the
+previous or next (respectively) point in the cycle.  Type @kbd{g m p h}
+to go to the previous haab date; Emacs asks you for a haab date and
+moves point to the previous occurrence of that date.  Similarly,
+type @kbd{g m n h} to go to the next haab date.
+@kindex g m p c (Calendar mode)
+@findex calendar-previous-calendar-round-date
+@kindex g m n c (Calendar mode)
+@findex calendar-next-calendar-round-date
+@cindex Mayan calendar round
+The Maya also used the combination of the tzolkin date and the haab
+date.  This combination is a cycle of about 52 years called a
+@emph{calendar round}.  If you type @kbd{g m p c}, Emacs asks you for
+both a haab and a tzolkin date and then moves point to the previous
+occurrence of that combination.  Use @kbd{g m p c} to move point to the
+next occurrence.  Emacs signals an error if the haab/tzolkin date you
+have typed cannot occur.
+Emacs uses strict completion (@pxref{Completion}) whenever it asks you
+to type a Mayan name, so you don't have to worry about spelling.
+@node Diary, Calendar Customization, Other Calendars, Calendar/Diary
+@subsection The Diary
+@cindex diary
+Associated with the Emacs calendar is a diary that keeps track of
+appointments or other events on a daily basis.  To use the diary
+feature, you must first create a @dfn{diary file} containing a list of
+events and their dates.  Then Emacs can automatically pick out and
+display the events for today, for the immediate future, or for any
+specified date.@refill
+By default, Emacs expects your diary file to be named @file{~/diary}.
+It uses the same format as the @code{calendar} utility.  A sample
+@file{~/diary} file is:
+@example
+12/22/1988 Twentieth wedding anniversary!!
+&1/1. Happy New Year!
+10/22 Ruth's birthday.
+* 21, *: Payday
+Tuesday--weekly meeting with grad students at 10am
+Supowit, Shen, Bitner, and Kapoor to attend.
+1/13/89 Friday the thirteenth!!
+&thu 4pm squash game with Lloyd.
+mar 16 Dad's birthday
+April 15, 1989 Income tax due.
+&* 15 time cards due.
+@end example
+Although you probably will start by creating a diary manually, Emacs
+provides a number of commands to let you view, add, and change diary
+entries.  You can also share diary entries with other users
+(@pxref{Included Diary Files}).
+@menu
+* Diary Commands::         Viewing diary entries and associated calendar dates.
+* Format of Diary File::   Entering events in your diary.
+* Special Diary Entries::  Anniversaries, blocks of dates, cyclic entries, etc.
+@end menu
+@node Diary Commands, Format of Diary File, Diary, Diary
+@subsection Commands Displaying Diary Entries
+Once you have created a @file{~/diary} file, you can view it within
+Calendar mode.  You can also view today's events independently of
+Calendar mode.
+@table @kbd
+@item d
+Display any diary entries for the selected date
+(@code{view-diary-entries}).
+@item s
+Display entire diary file (@code{show-all-diary-entries}).
+@item m
+Mark all visible dates that have diary entries
+(@code{mark-diary-entries}).
+@item u
+Unmark calendar window (@code{calendar-unmark}).
+@item M-x print-diary-entries
+Print a hard copy of the diary display as it appears.
+@item M-x diary
+Display any diary entries for today's date.
+@end table
+@kindex d (Calendar mode)
+@findex view-diary-entries
+Displaying the diary entries with @kbd{d} shows in a separate window the
+diary entries for the date indicated by point in the calendar window.  The
+mode line of the new window shows the date of the diary entries and any
+holidays that fall on that date.
+If you specify a numeric argument with @kbd{d}, then all the diary
+entries for that many successive days are shown.  Thus, @kbd{2 d}
+displays all the entries for the selected date and for the following
+day.
+@kindex m (Calendar mode)
+@findex mark-diary-entries
+@kindex u (Calendar mode)
+@findex calendar-unmark
+To get a broader overview of which days are mentioned in the diary, use
+the @kbd{m} command to mark those days in the calendar window.  The marks
+appear next to the dates to which they apply.  The @kbd{m} command affects
+the dates currently visible and, if you scroll the calendar, newly visible
+dates as well.  The @kbd{u} command deletes all diary marks (and all
+holiday marks too; @pxref{Holidays}), not only in the dates currently
+visible, but dates that become visible when you scroll the calendar.
+@kindex s (Calendar mode)
+@findex show-all-diary-entries
+For more detailed information, use the @kbd{s} command, which displays
+the entire diary file.
+Display of selected diary entries uses the selective display feature,
+the same feature that Outline mode uses to show part of an outline
+(@pxref{Outline Mode}).  This involves hiding the diary entries that are
+not relevant, by changing the preceding newline into an ASCII control-m
+(code 015).  The hidden lines are part of the buffer's text, but they
+are invisible; they don't appear on the screen.  When you save the diary
+file, the control-m characters are saved as newlines; thus, the
+invisible lines become ordinary lines in the file.
+@findex print-diary-entries
+Because the diary buffer as you see it is an illusion, simply printing
+the contents does not print what you see on your screen.  So there is a
+special command to print a hard copy of the buffer @emph{as it appears};
+this command is @kbd{M-x print-diary-entries}.  It sends the data
+directly to the printer.  You can customize it like @code{lpr-region}
+(@pxref{Hardcopy}).
+@findex diary
+The command @kbd{M-x diary} displays the diary entries for the current
+date, independently of the calendar display, and optionally for the next
+few days as well; the variable @code{number-of-diary-entries} specifies
+how many days to include (@pxref{Customization}).
+If you put in your @file{.emacs} file:
+@example
+(diary)
+@end example
+@noindent
+it automatically displays a window with the day's diary entries, when
+you enter Emacs.  The mode line of the displayed window shows the date
+and any holidays that fall on that date.
+@node Format of Diary File, Special Diary Entries, Diary Commands, Diary
+@subsection The Diary File
+@cindex diary file
+@vindex diary-file
+Your @dfn{diary file} is a file that records events associated with
+particular dates.  The name of the diary file is specified by the variable
+@code{diary-file}; @file{~/diary} is the default.  You can use the same file
+for the @code{calendar} utility program, since its formats are a subset of the
+ones allowed by the Emacs Calendar.
+Each entry in the file describes one event and consists of one or more
+lines.  It always begins with a date specification at the left margin.
+The rest of the entry is simply text to describe the event.  If the
+entry has more than one line, then the lines after the first must begin
+with whitespace to indicate they continue a previous entry.
+Here are some sample diary entries, illustrating different ways of
+formatting a date.  The examples all show dates in American order (month, day,
+year), but Calendar mode offers (day, month, year) ordering too.
+@example
+4/20/93  Switch-over to new tabulation system
+apr. 25  Start tabulating annual results
+4/30  Results for April are due
+*/25  Monthly cycle finishes
+Friday  Don't leave without backing up files
+@end example
+The first entry appears only once, on April 20, 1993.  The second and
+third appear every year on the specified dates, and the fourth uses a
+wildcard (asterisk) for the month, so it appears on the 25th of every
+month.  The final entry appears every week on Friday.
+You can also use just numbers to express a date, as in
+@samp{@var{month}/@var{day}} or
+@samp{@var{month}/@var{day}/@var{year}}.  This must be followed by a
+nondigit.  In the date itself, @var{month} and @var{day} are numbers of
+one or two digits.  @var{year} is a number and may be abbreviated to the
+last two digits; that is, you can use @samp{11/12/1989} or
+@samp{11/12/89}.
+A date may be @dfn{generic}, or partially unspecified.  Then the entry
+applies to all dates that match the specification.  If the date does
+not contain a year, it is generic and applies to any year.
+Alternatively, @var{month}, @var{day}, or @var{year} can be a @samp{*};
+this matches any month, day, or year, respectively.  Thus, a diary entry
+@samp{3/*/*} matches any day in March of any year.@refill
+Dates can also have the form @samp{@var{monthname} @var{day}} or
+@samp{@var{monthname} @var{day}, @var{year}}, where the month's name can
+be spelled in full or abbreviated to three characters (with or without a
+period).  Case is not significant.  If the date does not contain a year,
+it is generic and applies to any year.  Also, @var{monthname},
+@var{day}, or @var{year} can be a @samp{*} which matches any month, day,
+or year, respectively.@refill
+@vindex european-calendar-style
+@findex european-calendar
+If you prefer the European style of writing dates---in which the day
+comes before the month---type @kbd{M-x european-calendar} while in the
+calendar, or set the variable @code{european-calendar-style} to @code{t}
+in your @file{.emacs} file @emph{before} the calendar or diary command.
+This mode interprets all dates in the diary in the European manner, and
+also uses European style for displaying diary dates.  (Note that there
+is no comma after the @var{monthname} in the European style.)@refill
+@findex american-calendar
+To revert to the (default) American style of writing dates, type @kbd{M-x
+american-calendar}.
+You can use the name of a day of the week as a generic date which
+applies to any date falling on that day of the week.  You can abbreviate
+the day of the week to three letters (with or without a period) or spell
+it in full; it need not be capitalized.
+You can inhibit the marking of certain diary entries in the calendar
+window; to do this, insert an ampersand (@samp{&}) at the beginning of
+the entry, before the date.  This has no effect on display of the entry
+in the diary window; it affects only marks on dates in the calendar
+window.  Nonmarking entries are especially useful for generic entries
+that would otherwise mark many different dates.
+Lines that do not begin with valid dates and do not continue a preceding
+entry are ignored.
+If the first line of a diary entry consists only of the date or day
+name with no following blanks or punctuation, then the diary window
+display doesn't include that line; only the continuation lines appear.
+For example:
+@example
+02/11/1989
+Bill B. visits Princeton today
+2pm Cognitive Studies Committee meeting
+2:30-5:30 Liz at Lawrenceville
+4:00pm Dentist appt
+7:30pm Dinner at George's
+8:00-10:00pm concert
+@end example
+@noindent
+appears in the diary window without the date line at the beginning.
+This style of entry looks neater when you display just a single day's
+entries, but can cause confusion if you ask for more than one day's
+entries.
+You can edit the diary entries as they appear in the window, but it is
+important to remember that the buffer displayed contains the @emph{entire}
+diary file, with portions of it concealed from view.  This means, for
+instance, that the @kbd{C-f} (@code{forward-char}) command can put point
+at what appears to be the end of the line, but what is in reality the
+middle of some concealed line.  @emph{Be careful when editing the diary
+entries!}  Inserting additional lines or adding/deleting characters in the
+middle of a visible line cannot cause problems.  Watch out for @kbd{C-e}
+(@code{end-of-line}), however; it may put you at the end of a concealed
+line far from where point appears to be!  Before editing the diary, it
+is best to display the entire file with @kbd{s}
+(@code{show-all-diary-entries}).@refill
+While in the calendar, there are several commands to help you in making
+entries to your diary.
+@table @kbd
+@item i d
+Add a diary entry for the selected date (@code{insert-diary-entry}).
+@item i w
+Add a diary entry for the selected day of the week (@code{insert-weekly-diary-entry}).
+@item i m
+Add a diary entry for the selected day of the month (@code{insert-monthly-diary-entry}).
+@item i y
+Add a diary entry for the selected day of the year (@code{insert-yearly-diary-entry}).
+@end table
+@kindex i d (Calendar mode)
+@findex insert-diary-entry
+You can make a diary entry for a specific date by moving point to that
+date in the calendar window and using the @kbd{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.
+@kindex i w (Calendar mode)
+@findex insert-weekly-diary-entry
+If you want to make a diary entry that applies to a specific day of
+the week, move point to that day of the week (any occurrence will do)
+and use the @kbd{i w} command.  This displays the end of your diary file
+in another window and inserts the day-of-week as a generic date; you can
+then type the rest of the diary entry.
+@kindex i m (Calendar mode)
+@findex insert-monthly-diary-entry
+@kindex i y (Calendar mode)
+@findex insert-yearly-diary-entry
+You make a monthly diary entry in the same fashion.  Move point to the
+day of the month, use the @kbd{i m} command, and type the diary entry.
+Similarly, you make a yearly diary entry with the @kbd{i y} command.
+All of the above commands make marking diary entries.  If you want the diary
+entry to be nonmarking, give a prefix argument to the command.  For example,
+@kbd{C-u i w} makes a nonmarking, weekly diary entry.
+If you modify the diary, be sure to write the file before exiting from the
+calendar.
+@node Special Diary Entries,, Format of Diary File, Diary
+@subsection Special Diary Entries
+In addition to entries based on calendar dates, your diary file can contain
+entries for regularly occurring events such as anniversaries.  These entries
+are based on expressions (sexps) that Emacs evaluates as it scans the diary
+file.  Such an entry is indicated by @samp{%%} at the beginning (preceded by
+@samp{&} for a nonmarking entry), followed by a sexp in parentheses.  Calendar
+mode offers commands to make it easier to put some of these special entries in
+your diary.
+@table @kbd
+@item i a
+Add an anniversary diary entry for the selected date (@code{insert-anniversary-diary-entry}).
+@item i b
+Add a block diary entry for the current region (@code{insert-block-diary-entry}).
+@item i c
+Add a cyclic diary entry starting at the date (@code{insert-cyclic-diary-entry}).
+@end table
+@kindex i a (Calendar mode)
+@findex insert-anniversary-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 @kbd{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.
+@findex diary-anniversary
+The effect of @kbd{i a} is to add a @code{diary-anniversary} sexp to your
+diary file.  You can also add one manually, for instance:
+@example
+%%(diary-anniversary 10 31 1948) Arthur's birthday
+@end example
+@noindent
+This entry applies to October 31 in any year after 1948; @samp{10 31 1948}
+specifies the date.  (If you are using the European calendar style, the month
+and day are interchanged.)  The reason this sexp requires a beginning
+year is that advanced diary functions can use it to calculate the number of
+elapsed years (@pxref{Sexp Diary Entries}).@refill
+@kindex i b (Calendar mode)
+@findex insert-block-diary-entry
+You can make a diary entry entry for a block of dates by setting the mark
+at the date at one end of the block, moving point to the date at the other
+end of the block, and using the @kbd{i b} command.  This command
+causes the end of your diary file to be displayed in another window and the
+block description to be inserted; you can then type the diary entry.
+@findex diary-block
+Here is such a diary entry that applies to all dates from June 24, 1990
+through July 10, 1990:
+@example
+%%(diary-block 6 24 1990 7 10 1990) Vacation
+@end example
+@noindent
+The @samp{6 24 1990} indicates the starting date and the @samp{7 10 1990}
+indicates the stopping date.  (Again, if you are using the European calendar
+style, the month and day are interchanged.)
+@kindex i c (Calendar mode)
+@findex insert-cyclic-diary-entry
+You can specify cyclic diary entries that repeat after a fixed
+interval of days.  Move point to the starting date and use the @kbd{i c}
+command.  After you specify the length of interval, this command
+displays the end of your diary file in another window and inserts the
+cyclic event description; you can then type the rest of the diary
+entry.
+The sexp corresponding to the @kbd{i c} command looks like:
+@findex diary-cyclic
+@example
+%%(diary-cyclic 50 3 1 1990) Renew medication
+@end example
+@noindent
+which applies to March 1, 1990 and every 50th day following; @samp{3 1 1990}
+specifies the starting date.  (If you are using the European calendar style,
+the month and day are interchanged.)
+All three of the these commands make marking diary entries.  If you want the
+diary entry to be nonmarking, give a numeric argument to the command.  For
+example, @kbd{C-u i a} makes a nonmarking anniversary diary
+entry.
+Marking sexp diary entries in the calendar is @emph{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 @samp{&}.
+One sophisticated kind of sexp, a floating diary entry, has no corresponding
+command.  The 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 @code{cron} utility on Unix systems.@refill
+Here is a nonmarking, floating diary entry that applies to the last
+Thursday in November:
+@findex diary-float
+@example
+&%%(diary-float 11 4 -1) American Thanksgiving
+@end example
+@noindent
+The 11 specifies November (the eleventh month), the 4 specifies Thursday
+(the fourth day of the week, where Sunday is numbered zero), and the
+@minus{}1 specifies ``last'' (1 would mean ``first'', 2 would mean
+``second'', @minus{}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 @samp{'(1 2 3)} and have the entry apply to the last
+Thursday of January, February, and March.  If the month is @code{t}, the
+entry applies to all months of the year.@refill
+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 (@pxref{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
+@example
+&%%(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
+@end example
+@noindent
+to just those dates.  This example illustrates how the sexp can depend
+on the variable @code{date}; this variable is a list (@var{month}
+@var{day} @var{year}) that gives the Gregorian date for which the diary
+entries are being found.  If the value of the sexp is @code{t}, the
+entry applies to that date.  If the sexp evaluates to @code{nil}, the
+entry does @emph{not} apply to that date.
+@node Calendar Customization,, Diary, Calendar/Diary
+@subsection 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.
+@end menu
+@node Calendar Customizing
+@subsubsection Customizing the Calendar
+@vindex view-diary-entries-initially
+If you set the variable @code{view-diary-entries-initially} to
+@code{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 @file{.emacs} file:@refill
+@example
+(setq view-diary-entries-initially t)
+(calendar)
+@end example
+@noindent
+they display both the calendar and diary windows whenever you start Emacs.
+@vindex view-calendar-holidays-initially
+Similarly, if you set the variable
+@code{view-calendar-holidays-initially} to @code{t}, entering the
+calendar automatically displays a list of holidays for the current three
+month period.  The holiday list appears in a separate window.@refill
+@vindex mark-diary-entries-in-calendar
+You can set the variable @code{mark-diary-entries-in-calendar} to @code{t}
+in order to place a plus sign (@samp{+}) beside any dates with diary entries.
+Whenever the calendar window is displayed or redisplayed, the diary entries
+are automatically marked for holidays.
+@vindex mark-holidays-in-calendar
+Similarly, setting the variable @code{mark-holidays-in-calendar} to
+@code{t} places an asterisk (@samp{*}) after all holiday dates visible
+in the calendar window.
+@vindex calendar-load-hook
+There are many customizations that you can make with the hooks
+provided.  For example, the variable @code{calendar-load-hook}, whose
+default value is @code{nil}, is a normal hook run when the calendar
+package is first loaded (before actually starting to display the
+calendar).
+@vindex initial-calendar-window-hook
+The variable @code{initial-calendar-window-hook}, whose default value
+is @code{nil}, is a normal hook run the first time the calendar window
+is displayed.  The function is invoked only when you first enter
+Calendar mode, not when you redisplay an existing Calendar window.  But
+if you leave the calendar with the @kbd{q} command and reenter it, the
+hook runs again.@refill
+@vindex today-visible-calendar-hook
+The variable @code{today-visible-calendar-hook}, whose default value
+is @code{nil}, 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;
+a function @code{calendar-star-date} is included for this purpose.  In
+your @file{.emacs} file, put:@refill
+@findex calendar-star-date
+@example
+(setq today-visible-calendar-hook 'calendar-star-date)
+@end example
+@noindent
+Another standard hook function adds asterisks around the current date.
+Here's how to use it:
+@findex calendar-mark-today
+@example
+(setq today-visible-calendar-hook 'calendar-mark-today)
+@end example
+@vindex today-invisible-calendar-hook
+@noindent
+A corresponding variable, @code{today-invisible-calendar-hook}, whose
+default value is @code{nil}, is a normal hook run after the calendar
+buffer text has been prepared, if the current date is @emph{not} visible
+in the window.@refill
+@node Holiday Customizing
+@subsubsection Customizing the Holidays
+@vindex calendar-holidays
+@vindex christian-holidays
+@vindex hebrew-holidays
+@vindex islamic-holidays
+Emacs knows about holidays defined by entries on one of several lists.
+You can customize theses lists of holidays to your own needs, adding
+holidays or deleting lists of holidays.  The lists of holidays that
+Emacs uses are for general holidays (@code{general-holidays}), local
+holidays (@code{local-holidays}), Christian holidays
+(@code{christian-holidays}), Hebrew (Jewish) holidays
+(@code{hebrew-holidays}), Islamic (Moslem) holidays
+(@code{islamic-holidays}), and other holidays (@code{other-holidays}).
+@vindex general-holidays
+The general holidays are, by default, holidays common throughout the
+United States.  To eliminate these holidays, set @code{general-holidays}
+to @code{nil}.
+@vindex local-holidays
+There are no default local holidays (but sites may supply some).  You
+can set the variable @code{local-holidays} to any list of holidays, as
+described below.
+@vindex all-christian-calendar-holidays
+@vindex all-hebrew-calendar-holidays
+@vindex all-islamic-calendar-holidays
+By default, Emacs does not consider all the holidays of these
+religions, only those commonly found in secular calendars.  For a more
+extensive collection of religious holidays, you can set any (or all) of
+the variables @code{all-christian-calendar-holidays},
+@code{all-hebrew-calendar-holidays}, or
+@code{all-islamic-calendar-holidays} to @code{t}.  If you want to
+eliminate the religious holidays, set any or all of the corresponding
+variables @code{christian-holidays}, @code{hebrew-holidays}, and
+@code{islamic-holidays} to @code{nil}.@refill
+@vindex other-holidays
+You can set the variable @code{other-holidays} to any list of
+holidays.  This list, normally empty, is intended for your use.
+@cindex holiday forms
+Each of the lists (@code{general-holidays}, @code{local-holidays},
+@code{christian-holidays}, @code{hebrew-holidays},
+@code{islamic-holidays}, and @code{other-holidays}) is a list of
+@dfn{holiday forms}, each holiday form describing a holiday (or
+sometimes a list of holidays).  Holiday forms may have the following
+formats:
+@table @code
+@item (holiday-fixed @var{month} @var{day} @var{string})
+A fixed date on the Gregorian calendar.  @var{month} and @var{day} are
+numbers, @var{string} is the name of the holiday.
+@item (holiday-float @var{month} @var{dayname} @var{k} @var{string})
+The @var{k}th @var{dayname} in @var{month} on the Gregorian calendar
+(@var{dayname}=0 for Sunday, and so on); negative @var{k} means count back
+from the end of the month.  @var{string} is the name of the holiday.
+@item (holiday-hebrew @var{month} @var{day} @var{string})
+A fixed date on the Hebrew calendar.  @var{month} and @var{day} are
+numbers, @var{string} is the name of the holiday.
+@item (holiday-islamic @var{month} @var{day} @var{string})
+A fixed date on the Islamic calendar.  @var{month} and @var{day} are
+numbers, @var{string} is the name of the holiday.
+@item (holiday-julian @var{month} @var{day} @var{string})
+A fixed date on the Julian calendar.  @var{month} and @var{day} are
+numbers, @var{string} is the name of the holiday.
+@item (holiday-sexp @var{sexp} @var{string})
+@var{sexp} is a Lisp expression that should use the variable @code{year}
+to compute the date of a holiday, or @code{nil} if the holiday doesn't
+happen this year.  The value represents the date as a list of the form
+@code{(@var{month} @var{day} @var{year})}.  @var{string} is the name of
+the holiday.
+@item (if @var{boolean} @var{holiday-form} &optional @var{holiday-form})
+A choice between two holidays based on the value of @var{boolean}.
+@item (@var{function} &optional @var{args})
+Dates requiring special computation; @var{args}, if any, are passed in
+a list to the function @code{calendar-holiday-function-@var{function}}.
+@end table
+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 @file{.emacs} file:
+@smallexample
+(setq other-holidays '((holiday-fixed 7 14 "Bastille Day")))
+@end smallexample
+@noindent
+The holiday form @code{(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:
+@smallexample
+(holiday-float 8 1 4 "Hurricane Supplication Day")
+@end smallexample
+@noindent
+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,
+@minus{}1 the last occurrence, @minus{}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,
+@smallexample
+(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")))
+@end smallexample
+@noindent
+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 the @samp{if} or the
+@samp{sexp} form.  For example, American presidential elections occur on
+the first Tuesday after the first Monday in November of years divisible
+by 4:
+@smallexample
+(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"))
+@end smallexample
+@noindent
+or
+@smallexample
+(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"))
+@end smallexample
+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 of the sun, for example, add @code{(eclipses)} to
+@code{other-holidays} and write an Emacs Lisp function
+@code{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:
+@smallexample
+(((6 27 1991) "Lunar Eclipse") ((7 11 1991) "Solar Eclipse") ... )
+@end smallexample
+@node Date Display Format
+@subsubsection Date Display Format
+@vindex calendar-date-display-form
+You can customize the manner of displaying dates in the diary,
+in mode lines, and in messages by setting
+@code{calendar-date-display-form}.  This variable is a list of
+expressions that can involve the variables @code{month}, @code{day}, and
+@code{year}, all numbers in string form, and @code{monthname} and
+@code{dayname}, both alphabetic strings.  In the American style, the
+default value of this list is as follows:
+@smallexample
+((if dayname (concat dayname ", ")) monthname " " day ", " year)
+@end smallexample
+@noindent
+while in the European style this value is the default:
+@smallexample
+((if dayname (concat dayname ", ")) day " " monthname " " year)
+@end smallexample
+The ISO standard date representation is this:
+@smallexample
+(year "-" month "-" day)
+@end smallexample
+@noindent
+This specifies a typical American format:
+@smallexample
+(month "/" day "/" (substring year -2))
+@end smallexample
+@node Time Display Format
+@subsubsection Time Display Format
+@vindex calendar-time-display-form
+In the calendar, diary, and related buffers, Emacs displays times of
+day in the conventional American style with the hours from 1 through 12,
+minutes, and either @samp{am} or @samp{pm}.  If you prefer the
+``military'' (European) style of writing times---in which the hours go
+from 00 to 23---you can alter the variable
+@code{calendar-time-display-form}.  This variable is a list of
+expressions that can involve the variables @code{12-hours},
+@code{24-hours}, and @code{minutes}, all numbers in string form, and
+@code{am-pm} and @code{time-zone}, both alphabetic strings.  The default
+definition of @code{calendar-time-display-form} is as follows:
+@smallexample
+(12-hours ":" minutes am-pm
+(if time-zone " (") time-zone (if time-zone ")"))
+@end smallexample
+Setting @code{calendar-time-display-form} to
+@smallexample
+(24-hours ":" minutes
+(if time-zone " (") time-zone (if time-zone ")"))
+@end smallexample
+@noindent
+gives military-style times like @samp{21:07 (UT)} if time zone names are
+defined, and times like @samp{21:07} if they are not.
+@node Daylight Savings
+@subsubsection Daylight Savings Time
+@cindex 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 default choice of rules is not
+appropriate for your location, you can tell Emacs the rules to use by
+setting certain variables.
+@vindex calendar-daylight-savings-starts
+@vindex calendar-daylight-savings-ends
+These variables are @code{calendar-daylight-savings-starts} and
+@code{calendar-daylight-savings-ends}.  Their values should be Lisp
+expressions that refer to the variable @code{year}, and evaluate to the
+Gregorian date on which daylight savings time starts or (respectively)
+ends, in the form of a list @code{(@var{month} @var{day} @var{year})}.
+The values should be @code{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:
+@example
+@group
+(calendar-nth-named-day 1 0 4 year)
+(calendar-nth-named-day -1 0 10 year)
+@end group
+@end example
+@noindent
+i.e. the first 0th day (Sunday) of the fourth month (April) in
+the year specified by @code{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
+@code{calendar-daylight-savings-starts} to this:
+@example
+(list 10 1 year)
+@end example
+For a more complex example, suppose daylight savings time begins on
+the first of Nisan on the Hebrew calendar.  You would set
+@code{calendar-daylight-savings-starts} as follows:
+@example
+(calendar-gregorian-from-absolute
+(calendar-absolute-from-hebrew
+(list 1 1 (+ year 3760))))
+@end example
+@noindent
+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 @code{calendar-daylight-savings-starts}
+and @code{calendar-daylight-savings-ends} to @code{nil}.
+@vindex calendar-daylight-time-offset
+This variable specifies the difference between daylight savings time and
+standard time, measured in minutes.  The value for Cambridge is 60.
+@vindex calendar-daylight-savings-starts-time
+@vindex calendar-daylight-savings-ends-time
+These variables specify is the number of minutes after midnight local time
+when the transition to and from daylight savings time should occur.  For
+Cambridge, both variables' values are 120.
+@node Diary Customizing
+@subsubsection Customizing the Diary
+@vindex holidays-in-diary-buffer
+Ordinarily, the mode line of the diary buffer window indicates any
+holidays that fall on the date of the diary entries.  The process of
+checking for holidays can take several seconds, so including holiday
+information delays the display of the diary buffer noticeably.  If you'd
+prefer to have a faster display of the diary buffer but without the
+holiday information, set the variable @code{holidays-in-diary-buffer} to
+@code{nil}.@refill
+@vindex number-of-diary-entries
+The variable @code{number-of-diary-entries} controls the number of
+days of diary entries to be displayed at one time.  It affects the
+initial display when @code{view-diary-entries-initially} is @code{t}, as
+well as the command @kbd{M-x diary}.  For example, the default value is
+1, which says to display only the current day's diary entries.  If the
+value is 2, both the current day's and the next day's entries are
+displayed.  The value can also be a vector of seven elements: if the
+value is @code{[0 2 2 2 2 4 1]} then no diary entries appear on Sunday,
+the current date's and the next day's diary entries appear Monday
+through Thursday, Friday through Monday's entries appear on Friday,
+while on Saturday only that day's entries appear.
+@vindex print-diary-entries-hook
+@findex print-diary-entries
+The variable @code{print-diary-entries-hook} is a normal hook run
+after preparation of a temporary buffer containing just the diary
+entries currently visible in the diary buffer.  (The other, irrelevant
+diary entries are really absent from the temporary buffer; in the diary
+buffer, they are merely hidden.)  The default value of this hook does
+the printing with the command @code{lpr-buffer}.  If you want to use a
+different command to do the printing, just change the value of this
+hook.  Other uses might include, for example, rearranging the lines into
+order by day and time.
+@vindex diary-date-forms
+You can customize the form of dates in your diary file, if neither the
+standard American nor European styles suits your needs, by setting the
+variable @code{diary-date-forms}.  This variable is a list of forms of
+dates recognized in the diary file.  Each form is a list of regular
+expressions (@pxref{Regexps}) and the variables @code{month},
+@code{day}, @code{year}, @code{monthname}, and @code{dayname}.  The
+variable @code{monthname} matches the name of the month, capitalized or
+not, or its three-letter abbreviation, followed by a period or not; it
+matches @samp{*}.  Similarly, @code{dayname} matches the name of the
+day, capitalized or not, or its three-letter abbreviation, followed by a
+period or not.  The variables @code{month}, @code{day}, and @code{year}
+match those numerical values, preceded by arbitrarily many zeros; they
+also match @samp{*}.  The default value of @code{diary-date-forms} in
+the American style is
+@example
+((month "/" day "[^/0-9]")
+(month "/" day "/" year "[^0-9]")
+(monthname " *" day "[^,0-9]")
+(monthname " *" day ", *" year "[^0-9]")
+(dayname "\\W"))
+@end example
+@noindent
+Emacs matches of the diary entries with the date forms is done with the
+standard syntax table from Fundamental mode
+(@pxref{Syntax Tables,,,lispref,XEmacs Lisp Reference Manual}),
+but with the @samp{*} changed so that it is a word constituent.@refill
+The forms on the list must be @emph{mutually exclusive} and must not
+match any portion of the diary entry itself, just the date.  If, to be
+mutually exclusive, the pattern must match a portion of the diary entry
+itself, the first element of the form @emph{must} be @code{backup}.
+This causes the date recognizer to back up to the beginning of the
+current word of the diary entry.  Even if you use @code{backup}, the
+form must absolutely not match more than a portion of the first word of
+the diary entry.  The default value of @code{diary-date-forms} in the
+European style is this list:
+@example
+((day "/" month "[^/0-9]")
+(day "/" month "/" year "[^0-9]")
+(backup day " *" monthname "\\W+\\<[^*0-9]")
+(day " *" monthname " *" year "[^0-9]")
+(dayname "\\W"))
+@end example
+@noindent
+Notice the use of @code{backup} in the middle form because part of the
+diary entry must be matched to distinguish this form from the following one.
+@node Hebrew/Islamic Entries
+@subsubsection Hebrew- and Islamic-Date Diary Entries
+Your diary file can have entries based on Hebrew or Islamic dates, as
+well as entries based on our usual Gregorian calendar.  However, because
+the processing of such entries is time-consuming and most people don't
+need them, you must customize the processing of your diary file to
+specify that you want such entries recognized.  If you want Hebrew-date
+diary entries, for example, you must include these lines in your
+@file{.emacs} file:
+@vindex nongregorian-diary-listing-hook
+@vindex nongregorian-diary-marking-hook
+@findex list-hebrew-diary-entries
+@findex mark-hebrew-diary-entries
+@smallexample
+(setq nongregorian-diary-listing-hook 'list-hebrew-diary-entries)
+(setq nongregorian-diary-marking-hook 'mark-hebrew-diary-entries)
+@end smallexample
+@noindent
+If you want Islamic-date entries, include these lines in your
+@file{.emacs} file:
+@findex list-islamic-diary-entries
+@findex mark-islamic-diary-entries
+@smallexample
+(setq nongregorian-diary-listing-hook 'list-islamic-diary-entries)
+(setq nongregorian-diary-marking-hook 'mark-islamic-diary-entries)
+@end smallexample
+@noindent
+If you want both Hebrew- and Islamic-date entries, include these lines:
+@smallexample
+(setq nongregorian-diary-listing-hook
+'(list-hebrew-diary-entries list-islamic-diary-entries))
+(setq nongregorian-diary-marking-hook
+'(mark-hebrew-diary-entries mark-islamic-diary-entries))
+@end smallexample
+Hebrew- and Islamic-date diary entries have the same formats as
+Gregorian-date diary entries, except that the date must be preceded with
+an @samp{H} for Hebrew dates and an @samp{I} for Islamic dates.
+Moreover, because the Hebrew and Islamic month names are not uniquely
+specified by the first three letters, you may not abbreviate them.  For
+example, a diary entry for the Hebrew date Heshvan 25 could look like
+@smallexample
+HHeshvan 25 Happy Hebrew birthday!
+@end smallexample
+@noindent
+and would appear in the diary for any date that corresponds to Heshvan 25
+on the Hebrew calendar.  Similarly, an Islamic-date diary entry might be
+@smallexample
+IDhu al-Qada 25 Happy Islamic birthday!
+@end smallexample
+@noindent
+and would appear in the diary for any date that corresponds to Dhu al-Qada 25
+on the Islamic calendar.
+As with Gregorian-date diary entries, Hebrew- and Islamic-date entries
+are nonmarking if they are preceded with an ampersand (@samp{&}).
+There are commands to help you in making Hebrew- and Islamic-date
+entries to your diary:
+@table @kbd
+@item i h d
+Add a diary entry for the Hebrew date corresponding to the selected date
+(@code{insert-hebrew-diary-entry}).
+@item i h m
+Add a diary entry for the day of the Hebrew month corresponding to the
+selected date (@code{insert-monthly-hebrew-diary-entry}).
+@item i h y
+Add a diary entry for the day of the Hebrew year corresponding to the
+selected date (@code{insert-yearly-hebrew-diary-entry}).
+@item i i d
+Add a diary entry for the Islamic date corresponding to the selected date
+(@code{insert-islamic-diary-entry}).
+@item i i m
+Add a diary entry for the day of the Islamic month corresponding to the
+selected date (@code{insert-monthly-islamic-diary-entry}).
+@item i i y
+Add a diary entry for the day of the Islamic year corresponding to the
+selected date (@code{insert-yearly-islamic-diary-entry}).
+@end table
+@findex insert-hebrew-diary-entry
+@findex insert-monthly-hebrew-diary-entry
+@findex insert-yearly-hebrew-diary-entry
+@findex insert-islamic-diary-entry
+@findex insert-monthly-islamic-diary-entry
+@findex insert-yearly-islamic-diary-entry
+These commands work exactly like the corresponding commands for ordinary
+diary entries: Move point to a date in the calendar window and the above
+commands insert the Hebrew or Islamic date (corresponding to the date
+indicated by point) at the end of your diary file and you can then type the
+diary entry.  If you want the diary entry to be nonmarking, give a numeric
+argument to the command.
+@node Fancy Diary Display
+@subsubsection Fancy Diary Display
+@vindex diary-display-hook
+@findex simple-diary-display
+Diary display works by preparing the diary buffer and then running the
+hook @code{diary-display-hook}.  The default value of this hook hides
+the irrelevant diary entries and then displays the buffer
+(@code{simple-diary-display}).  However, if you specify the hook as
+follows,
+@cindex diary buffer
+@findex fancy-diary-display
+@example
+(add-hook 'diary-display-hook 'fancy-diary-display)
+@end example
+@noindent
+then fancy mode displays diary entries and holidays by copying them into
+a special buffer that exists only for display.  Copying provides an
+opportunity to change the displayed text to make it prettier---for
+example, to sort the entries by the dates they apply to.
+As with simple diary display, you can print a hard copy of the buffer
+with @code{print-diary-entries}.  To print a hard copy of a day-by-day
+diary for a week by positioning point on Sunday of that week, type
+@kbd{7 d} and then do @kbd{M-x print-diary-entries}.  As usual, the
+inclusion of the holidays slows down the display slightly; you can speed
+things up by setting the variable @code{holidays-in-diary-buffer} to
+@code{nil}.
+@vindex diary-list-include-blanks
+Ordinarily, the fancy diary buffer does not show days for which there are
+no diary entries, even if that day is a holiday.  If you want such days to be
+shown in the fancy diary buffer, set the variable
+@code{diary-list-include-blanks} to @code{t}.@refill
+@cindex sorting diary entries
+If you use the fancy diary display, you can use the normal hook
+@code{list-diary-entries-hook} to sort each day's diary entries by their
+time of day.  Add this line to your @file{.emacs} file:
+@findex sort-diary-entries
+@example
+(add-hook 'list-diary-entries-hook 'sort-diary-entries)
+@end example
+@noindent
+For each day, this sorts diary entries that begin with a recognizable
+time of day according to their times.  Diary entries without times come
+first within each day.
+@node Included Diary Files
+@subsubsection Included Diary Files
+If you use the fancy diary display, you can have diary entries from other
+files included with your own by an ``include'' mechanism.  This facility makes
+possible the sharing of common diary files among groups of users.  Lines in
+the diary file of this form:
+@smallexample
+#include "@var{filename}"
+@end smallexample
+@noindent
+includes the diary entries from the file @var{filename} in the fancy
+diary buffer (because the ordinary diary buffer is just the buffer
+associated with your diary file, you cannot use the include mechanism
+unless you use the fancy diary buffer).  The include mechanism is
+recursive, by the way, so that included files can include other files,
+and so on; you must be careful not to have a cycle of inclusions, of
+course.  To enable the include facility, add lines as follows to your
+@file{.emacs} file:
+@vindex list-diary-entries-hook
+@vindex mark-diary-entries-hook
+@findex include-other-diary-files
+@findex mark-included-diary-files
+@smallexample
+(add-hook 'list-diary-entries-hook 'include-other-diary-files)
+(add-hook 'mark-diary-entries-hook 'mark-included-diary-files)
+@end smallexample
+@node Sexp Diary Entries
+@subsubsection Sexp Entries and the Fancy Diary Display
+@cindex sexp diary entries
+Sexp diary entries allow you to do more than just have complicated
+conditions under which a diary entry applies.  If you use the fancy
+diary display, sexp entries can generate the text of the entry depending
+on the date itself.  For example, an anniversary diary entry can insert
+the number of years since the anniversary date into the text of the
+diary entry.  Thus the @samp{%d} in this dairy entry:
+@findex diary-anniversary
+@smallexample
+%%(diary-anniversary 10 31 1948) Arthur's birthday (%d years old)
+@end smallexample
+@noindent
+gets replaced by the age, so on October 31, 1990 the entry appears in
+the fancy diary buffer like this:
+@smallexample
+Arthur's birthday (42 years old)
+@end smallexample
+@noindent
+If the diary file instead contains this entry:
+@smallexample
+%%(diary-anniversary 10 31 1948) Arthur's %d%s birthday
+@end smallexample
+@noindent
+the entry in the fancy diary buffer for October 31, 1990 appears like this:
+@smallexample
+Arthur's 42nd birthday
+@end smallexample
+Similarly, cyclic diary entries can interpolate the number of repetitions
+that have occurred:
+@findex diary-cyclic
+@smallexample
+%%(diary-cyclic 50 1 1 1990) Renew medication (%d%s time)
+@end smallexample
+@noindent
+looks like this:
+@smallexample
+Renew medication (5th time)
+@end smallexample
+@noindent
+in the fancy diary display on September 8, 1990.
+The generality of sexp diary entries 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
+@smallexample
+&%%(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
+@end smallexample
+@noindent
+applies to just those dates.  This example illustrates how the sexp can
+depend on the variable @code{date}; this variable is a list (@var{month}
+@var{day} @var{year}) that gives the Gregorian date for which the diary
+entries are being found.  If the value of the expression is @code{t},
+the entry applies to that date.  If the expression evaluates to
+@code{nil}, the entry does @emph{not} apply to that date.
+The following sexp diary entries take advantage of the ability (in the fancy
+diary display) to concoct diary entries based on the date:
+@findex diary-sunrise-sunset
+@findex diary-phases-of-moon
+@findex diary-day-of-year
+@findex diary-iso-date
+@findex diary-julian-date
+@findex diary-astro-day-number
+@findex diary-hebrew-date
+@findex diary-islamic-date
+@findex diary-french-date
+@findex diary-mayan-date
+@table @code
+@item %%(diary-sunrise-sunset)
+Make a diary entry for the local times of today's sunrise and sunset.
+@item %%(diary-phases-of-moon)
+Make a diary entry for the phases (quarters) of the moon.
+@item %%(diary-day-of-year)
+Make a diary entry with today's day number in the current year and the number
+of days remaining in the current year.
+@item %%(diary-iso-date)
+Make a diary entry with today's equivalent ISO commercial date.
+@item %%(diary-julian-date)
+Make a diary entry with today's equivalent date on the Julian calendar.
+@item %%(diary-astro-day-number)
+Make a diary entry with today's equivalent astronomical (Julian) day number.
+@item %%(diary-hebrew-date)
+Make a diary entry with today's equivalent date on the Hebrew calendar.
+@item %%(diary-islamic-date)
+Make a diary entry with today's equivalent date on the Islamic calendar.
+@item %%(diary-french-date)
+Make a diary entry with today's equivalent date on the French Revolutionary
+calendar.
+@item %%(diary-mayan-date)
+Make a diary entry with today's equivalent date on the Mayan calendar.
+@end table
+@noindent
+Thus including the diary entry
+@smallexample
+&%%(diary-hebrew-date)
+@end smallexample
+@noindent
+causes every day's diary display to contain the equivalent date on the
+Hebrew calendar, if you are using the fancy diary display.  (With simple
+diary display, the line @samp{&%%(diary-hebrew-date)} appears in the
+diary for any date, but does nothing particularly useful.)
+There are a number of other available sexp diary entries that are important
+to those who follow the Hebrew calendar:
+@cindex rosh hodesh
+@findex diary-rosh-hodesh
+@cindex parasha, weekly
+@findex diary-parasha
+@cindex candle lighting times
+@findex diary-sabbath-candles
+@cindex omer count
+@findex diary-omer
+@cindex yahrzeits
+@findex diary-yahrzeit
+@table @code
+@item %%(diary-rosh-hodesh)
+Make a diary entry that tells the occurrence and ritual announcement of each
+new Hebrew month.
+@item %%(diary-parasha)
+Make a Saturday diary entry that tells the weekly synagogue scripture reading.
+@item %%(diary-sabbath-candles)
+Make a Friday diary entry that tells the @emph{local time} of Sabbath
+candle lighting.
+@item %%(diary-omer)
+Make a diary entry that gives the omer count, when appropriate.
+@item %%(diary-yahrzeit @var{month} @var{day} @var{year}) @var{name}
+Make a diary entry marking the anniversary of a date of death.  The date
+is the @emph{Gregorian} (civil) date of death.  The diary entry appears
+on the proper Hebrew calendar anniversary and on the day before.  (In
+the European style, the order of the parameters is changed to @var{day},
+@var{month}, @var{year}.)
+@end table
+@node Appt Customizing
+@subsubsection Customizing Appointment Reminders
+You can specify exactly how Emacs reminds you of an appointment and
+how far in advance it begins doing so.  Here are the variables that you
+can set:
+@vindex appt-message-warning-time
+@vindex appt-audible
+@vindex appt-visible
+@vindex appt-display-mode-line
+@vindex appt-msg-window
+@vindex appt-display-duration
+@table @code
+@item appt-message-warning-time
+The time in minutes before an appointment that the reminder begins.  The
+default is 10 minutes.
+@item appt-audible
+If this is @code{t} (the default), Emacs rings the terminal bell for
+appointment reminders.
+@item appt-visible
+If this is @code{t} (the default), Emacs displays the appointment
+message in echo area.
+@item appt-display-mode-line
+If this is @code{t} (the default), Emacs displays the number of minutes
+to the appointment on the mode line.
+@item appt-msg-window
+If this is @code{t} (the default), Emacs displays the appointment
+message in another window.
+@item appt-display-duration
+The number of seconds an appointment message is displayed.  The default
+is 5 seconds.
+@end table

Mercurial > hg > xemacs-beta

comparison man/xemacs/calendar.texi @ 0:376386a54a3c r19-14