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

comparison man/xemacs/calendar.texi @ 428:3ecd8885ac67 r21-2-22

Import from CVS: tag r21-2-22

author	cvs
date	Mon, 13 Aug 2007 11:28:15 +0200
parents
children	abe6d1db359e

comparison

equal deleted inserted replaced

-:0a0253eac470
+:3ecd8885ac67
+@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
+planned or past events.  To enter the calendar, type @kbd{M-x calendar};
+this displays a three-month calendar centered on the current month, with
+point on the current date.  With a numeric argument, as in @kbd{C-u M-x
+calendar}, it prompts you for the month and year to be the center of the
+three-month calendar.  The calendar uses its own buffer, whose major
+mode is Calendar mode.
+@kbd{Button2} in the calendar brings up a menu of operations on a
+particular date; @kbd{Buttons3} brings up a menu of commonly used
+calendar features that are independent of any particular date.  To exit
+the calendar, type @kbd{q}.  @xref{Calendar, Customizing the Calendar
+and Diary,, elisp, The Emacs Lisp Reference Manual}, for customization
+information about the calendar and diary.
+@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::       Exiting or recomputing the calendar.
+* LaTeX Calendar::         Print a calendar using LaTeX.
+* 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
+@cindex moving inside the calendar
+Calendar mode lets you move through the calendar in logical units of
+time such as days, weeks, months, and years.  If you move outside the
+three months originally displayed, the calendar display ``scrolls''
+automatically through time to make the selected date visible.  Moving to
+a date lets you view its holidays or diary entries, or convert it to other
+calendars; moving longer time periods is also useful simply to scroll the
+calendar.
+@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-backward-year}).
+@end table
+@kindex C-f @r{(Calendar mode)}
+@findex calendar-forward-day
+@kindex C-b @r{(Calendar mode)}
+@findex calendar-backward-day
+@kindex C-n @r{(Calendar mode)}
+@findex calendar-forward-week
+@kindex C-p @r{(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.
+The arrow keys are equivalent to @kbd{C-f}, @kbd{C-b}, @kbd{C-n} and
+@kbd{C-p}, just as they normally are in other modes.
+@kindex M-@} @r{(Calendar mode)}
+@findex calendar-forward-month
+@kindex M-@{ @r{(Calendar mode)}
+@findex calendar-backward-month
+@kindex C-x ] @r{(Calendar mode)}
+@findex calendar-forward-year
+@kindex C-x [ @r{(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 @w{@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.
+All these commands accept a numeric argument as a repeat count.
+For convenience, the digit keys and the minus sign specify numeric
+arguments in Calendar mode even without the Meta modifier.  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
+weeks (months, years) as starting on particular dates.  So Calendar mode
+provides commands to move to the beginning or end of a week, month or
+year:
+@table @kbd
+@kindex C-a @r{(Calendar mode)}
+@findex calendar-beginning-of-week
+@item C-a
+Move point to start of week (@code{calendar-beginning-of-week}).
+@kindex C-e @r{(Calendar mode)}
+@findex calendar-end-of-week
+@item C-e
+Move point to end of week (@code{calendar-end-of-week}).
+@kindex M-a @r{(Calendar mode)}
+@findex calendar-beginning-of-month
+@item M-a
+Move point to start of month (@code{calendar-beginning-of-month}).
+@kindex M-e @r{(Calendar mode)}
+@findex calendar-end-of-month
+@item M-e
+Move point to end of month (@code{calendar-end-of-month}).
+@kindex M-< @r{(Calendar mode)}
+@findex calendar-beginning-of-year
+@item M-<
+Move point to start of year (@code{calendar-beginning-of-year}).
+@kindex M-> @r{(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.
+@vindex calendar-week-start-day
+@cindex weeks, which day they start on
+@cindex calendar, first day of week
+By default, weeks begin on Sunday.  To make them begin on Monday
+instead, set the variable @code{calendar-week-start-day} to 1.
+@node Specified Dates,,Move to Beginning or End, Calendar Motion
+@subsubsection Particular Dates
+Calendar mode provides commands for moving to a particular date
+specified in various ways.
+@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-goto-today}).
+@end table
+@kindex g d @r{(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 moves 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 @r{(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 . @r{(Calendar mode)}
+@findex calendar-goto-today
+You can return to today's date with @kbd{.}@:
+(@code{calendar-goto-today}).
+@node Scroll Calendar, Mark and Region, Calendar Motion, Calendar/Diary
+@subsection Scrolling the Calendar through Time
+@cindex scrolling in the calendar
+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
+@itemx @key{NEXT}
+Scroll calendar three months forward
+(@code{scroll-calendar-left-three-months}).
+@item M-v
+@itemx @key{PRIOR}
+Scroll calendar three months backward
+(@code{scroll-calendar-right-three-months}).
+@end table
+@kindex C-x < @r{(Calendar mode)}
+@findex scroll-calendar-left
+@kindex C-x > @r{(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 @r{(Calendar mode)}
+@findex scroll-calendar-left-three-months
+@kindex M-v @r{(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 take a numeric argument as a
+repeat count; in particular, since @kbd{C-u} 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.
+The function keys @key{NEXT} and @key{PRIOR} are equivalent to
+@kbd{C-v} and @kbd{M-v}, just as they are in other modes.
+@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-@@ @r{(Calendar mode)}
+@kindex C-SPC @r{(Calendar mode)}
+@findex calendar-set-mark
+@kindex C-x C-x @r{(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-= @r{(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, it 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, LaTeX Calendar, 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 C-c C-l
+Regenerate the calendar window (@code{redraw-calendar}).
+@item SPC
+Scroll the next window (@code{scroll-other-window}).
+@item q
+Exit from calendar (@code{exit-calendar}).
+@end table
+@kindex p d @r{(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 ? @r{(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 @r{(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 @r{(Calendar mode)}
+@findex redraw-calendar
+If the calendar window text gets corrupted, type @kbd{C-c C-l}
+(@code{redraw-calendar}) to redraw it.  (This can only happen if you use
+non-Calendar-mode editing commands.)
+@kindex SPC @r{(Calendar mode)}
+In Calendar mode, 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 q @r{(Calendar mode)}
+@findex exit-calendar
+To exit from the calendar, type @kbd{q} (@code{exit-calendar}).  This
+buries all buffers related to the calendar, selecting other buffers.
+(If a frame contains a dedicated calendar window, exiting from the
+calendar iconifies that frame.)
+@node LaTeX Calendar, Holidays, General Calendar, Calendar/Diary
+@section LaTeX Calendar
+@cindex calendar and La@TeX{}
+The Calendar La@TeX{} commands produce a buffer of La@TeX{} code that
+prints as a calendar.  Depending on the command you use, the printed
+calendar covers the day, week, month or year that point is in.
+@kindex t @r{(Calendar mode)}
+@table @kbd
+@item t m
+Generate a one-month calendar (@code{cal-tex-cursor-month}).
+@item t M
+Generate a sideways-printing one-month calendar
+(@code{cal-tex-cursor-month-landscape}).
+@item t d
+Generate a one-day calendar
+(@code{cal-tex-cursor-day}).
+@item t w 1
+Generate a one-page calendar for one week
+(@code{cal-tex-cursor-week}).
+@item t w 2
+Generate a two-page calendar for one week
+(@code{cal-tex-cursor-week2}).
+@item t w 3
+Generate an ISO-style calendar for one week
+(@code{cal-tex-cursor-week-iso}).
+@item t w 4
+Generate a calendar for one Monday-starting week
+(@code{cal-tex-cursor-week-monday}).
+@item t f w
+Generate a Filofax-style two-weeks-at-a-glance calendar
+(@code{cal-tex-cursor-filofax-2week}).
+@item t f W
+Generate a Filofax-style one-week-at-a-glance calendar
+(@code{cal-tex-cursor-filofax-week}).
+@item t y
+Generate a calendar for one year
+(@code{cal-tex-cursor-year}).
+@item t Y
+Generate a sideways-printing calendar for one year
+(@code{cal-tex-cursor-year-landscape}).
+@item t f y
+Generate a Filofax-style calendar for one year
+(@code{cal-tex-cursor-filofax-year}).
+@end table
+Some of these commands print the calendar sideways (in ``landscape
+mode''), so it can be wider than it is long.  Some of them use Filofax
+paper size (3.75in x 6.75in).  All of these commands accept a prefix
+argument which specifies how many days, weeks, months or years to print
+(starting always with the selected one).
+If the variable @code{cal-tex-holidays} is non-@code{nil} (the
+default), then the printed calendars show the holidays in
+@code{calendar-holidays}.  If the variable @code{cal-tex-diary} is
+non-@code{nil} (the default is @code{nil}), diary entries are included
+also (in weekly and monthly calendars only).
+@node Holidays, Sunrise/Sunset, LaTeX Calendar, Calendar/Diary
+@subsection Holidays
+@cindex holidays
+The Emacs calendar knows about all major and many minor holidays,
+and can display them.
+@table @kbd
+@item h
+Display holidays for the selected date
+(@code{calendar-cursor-holidays}).
+@item Button2 Holidays
+Display any holidays for the date you click on.
+@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.
+@item M-x list-holidays
+List holidays in another window for a specified range of years.
+@end table
+@kindex h @r{(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.  Alternatively,
+click on that date with @kbd{Button2} and then choose @kbd{Holidays}
+from the menu that appears.  Either way, this displays the holidays for
+that date, in the echo area if they fit there, otherwise in a separate
+window.
+@kindex x @r{(Calendar mode)}
+@findex mark-calendar-holidays
+@kindex u @r{(Calendar mode)}
+@findex calendar-unmark
+To view the distribution of holidays for all the dates shown in the
+calendar, use the @kbd{x} command.  This displays the dates that are
+holidays in a different face (or places a @samp{*} after these dates, if
+display with multiple faces is not available). The command applies both
+to the currently visible months and to other months that subsequently
+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 @r{(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.  You can use @key{SPC} in the calendar window
+to scroll that list.
+@findex holidays
+The command @kbd{M-x holidays} displays the list of holidays for the
+current month and the preceding and succeeding months; this works even
+if you don't have a calendar window.  If you want the list of holidays
+centered around a different month, use @kbd{C-u M-x holidays}, which
+prompts for the month and year.
+The holidays known to Emacs include United States holidays and the
+major Christian, Jewish, and Islamic holidays; also the solstices and
+equinoxes.
+@findex list-holidays
+The command @kbd{M-x list-holidays} displays the list of holidays for
+a range of years.  This function asks you for the starting and stopping
+years, and allows you to choose all the holidays or one of several
+categories of holidays.  You can use this command even if you don't have
+a calendar window.
+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, but present United States law mandates that daylight savings time
+begins on the first Sunday in April.  When the daylight savings rules
+are set up for the United States, Emacs always uses the present
+definition, 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 and sunset
+Special calendar commands can tell you, to within a minute or two, the
+times of sunrise and sunset for any date.
+@table @kbd
+@item S
+Display times of sunrise and sunset for the selected date
+(@code{calendar-sunrise-sunset}).
+@item Button2 Sunrise/Sunset
+Display times of sunrise and sunset for the date you click on.
+@item M-x sunrise-sunset
+Display times of sunrise and sunset for today's date.
+@item C-u M-x sunrise-sunset
+Display times of sunrise and sunset for a specified date.
+@end table
+@kindex S @r{(Calendar mode)}
+@findex calendar-sunrise-sunset
+@findex sunrise-sunset
+Within the calendar, to display the @emph{local times} of sunrise and
+sunset in the echo area, move point to the date you want, and type
+@kbd{S}.  Alternatively, click @kbd{Button2} on the date, then choose
+@kbd{Sunrise/Sunset} from the menu that appears.  The command @kbd{M-x
+sunrise-sunset} is available outside the calendar to display this
+information for today's date or a specified date.  To specify a date
+other than today, use @kbd{C-u M-x sunrise-sunset}, which prompts for
+the year, month, and day.
+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}.  This asks you for a
+longitude, latitude, number of minutes difference from Coordinated
+Universal Time, and date, and then tells you the times of sunrise and
+sunset for that location on that date.
+Because the times of sunrise and sunset depend on the location on
+earth, you need to tell Emacs your latitude, longitude, and location
+name before using these commands.  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 time zone information from the operating system, but
+if these values are not what you want (or if the operating system does
+not supply them), you must set them yourself.  Here is an example:
+@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 Coordinated 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}.  @xref{Daylight Savings},
+for how daylight savings time is determined.
+As a user, you might find it convenient to set the calendar location
+variables for your usual physical location in your @file{.emacs} file.
+And when you install Emacs on a machine, you can create a
+@file{default.el} file which sets them properly for the typical location
+of most users of that machine.  @xref{Init File}.
+@node Lunar Phases, Other Calendars, Sunrise/Sunset, Calendar/Diary
+@subsection Phases of the Moon
+@cindex phases of the moon
+@cindex moon, phases of
+These calendar commands display the dates and times of the phases of
+the moon (new moon, first quarter, full moon, last quarter).  This
+feature is useful for debugging problems that ``depend on the phase of
+the moon.''
+@table @kbd
+@item M
+Display the dates and times for all the quarters of the moon for the
+three-month period shown (@code{calendar-phases-of-moon}).
+@item M-x phases-of-moon
+Display dates and times of the quarters of the moon for three months around
+today's date.
+@end table
+@kindex M @r{(Calendar mode)}
+@findex calendar-phases-of-moon
+Within the calendar, 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
+Outside the calendar, use the command @kbd{M-x phases-of-moon} to
+display the list of the phases of the moon for the current month and the
+preceding and succeeding months.  For information about a different
+month, use @kbd{C-u M-x phases-of-moon}, which prompts for the month and
+year.
+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, Coordinated Universal
+Time (the Greenwich time zone) is used.  @xref{Daylight Savings}.
+@node Other Calendars, Calendar Systems, Lunar Phases, Calendar/Diary
+@subsection  Conversion To and From 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.  The Emacs calendar can
+display any month since 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.
+While Emacs cannot display other calendars, it can convert dates to
+and from several other calendars.
+@menu
+* Calendar Systems::      The calendars Emacs understands
+(aside from Gregorian).
+* To Other Calendar::     Converting the selected date to various calendars.
+* From Other Calendar::   Moving to a date specified in another calendar.
+* Mayan Calendar::        Moving to a date specified in a Mayan calendar.
+@end menu
+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.
+@node Calendar Systems, To Other Calendar, Other Calendars, Other Calendars
+@section Supported Calendar Systems
+@cindex ISO commercial calendar
+The ISO commercial calendar is used largely in Europe.
+@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.
+@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}.
+@cindex Hebrew calendar
+The Hebrew calendar is used by tradition in the Jewish religion.  The
+Emacs calendar program uses the Hebrew calendar to determine the dates
+of Jewish holidays.  Hebrew calendar dates begin and end at sunset.
+@cindex Islamic calendar
+The Islamic calendar is used in many predominantly Islamic countries.
+Emacs uses it to determine the dates of Islamic 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 observance can vary
+slightly from the dates computed by Emacs.  Islamic calendar dates begin
+and end at sunset.
+@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.
+@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.
+@cindex Coptic calendar
+@cindex Ethiopic calendar
+The Copts use a calendar based on the ancient Egyptian solar calendar.
+Their calendar consists of twelve 30-day months followed by an extra
+five-day period.  Once every fourth year they add a leap day to this
+extra period to make it six days.  The Ethiopic calendar is identical in
+structure, but has different year numbers and month names.
+@cindex Persian calendar
+The Persians use a solar calendar based on a design of Omar Khayyam.
+Their calendar consists of twelve months of which the first six have 31
+days, the next five have 30 days, and the last has 29 in ordinary years
+and 30 in leap years.  Leap years occur in a complicated pattern every
+four or five years.
+@cindex Chinese calendar
+The Chinese calendar is a complicated system of lunar months arranged
+into solar years.  The years go in cycles of sixty, each year containing
+either twelve months in an ordinary year or thirteen months in a leap
+year; each month has either 29 or 30 days.  Years, ordinary months, and
+days are named by combining one of ten ``celestial stems'' with one of
+twelve ``terrestrial branches'' for a total of sixty names that are
+repeated in a cycle of sixty.
+@node To Other Calendar, From Other Calendar, Calendar Systems, Other Calendars
+@section Converting To Other Calendars
+The following commands describe the selected date (the date at point)
+in various other calendar systems:
+@table @kbd
+@item Button2  Other Calendars
+Display the date that you click on, expressed in various other calendars.
+@kindex p @r{(Calendar mode)}
+@findex calendar-print-iso-date
+@item p c
+Display ISO commercial calendar equivalent for selected day
+(@code{calendar-print-iso-date}).
+@findex calendar-print-julian-date
+@item p j
+Display Julian date for selected day (@code{calendar-print-julian-date}).
+@findex calendar-print-astro-day-number
+@item p a
+Display astronomical (Julian) day number for selected day
+(@code{calendar-print-astro-day-number}).
+@findex calendar-print-hebrew-date
+@item p h
+Display Hebrew date for selected day (@code{calendar-print-hebrew-date}).
+@findex calendar-print-islamic-date
+@item p i
+Display Islamic date for selected day (@code{calendar-print-islamic-date}).
+@findex calendar-print-french-date
+@item p f
+Display French Revolutionary date for selected day
+(@code{calendar-print-french-date}).
+@findex calendar-print-chinese-date
+@item p C
+Display Chinese date for selected day
+(@code{calendar-print-chinese-date}).
+@findex calendar-print-coptic-date
+@item p k
+Display Coptic date for selected day
+(@code{calendar-print-coptic-date}).
+@findex calendar-print-ethiopic-date
+@item p e
+Display Ethiopic date for selected day
+(@code{calendar-print-ethiopic-date}).
+@findex calendar-print-persian-date
+@item p p
+Display Persian date for selected day
+(@code{calendar-print-persian-date}).
+@findex calendar-print-mayan-date
+@item p m
+Display Mayan date for selected day (@code{calendar-print-mayan-date}).
+@end table
+If you are using X, the easiest way to translate a date into other
+calendars is to click on it with @kbd{Button2}, then choose @kbd{Other
+Calendars} from the menu that appears.  This displays the equivalent
+forms of the date in all the calendars Emacs understands, in the form of
+a menu.  (Choosing an alternative from this menu doesn't actually do
+anything---the menu is used only for display.)
+Put point on the desired date of the Gregorian calendar, then type the
+appropriate keys.  The @kbd{p} is a mnemonic for ``print'' since Emacs
+``prints'' the equivalent date in the echo area.
+@node From Other Calendar, Mayan Calendar, To Other Calendar, Other Calendars
+@section Converting From Other Calendars
+You can use the other supported calendars to specify a date to move
+to.  This section describes the commands for doing this using calendars
+other than Mayan; for the Mayan calendar, see the following section.
+@kindex g @var{char} @r{(Calendar mode)}
+@findex calendar-goto-iso-date
+@findex calendar-goto-julian-date
+@findex calendar-goto-astro-day-number
+@findex calendar-goto-hebrew-date
+@findex calendar-goto-islamic-date
+@findex calendar-goto-french-date
+@findex calendar-goto-chinese-date
+@findex calendar-goto-persian-date
+@findex calendar-goto-coptic-date
+@findex calendar-goto-ethiopic-date
+@table @kbd
+@item g c
+Move to a date specified in the ISO commercial calendar
+(@code{calendar-goto-iso-date}).
+@item g j
+Move to a date specified in the Julian calendar
+(@code{calendar-goto-julian-date}).
+@item g a
+Move to a date specified in astronomical (Julian) day number
+(@code{calendar-goto-astro-day-number}).
+@item g h
+Move to a date specified in the Hebrew calendar
+(@code{calendar-goto-hebrew-date}).
+@item g i
+Move to a date specified in the Islamic calendar
+(@code{calendar-goto-islamic-date}).
+@item g f
+Move to a date specified in the French Revolutionary calendar
+(@code{calendar-goto-french-date}).
+@item g C
+Move to a date specified in the Chinese calendar
+(@code{calendar-goto-chinese-date}).
+@item g p
+Move to a date specified in the Persian calendar
+(@code{calendar-goto-persian-date}).
+@item g k
+Move to a date specified in the Coptic calendar
+(@code{calendar-goto-coptic-date}).
+@item g e
+Move to a date specified in the Ethiopic calendar
+(@code{calendar-goto-ethiopic-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.
+@node Mayan Calendar, Diary ,From Other Calendar ,Other Calendars
+@subsection Converting from the Mayan Calendar
+Here are the commands to select dates based on the Mayan calendar:
+@table @kbd
+@item g m l
+Move to a date specified by the long count calendar
+(@code{calendar-goto-mayan-long-count-date}).
+@item g m n t
+Move to the next occurrence of a place in the
+tzolkin calendar (@code{calendar-next-tzolkin-date}).
+@item g m p t
+Move to the previous occurrence of a place in the
+tzolkin calendar (@code{calendar-previous-tzolkin-date}).
+@item g m n h
+Move to the next occurrence of a place in the
+haab calendar (@code{calendar-next-haab-date}).
+@item g m p h
+Move to the previous occurrence of a place in the
+haab calendar (@code{calendar-previous-haab-date}).
+@item g m n c
+Move to the next occurrence of a place in the
+calendar round (@code{calendar-next-calendar-round-date}).
+@item g m p c
+Move to the previous occurrence of a place in the
+calendar round (@code{calendar-previous-calendar-round-date}).
+@end table
+@cindex Mayan long count
+To understand these commands, you need to understand the Mayan calendars.
+The @dfn{long count} is a counting of days with these units:
+@display
+1 kin = 1 day@ @ @ 1 uinal = 20 kin@ @ @ 1 tun = 18 uinal
+1 katun = 20 tun@ @ @ 1 baktun = 20 katun
+@end display
+@kindex g m l @r{(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.
+@findex calendar-previous-tzolkin-date
+@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.  Since this cycle repeats
+endlessly, Emacs provides commands to move backward and forward to the
+previous or next point in the cycle.  Type @kbd{g m p t} to go to the
+previous tzolkin date; Emacs asks you for a tzolkin date and moves point
+to the previous occurrence of that date.  Similarly, type @kbd{g m n t}
+to go to the next occurrence of a tzolkin date.
+@findex calendar-previous-haab-date
+@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.  Like the tzolkin
+cycle, this cycle repeats endlessly, and there are commands to move
+backward and forward to the previous or next 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 occurrence of a haab
+date.
+@c This is omitted because it is too long for smallbook format.
+@c @findex calendar-previous-calendar-round-date
+@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 n c} to move point to the
+next occurrence of a combination.  These commands signal an error if the
+haab/tzolkin date combination you have typed is impossible.
+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, Mayan Calendar, Calendar/Diary
+@subsection The Diary
+@cindex diary
+The Emacs diary keeps track of appointments or other events on a daily
+basis, in conjunction with the calendar.  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.
+By default, Emacs uses @file{~/diary} as the diary file.  This is the
+same file that the @code{calendar} utility uses.  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
+@noindent
+This example uses extra spaces to align the event descriptions of most
+of the entries.  Such formatting is purely a matter of taste.
+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.
+* Date Formats::           Various ways you can specify dates.
+* Adding to Diary::        Commands to create diary entries.
+* 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 use the calendar
+to view it.  You can also view today's events outside of Calendar mode.
+@table @kbd
+@item d
+Display all diary entries for the selected date
+(@code{view-diary-entries}).
+@item Button2 Diary
+Display all diary entries for the date you click on.
+@item s
+Display the 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 the calendar window (@code{calendar-unmark}).
+@item M-x print-diary-entries
+Print hard copy of the diary display as it appears.
+@item M-x diary
+Display all diary entries for today's date.
+@item M-x diary-mail-entries
+Mail yourself email reminders about upcoming diary entries.
+@end table
+@kindex d @r{(Calendar mode)}
+@findex view-diary-entries
+Displaying the diary entries with @kbd{d} shows in a separate window
+the diary entries for the selected date in the calendar.  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},
+it shows all the diary entries for that many successive days.  Thus,
+@kbd{2 d} displays all the entries for the selected date and for the
+following day.
+Another way to display the diary entries for a date is to click
+@kbd{Button2} on the date, and then choose @kbd{Diary} from the menu
+that appears.
+@kindex m @r{(Calendar mode)}
+@findex mark-diary-entries
+@kindex u @r{(Calendar mode)}
+@findex calendar-unmark
+To get a broader view of which days are mentioned in the diary, use
+the @kbd{m} command.  This displays the dates that have diary entries
+in a different face (or places a @samp{+} after these dates, if
+display with multiple faces is not available).  The command applies both
+to the currently visible months and to other months that subsequently
+become visible by scrolling.  To turn marking off and erase the current
+marks, type @kbd{u}, which also turns off holiday marks
+(@pxref{Holidays}).
+@kindex s @r{(Calendar mode)}
+@findex show-all-diary-entries
+To see the full diary file, rather than just some of the entries, use
+the @kbd{s} command.
+Display of selected diary entries uses the selective display feature
+to hide entries that don't apply.
+@findex print-diary-entries
+The diary buffer as you see it is an illusion, so simply printing the
+buffer does not print what you see on your screen.  There is a special
+command to print hard copy of the diary 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 @code{(diary)} in your @file{.emacs} file, this
+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.
+@findex diary-mail-entries
+@vindex diary-mail-days
+Many users like to receive notice of events in their diary as email.
+To send such mail to yourself, use the command @kbd{M-x
+diary-mail-entries}.  A prefix argument specifies how many days
+(starting with today) to check; otherwise, the variable
+@code{diary-mail-days} says how many days.
+@node Format of Diary File, Date Formats, 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.  The
+@code{calendar} utility program supports a subset of the format allowed
+by the Emacs diary facilities, so you can use that utility to view the
+diary file, with reasonable results aside from the entries it cannot
+understand.
+Each entry in the diary file describes one event and consists of one
+or more lines.  An entry 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.  Lines that do not begin with valid dates and do not continue a
+preceding entry are ignored.
+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.
+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, this entry:
+@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, but editing at the end of a line may
+not do what you expect.  Deleting a line may delete other invisible
+entries that follow it.  Before editing the diary, it is best to display
+the entire file with @kbd{s} (@code{show-all-diary-entries}).
+@node Date Formats,Adding to Diary ,Format of Diary File, Diary
+@subsection Date Formats
+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 supports European order (day,
+month, year) as an option.
+@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 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.  The optional @var{year}
+is also 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}.
+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.
+A date may be @dfn{generic}; that is, 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; so does @samp{march
+*}.
+@vindex european-calendar-style
+@findex european-calendar
+@findex american-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}
+@emph{before} using any 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.)  To go back 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; case is not significant.
+@node Adding to Diary, Special Diary Entries, Date Formats, Diary
+@subsection Commands to Add to the Diary
+While in the calendar, there are several commands to create diary
+entries:
+@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 @r{(Calendar mode)}
+@findex insert-diary-entry
+You can make a diary entry for a specific date by selecting that date
+in the calendar window and typing 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 @r{(Calendar mode)}
+@findex insert-weekly-diary-entry
+@kindex i m @r{(Calendar mode)}
+@findex insert-monthly-diary-entry
+@kindex i y @r{(Calendar mode)}
+@findex insert-yearly-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
+@kbd{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 @kbd{i m}
+command, and type rest of the entry.  Similarly, you can insert a yearly
+diary entry with the @kbd{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, @kbd{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.
+@node Special Diary Entries,, Adding to Diary, Diary
+@subsection Special Diary Entries
+In addition to entries based on calendar dates, the diary file can
+contain @dfn{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
+@samp{%%} 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:
+@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 @r{(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. The entry looks like this:
+@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 expression
+requires a beginning year is that advanced diary functions can use it to
+calculate the number of elapsed years.
+A @dfn{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:
+@findex diary-block
+@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 b @r{(Calendar mode)}
+@findex insert-block-diary-entry
+To insert a block entry, place point and the mark on the two
+dates that begin and end the range, and type @kbd{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.
+@kindex i c @r{(Calendar mode)}
+@findex insert-cyclic-diary-entry
+@dfn{Cyclic} diary entries repeat after a fixed interval of days.  To
+create one, select the starting date and use the @kbd{i c} command.  The
+command prompts for the length of interval, then inserts the entry,
+which looks like this:
+@findex diary-cyclic
+@example
+%%(diary-cyclic 50 3 1 1990) Renew medication
+@end example
+@noindent
+This entry 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 these commands make marking diary entries.  To insert a
+nonmarking entry, 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{&}) when possible.
+Another sophisticated kind of sexp entry, a @dfn{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.  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
+this displays 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.
+@vindex mark-diary-entries-in-calendar
+You can set the variable @code{mark-diary-entries-in-calendar} to
+@code{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 (@pxref{Faces}),
+if the display supports that, or by placing a plus sign (@samp{+})
+beside the date otherwise.
+@vindex mark-holidays-in-calendar
+Similarly, setting the variable @code{mark-holidays-in-calendar} to
+@code{t} marks holiday dates, either with a change of face or with an
+asterisk (@samp{*}).
+@vindex calendar-holiday-marker
+@vindex diary-entry-marker
+The variable @code{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 @code{diary-entry-marker} specifies how to mark a date that has
+diary entries.  The calendar creates faces named @code{holiday-face} and
+@code{diary-face} for these purposes; those symbols are the default
+values of these variables, when Emacs supports multiple faces on your
+terminal.
+@vindex calendar-load-hook
+The variable @code{calendar-load-hook} is a normal hook run when the
+calendar package is first loaded (before actually starting to display
+the calendar).
+@vindex initial-calendar-window-hook
+Starting the calendar runs the normal hook
+@code{initial-calendar-window-hook}.  Recomputation of the calendar
+display does not run this hook.  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} 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
+@code{calendar-star-date}.
+@findex calendar-star-date
+@example
+(add-hook 'today-visible-calendar-hook 'calendar-star-date)
+@end example
+@noindent
+Another standard hook function marks the current date, either by
+changing its face or by adding an asterisk.  Here's how to use it:
+@findex calendar-mark-today
+@example
+(add-hook 'today-visible-calendar-hook 'calendar-mark-today)
+@end example
+@noindent
+@vindex calendar-today-marker
+The variable @code{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
+@code{calendar-today-face} is provided for this purpose; that symbol is
+the default for this variable when Emacs supports multiple faces on your
+terminal.
+@vindex today-invisible-calendar-hook
+@noindent
+A similar normal hook, @code{today-invisible-calendar-hook} is run if
+the current date is @emph{not} visible in the window.
+@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 these lists of holidays to your own needs, adding or
+deleting 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 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 @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 individual 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).
+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 @var{string} is always the
+name of the holiday, as a string.
+@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})
+A date calculated by the Lisp expression @var{sexp}.  The expression
+should use the variable @code{year} to compute and return the date of a
+holiday, or @code{nil} if the holiday doesn't happen this year.  The
+value of @var{sexp} must represent 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{condition} @var{holiday-form} &optional @var{holiday-form})
+A holiday that happens only if @var{condition} is true.
+@item (@var{function} @r{[}@var{args}@r{]})
+A list of dates calculated by the function @var{function}, called with
+arguments @var{args}.
+@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 Emacs Lisp's @code{if} or the
+@code{holiday-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,
+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 holds a list of expressions that can involve the variables
+@code{month}, @code{day}, and @code{year}, which are all numbers in
+string form, and @code{monthname} and @code{dayname}, which are 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
++@noindent
+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
+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 @samp{am} or @samp{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 @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}, which are all
+numbers in string form, and @code{am-pm} and @code{time-zone}, which are
+both alphabetic strings.  The default value 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
+@noindent
+Here is a value that provides European style times:
+@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 resulting rules are not what you want,
+you can tell Emacs the rules to use by setting certain variables.
+@vindex calendar-daylight-savings-starts
+@vindex calendar-daylight-savings-ends
+If the default choice of rules is not appropriate for your location,
+you can tell Emacs the rules to use by setting the variables
+@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
+That is, 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 should set
+@code{calendar-daylight-savings-starts} to this value:
+@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
+The variable @code{calendar-daylight-time-offset} specifies the
+difference between daylight savings time and standard time, measured in
+minutes.  The value for Cambridge, Massachusetts is 60.
+@c @vindex calendar-daylight-savings-starts-time  too long!
+@vindex calendar-daylight-savings-ends-time
+The two variables @code{calendar-daylight-savings-starts-time} and
+@code{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.
+@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: for
+example, 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 patterns
+for recognizing a date.  Each date pattern is a list whose elements may
+be regular expressions (@pxref{Regexps}) or the symbols
+@code{month}, @code{day}, @code{year}, @code{monthname}, and
+@code{dayname}.  All these elements serve as patterns that match certain
+kinds of text in the diary file.  In order for the date pattern, as a
+whole, to match, all of its elements must match consecutively.
+A regular expression in a date pattern matches in its usual fashion,
+using the standard syntax table altered so that @samp{*} is a word
+constituent.
+The symbols @code{month}, @code{day}, @code{year}, @code{monthname},
+and @code{dayname} match the month number, day number, year number,
+month name, and day name of the date being considered.  The symbols that
+match numbers allow leading zeros; those that match names allow
+three-letter abbreviations and capitalization.  All the symbols can
+match @samp{*}; since @samp{*} in a diary entry means ``any day'', ``any
+month'', and so on, it should match regardless of the date being
+considered.
+The default value of @code{diary-date-forms} in the American style is
+this:
+@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 date patterns in the list must be @emph{mutually exclusive} and
+must not match any portion of the diary entry itself, just the date and
+one character of whitespace.  If, to be mutually exclusive, the pattern
+must match a portion of the diary entry text---beyond the whitespace
+that ends the date---then the first element of the date pattern
+@emph{must} be @code{backup}.  This causes the date recognizer to back
+up to the beginning of the current word of the diary entry, after
+finishing the match.  Even if you use @code{backup}, the date pattern
+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 third pattern, because it needs
+to match part of a word beyond the date itself to distinguish it from
+the fourth pattern.
+@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 the world-standard Gregorian calendar.
+However, because recognition of such entries is time-consuming and most
+people don't use them, you must explicitly enable their use.  If you
+want the diary to recognize Hebrew-date diary entries, for example,
+you must do this:
+@vindex nongregorian-diary-listing-hook
+@vindex nongregorian-diary-marking-hook
+@findex list-hebrew-diary-entries
+@findex mark-hebrew-diary-entries
+@smallexample
+(add-hook 'nongregorian-diary-listing-hook 'list-hebrew-diary-entries)
+(add-hook 'nongregorian-diary-marking-hook 'mark-hebrew-diary-entries)
+@end smallexample
+@noindent
+If you want Islamic-date entries, do this:
+@findex list-islamic-diary-entries
+@findex mark-islamic-diary-entries
+@smallexample
+(add-hook 'nongregorian-diary-listing-hook 'list-islamic-diary-entries)
+(add-hook 'nongregorian-diary-marking-hook 'mark-islamic-diary-entries)
+@end smallexample
+Hebrew- and Islamic-date diary entries have the same formats as
+Gregorian-date diary entries, except that @samp{H} precedes a Hebrew
+date and @samp{I} precedes an Islamic date.  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 this:
+@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.  And here is  Islamic-date diary entry  that matches
+Dhu al-Qada 25:
+@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{&}).
+Here is a table of commands used in the calendar to create diary entries
+that match the selected date and other dates that are similar in the Hebrew
+or Islamic calendar:
+@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}).  This diary
+entry matches any date that has the same Hebrew day-within-month as the
+selected date.
+@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}).  This diary
+entry matches any date which has the same Hebrew month and day-within-month
+as the selected date.
+@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 much like the corresponding commands for ordinary
+diary entries: they apply to the date that point is on in the calendar
+window, and what they do is insert just the date portion of a diary entry
+at the end of your diary file.  You must then insert the rest of the
+diary entry.
+@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
+(@code{simple-diary-display}) hides the irrelevant diary entries and
+then displays the buffer.  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
+this enables fancy diary display.  It displays diary entries and
+holidays by copying them into a special buffer that exists only for the
+sake of display.  Copying to a separate buffer 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 t)
+@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
+Fancy diary display also has the ability to process included diary
+files.  This permits a group of people to share a diary file for events
+that apply to all of them.  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.  The include mechanism is recursive, so that included files
+can include other files, and so on; you must be careful not to have a
+cycle of inclusions, of course.  Here is how to enable the include
+facility:
+@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
+The include mechanism works only with the fancy diary display, because
+ordinary diary display shows the entries directly from your diary file.
+@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.  A sexp diary entry contains an
+expression that computes whether the entry applies to any given date.
+If its value is non-@code{nil}, the entry applies to that date;
+otherwise, it does not.  The expression can use the variable  @code{date}
+to find the date being considered; its value is a list (@var{month}
+@var{day} @var{year}) that refers to the Gregorian calendar.
+Suppose you get paid on the 21st of the month if it is a weekday, and
+on the Friday before if the 21st is on a weekend.  Here is how to write
+a sexp diary entry that matches those dates:
+@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 whose text varies 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.)
+These functions can be used to construct sexp diary entries based on
+the Hebrew calendar in certain standard ways:
+@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, by setting these variables:
+@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 @ 428:3ecd8885ac67 r21-2-22