\input texinfo                  @c -*-texinfo-*-
@comment %**start of header (This is for running Texinfo on a region.)
@setfilename calendar-info
@comment %**end of header (This is for running Texinfo on a region.)


@node Calendar
@section Calendar Mode and the Diary
@cindex calendar
@findex calendar

  Emacs provides all the usual functions of a calendar, with a diary of
past or planned events.  To see a three-month calendar centered around
the current month, use the command @kbd{M-x calendar}.  Emacs will
display a window with the calendar, point will indicate the current
date, and you will be in Calendar mode.

@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.
* Misc Calendar::         Moving to today's date, to a specified date.
* Holidays::              Displaying dates of holidays.
* Other Calendars::       Converting dates to other calendar systems.
* Diary::                 Displaying events from your diary.
* Diary File::            Entering events in your diary.
* Special Diary Entries:: Anniversaries, blocks of dates, cyclic entries, etc.
* Customization:: Altering the behavior of the features above.
@end menu

@node Calendar Motion, Scroll Calendar, Calendar, Calendar
@subsection Movement in the Calendar

  You can move through the calendar from the current date to other
dates.  If you move outside the three months originally displayed,
the calendar display scrolls automatically through time.

@menu
* Calendar Unit Motion::       Moving by days, weeks, months, and years.
* Beg or End Calendar Motion:: Moving to beg/end of weeks, months, and years.
* Moving to Arbitrary Dates::  Moving to a specific date.
@end menu

@node Calendar Unit Motion, Beg or End Calendar Motion, Calendar Motion, Calendar Motion
@subsubsection Motion by Integral Days, Weeks, Months, Years

  The commands for movement in the calendar buffer parallel the
commands for movement in text.  You can move forward and backward by
days, weeks, months, and years.

@table @kbd
@item C-f
Move point one day forward (@code{calendar-forward-day}).
@item C-b
Move point one day backward (@code{calendar-backward-day}).
@item C-n
Move point one week forward (@code{calendar-forward-week}).
@item C-p
Move point one week backward (@code{calendar-backward-week}).
@item M-]
Move point one month forward (@code{calendar-forward-month}).
@item M-[
Move point one month backward (@code{calendar-backward-month}).
@item C-x ]
Move point one year forward (@code{calendar-forward-year}).
@item C-x [
Move point one year backward (@code{calendar-forward-year}).
@end table

@kindex C-f (Calendar mode)
@findex calendar-forward-day
@kindex C-b (Calendar mode)
@findex calendar-backward-day
@kindex C-n (Calendar mode)
@findex calendar-forward-week
@kindex C-p (Calendar mode)
@findex calendar-backward-week
  The day and week commands are natural analogues of the usual Emacs
commands for moving by characters and by lines.  Just as @kbd{C-n}
usually moves to the same column in the following line, in Calendar
mode it moves to the same day in the following week.  And @kbd{C-p}
moves to the same day in the previous week.

@kindex M-] (Calendar mode)
@findex calendar-forward-month
@kindex M-[ (Calendar mode)
@findex calendar-backward-month
@kindex C-x ] (Calendar mode)
@findex calendar-forward-year
@kindex C-x [ (Calendar mode)
@findex calendar-forward-year
  The commands for motion by months and years work like those for
weeks, but move a larger distance.  The month commands @kbd{M-]} and
@kbd{M-[} move forward or backward by an entire month's time.  The
year commands @kbd{C-x ]} and @kbd{C-x [} move forward or backward a
whole year.

  The easiest way to remember these commands is to consider months and
years analogous to paragraphs and pages of text, respectively.  But the
commands themselves are not quite analogous.  The ordinary Emacs paragraph
commands move to the beginning or end of a paragraph, whereas these month
and year commands move by an entire month or an entire year, which usually
involves skipping across the end of a month or year.

  Each of these commands accepts a numeric argument as repeat counts.
For convenience, the digit keys and the minus sign are bound in
Calendar mode so that it is unnecessary to type the @kbd{M-} prefix.
For example, @kbd{100 C-f} will move point 100 days forward from its
present location.

@node Beg or End Calendar Motion,, Calendar Unit Motion, Calendar Motion
@subsubsection Beginning or End of Week, Month or Year

  A week (or month, or year) is not just a quantity of days; we think
of new weeks (months, years) as starting on particular days.  So
Calendar mode provides commands to move to the beginning or end of the
week, month or year:

@table @kbd
@kindex C-a (Calendar mode)
@findex calendar-beginning-of-week
@item C-a
Move point to beginning of week (@code{calendar-beginning-of-week}).
@kindex C-e (Calendar mode)
@findex calendar-end-of-week
@item C-e
Move point to end of week (@code{calendar-end-of-week}).
@kindex M-a (Calendar mode)
@findex calendar-beginning-of-month
@item M-a
Move point to beginning of month (@code{calendar-beginning-of-month}).
@kindex M-e (Calendar mode)
@findex calendar-end-of-month
@item M-e
Move point to end of month (@code{calendar-end-of-month}).
@kindex M-< (Calendar mode)
@findex calendar-beginning-of-year
@item M-<
Move point to beginning of year (@code{calendar-beginning-of-year}).
@kindex M-> (Calendar mode)
@findex calendar-end-of-year
@item M->
Move point to end of year (@code{calendar-end-of-year}).
@end table

  These commands also take numeric arguments as repeat counts, with the
repeat count indicating how many weeks, months, or years to move backward
or forward.

@node Moving to Arbitrary Dates,,Beg or End Calendar Motion, Calendar Motion
@subsubsection Arbitrary Dates

  You can move to any arbitrary date:

@table @kbd
@item g d
Move point to specified date (@code{calendar-goto-date}).
@end table

@kindex g d (Calendar mode)
@findex calendar-goto-date
  This command prompts for a year, a month, and a day of the month an goes
to that date.  Because the calendar includes all dates from the beginning of
the present era, you must enter the year in its entirety; that is, type
@samp{1990}, not @samp{90}.

@node Scroll Calendar, Misc Calendar, Calendar Motion, Calendar
@subsection Scrolling the Calendar through Time

  The calendar display scrolls automatically through time when you move out
of the visible portion.  You can also scroll it manually.  Imagine that the
calendar window contains a long strip of paper with the months on it.
Scrolling it means moving the strip so that new months become visible in
the window.

@table @kbd
@item C-x <
Scroll calendar display one month forward
(@code{scroll-calendar-left}).
@item C-x >
Scroll calendar display one month backward
(@code{scroll-calendar-right}).
@item C-v
Scroll calendar display three months forward
(@code{scroll-calendar-left-three-months}).
@item M-v
Scroll calendar display three months backward
(@code{scroll-calendar-right-three-months}).
@item o
Prompt for month and year and scroll calendar to that month
(@code{calendar-other-month}).
@end table

@kindex C-x < (Calendar mode)
@findex scroll-calendar-left
@kindex C-x > (Calendar mode)
@findex scroll-calendar-right
  The most basic calendar scroll commands scroll by one month at a
time.  This means that there are two months of overlap between the
display before the command and the display after.  @kbd{C-x <} scrolls
the calendar contents one month to the left; that is, it moves the
display forward in time.  @kbd{C-x >} scrolls the contents to the
right, which moves backwards in time.

@kindex C-v (Calendar mode)
@findex scroll-calendar-left-three-months
@kindex M-v (Calendar mode)
@findex scroll-calendar-right-three-months
  The commands @kbd{C-v} and @kbd{M-v} scroll the calendar by an entire
``screenful''---three months---in analogy with the usual meaning of these
commands.  @kbd{C-v} makes later dates visible and @kbd{M-v} makes earlier
dates visible.  These commands also take a numeric argument as a repeat
count; in particular, since @kbd{C-u} (@code{universal-argument}) multiplies
the next command by four, typing @kbd{C-u C-v} scrolls the calendar forward by
a year and typing @kbd{C-u M-v} scrolls the calendar backward by a year.

  Any of the special Calendar mode commands will scroll the calendar
automatically as necessary to ensure that the date you have moved to
is visible.

@kindex o (Calendar mode)
@findex calendar-other-month
  You can scroll to an absolute date with
@kbd{o} (@code{calendar-other-month}).  This command prompts for a month
and year, and centers the three-month around that month.  You must enter
the year in its entirety; that is, type @samp{1990}, not @samp{90}.

@node Mark and Region, Misc Calendar, Scroll Calendar, Calendar
@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-=
Print the number of days in the current region
(@code{calendar-count-days-region}).
@end table

@kindex C-@@ (Calendar mode)
@kindex C-SPC (Calendar mode)
@findex calendar-set-mark
@kindex C-x C-x (Calendar mode)
@findex calendar-exchange-point-and-mark
  You set the mark in the calendar, as in any other buffer, by using @kbd{C-@@}
or @kbd{C-SPC} (@code{calendar-set-mark}).  You return to the marked date
with the command @kbd{C-x C-x} (@code{calendar-exchange-point-and-mark})
which puts the mark where point was and point where mark was.  The calendar
will be scrolled as necessary, if the marked date was not visible on the
screen.  This does not change the extent of the region.

@kindex M-= (Calendar mode)
@findex calendar-count-days-region
  To determine the number of days in the region, use @kbd{M-=}
(@code{calendar-count-days-region}).  The numbers of days printed will be
@emph{inclusive}, that is, will include 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{The Mark Ring}) operates exactly as in other buffers:  Emacs remembers
16 previous locations of the mark.  To return to a marked date, use @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 Misc Calendar, Holidays, Mark and Region, Calendar
@subsection Miscellaneous Calendar Commands

@table @kbd
@item c
Move point to today's date (@code{calendar-current-month}).
@item D
Display day-in-year (@code{cursor-to-calendar-day-of-year}).
@item ?
Briefly describe calendar commands (@code{describe-calendar-mode}).
@item SPC
Scroll the next window (@code{scroll-other-window}).
@item C-c C-l
Regenerate the calendar window (@code{redraw-calendar}).
@item q
Exit from calendar (@code{exit-calendar}).
@end table

@kindex c (Calendar mode)
@findex calendar-current-month
  You can always return to the current date with @kbd{c}
(@code{calendar-current-month}).

@kindex D (Calendar mode)
@findex cursor-to-calendar-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, use the @kbd{D}
command (@code{cursor-to-calendar-day-of-year}).  This displays both
of those numbers in the echo area.

@kindex ? (Calendar mode)
@findex describe-calendar-mode
  To display a brief description of the calendar commands, type @kbd{?}
(@code{describe-calendar-mode}).  For a fuller description, type @kbd{C-h m}.

@kindex SPC (Calendar mode)
@findex scroll-other-window
  You can use @kbd{SPC} (@code{scroll-other-window}) to scroll the other
window.  This is handy when you display a list of holidays or diary entries
in another window.

@kindex C-c C-l (Calendar mode)
@findex redraw-calendar
  If the calendar window gets corrupted, type @kbd{C-c C-l}
(@code{redraw-calendar}) to redraw it as it was.

@kindex q (Calendar mode)
@findex exit-calendar
  To exit from the calendar, type @kbd{q} (@code{exit-calendar}).  All
buffers related to the calendar will be deleted and the window display
will return to what it was when you entered the calendar.

@node Holidays, Other Calendars, Misc Calendar, Calendar
@subsection Holidays
@cindex holidays

  The Emacs calendar knows about all major and many minor holidays.

@table @kbd
@item h
Display holidays for the date indicated by point
(@code{calendar-cursor-holidays}).
@item x
Mark holidays in the calendar window (@code{mark-calendar-holidays}).
@item u
Unmark calendar window (@code{calendar-unmark}).
@item a
List all holidays for the displayed three months in another window
(@code{list-calendar-holidays}).
@item M-x holidays
List all holidays for three months around today's date in another
window.
@end table

@kindex h (Calendar mode)
@findex calendar-cursor-holidays
  To see if any holidays fall on a given date, position point on that
date in the calendar window and use the @kbd{h} command.  The holidays
are usually listed in the echo area, but if there are too many to fit in
one line, then they are displayed in a separate window.

@kindex x (Calendar mode)
@findex mark-calendar-holidays
@kindex u (Calendar mode)
@findex calendar-unmark
  To find the distribution of holidays for a wider period, you can use the
@kbd{x} command to mark all the days in the calendar display that have
holidays.  The mark appears as a @samp{*} next to the date in the calendar.
This command applies to the dates currently visible and new dates that
become visible by scrolling new months onto the display.  To erase these
marks from the calendar, use @kbd{u}, which also erases any diary marks
(@pxref{Diary}); neither holidays nor diary entries will be marked on new
dates that are scrolled into view.

@kindex a (Calendar mode)
@findex list-calendar-holidays
  To get even more detailed information, use the @kbd{a} command, which
displays a separate buffer containing a list of all holidays in the
current three-month range.

@findex holidays
  You can display the list of holidays for the current month and the
preceding and succeeding months even if you don't have a calendar window.
Use the command @kbd{M-x holidays}.

  The holidays known to Emacs include American holidays, as well as major
Christian, Jewish, and Islamic holidays.  The dates used by Emacs for
holidays are based on @emph{current practice}, not historical fact.
Historically, for instance, the start of daylight savings time and even its
existence have varied from year to year.  However present American law mandates
that daylight savings time begins on the first Sunday in April; this is the
definition that Emacs uses, even though it will be wrong for some prior years.

@vindex all-christian-calendar-holidays
@vindex all-hebrew-calendar-holidays
@vindex all-islamic-calendar-holidays
  The religious holidays known to Emacs are usually limited to 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} in your @file{.emacs}
file.

@vindex calendar-holidays
  You can easily customize the list of holidays to your own needs; to
find out how, use @kbd{C-h v calendar-holidays @key{RET}} after
entering the calendar.@refill

@node Other Calendars, Diary, Holidays, Calendar
@subsection Our Calendar and Other Calendars

  The Emacs calendar displayed is always the Gregorian calendar, sometimes
called the ``new style'' calendar, which is used in most of the world today.
However, this calendar did not exist before the sixteenth century and was
not widely used before the eighteenth century; it did not fully displace
the Julian calendar and gain universal acceptance until the early twentieth
century.  This poses a problem for the Emacs calendar: you can ask for the
calendar of any month after January, 1 AD, but the calendar displayed will
be the Gregorian, even for a date at which the Gregorian calendar did not
exist!

  Emacs knows about several different calendars, though, not just the
Gregorian calendar.  The following commands describe the date indicated
by point in various calendar notations:

@table @kbd
@item C
Display ISO commercial calendar equivalent for selected day
(@code{cursor-to-iso-calendar-date}).
@item J
Display Julian date for selected day (@code{cursor-to-julian-calendar-date}).
@item H
Display Hebrew date for selected day (@code{cursor-to-hebrew-calendar-date}).
@item I
Display Islamic date for selected day (@code{cursor-to-islamic-calendar-date}).
@item F
Display French Revolutionary date for selected day (@code{cursor-to-french-calendar-date}).
@end table

@kindex C (Calendar mode)
@findex cursor-to-iso-calendar-date
  You can find out the date on the ISO (International Standardization
Organization) commercial calendar---used largely in Europe---with the
@kbd{C} command.  The ISO date equivalent to the date indicated by point
will be displayed in the echo area.

@kindex J (Calendar mode)
@findex cursor-to-julian-calendar-date
  If you need to know the equivalent date on the Julian (``old style'')
calendar, use the @kbd{J} command.  This will display in the echo area
the Julian date for the day point is on.  The Julian calendar is no
longer in common use.

@kindex H (Calendar mode)
@findex cursor-to-hebrew-calendar-date
  If you want to know the equivalent date on the Hebrew (Jewish)
calendar, use the @kbd{H} command; this will display in the echo area
the Hebrew date for the day point is on.  The Hebrew calendar is the
one used to determine the dates of Jewish holidays.

@kindex I (Calendar mode)
@findex cursor-to-islamic-calendar-date
  To find the equivalent date on the Islamic (Moslem) calendar, use the
@kbd{I} command; this will display in the echo area the Islamic date for
the day point is on.  The Islamic calendar is the one used to determine
the dates of Moslem holidays.  Note that there is no universal agreement
in the Islamic world about the calendar; Emacs uses a widely accepted
version, but the precise dates of Islamic holidays often depend on
proclamation by religious authorities, not on calculations.  As a
consequence, the actual dates of occurrence can vary slightly from the
dates computed by Emacs.

@kindex F (Calendar mode)
@findex cursor-to-french-calendar-date
  To find the equivalent date on the French Revolutionary calendar, use
the @kbd{F} command; this will display in the echo area the French
Revolutionary date for the day point is on.  The French Revolutionary
calendar is no longer in use.

  You can move to dates that you specify on the Commercial, Julian, Hebrew,
or Islamic calendars:

@kindex g C (Calendar mode)
@findex calendar-goto-iso-date
@kindex g J (Calendar mode)
@findex calendar-goto-julian-date
@kindex g H (Calendar mode)
@findex calendar-goto-hebrew-date
@kindex g I (Calendar mode)
@findex calendar-goto-islamic-date
@table @kbd
@item g C
Move point to a date specified by the ISO commercial calendar
(@code{calendar-goto-iso-date}).
@item g J
Move point to a date specified by the Julian calendar
(@code{calendar-goto-julian-date}).
@item g H
Move point to a date specified by the Hebrew calendar
(@code{calendar-goto-hebrew-date}).
@item g I
Move point to a date specified by the Islamic calendar
(@code{calendar-goto-islamic-date}).
@end table

  These commands will ask you for a date on the other calendar, move the
point to the date equivalent to that date, and display the other calendar's
date in the echo area.

@node Diary, Diary File, Other Calendars, Calendar
@subsection The Diary
@cindex diary

  Associated with the Emacs calendar is a diary that keeps track of
appointments or other events on a daily basis.  To use the diary
feature, you must first create a @dfn{diary file} containing a list of
events and their dates.  Then Emacs can automatically pick out and
display the events for today, for the immediate future, or for any
specified date.

@table @kbd
@item d
Display any diary entries for the selected date
(@code{view-diary-entries}).
@item s
Display entire diary file (@code{show-all-diary-entries}).
@item m
Mark all visible dates that have diary entries
(@code{mark-diary-entries}).
@item u
Unmark calendar window (@code{calendar-unmark}).
@item M-x print-diary-entries
Print a hard copy of the diary display as it appears.
@item M-x diary
Display any diary entries for today's date.
@end table

@kindex d (Calendar mode)
@findex view-diary-entries
  Displaying the diary entries with @kbd{d} shows in a separate window
the diary entries for the date indicated by the point in the calendar
window.  The mode line of the new window shows the date of the diary
entries and any holidays that fall on that date.

  If you specify a numeric argument with @kbd{d}, then all the diary
entries for that many successive days are shown.  Thus, @kbd{2 d}
displays all the entries for the selected date and for the following
day.

@kindex m (Calendar mode)
@findex mark-diary-entries
@kindex u (Calendar mode)
@findex calendar-unmark
  To get a broader overview of which days are mentioned in the diary, use
the @kbd{m} command to mark those days in the calendar window.  The marks
appear next to the dates to which they apply.  The @kbd{m} command affects
the dates currently visible and, if you scroll the calendar, newly visible
dates as well.  The @kbd{u} command deletes all diary marks (and all
holiday marks too; @pxref{Holidays}), not only in the dates currently
visible, but dates that become visible when you scroll the calendar.

@kindex s (Calendar mode)
@findex show-all-diary-entries
  For more detailed information, use the @kbd{s} command, which displays
the entire diary file.

  The diary file is displayed using selective display, the same mechanism
used in Outline mode (@pxref{Outline Mode}).  This means that diary entries
that are not relevant are made invisible by changing the preceding newline
into an ASCII control-m (code 015).  These lines are invisible, but they
are part of the file; when you save the diary, the control-m characters are
saved as newlines so the invisible lines become ordinary lines in the file
without changing their visibility status in Emacs.

@findex print-diary-entries
  Because the diary buffer as you see it is an illusion, simply printing
the contents will not print what you see on your screen.  So there is a
special command to print a hard copy of the buffer @emph{as it appears};
this command is @kbd{M-x print-diary-entries}.  It sends the data
directly to the printer, and can be customized like @code{lpr-region}
(@pxref{Hardcopy}).

@findex diary
@vindex number-of-diary-entries
  The command @kbd{M-x diary} displays the diary entries for the current
date, independently of the calendar display.  Entries for the next few
days can be displayed as well; the number of days is governed by the
variable @code{number-of-diary-entries} (@pxref{Customizing Calendar}).

  The function @code{diary} is suitable for use in your @file{.emacs}
file to display automatically the day's diary entries when you enter
Emacs.  The mode line of the displayed window will show the date and any
holidays that fall on that date.  It is sufficient to put this
expression in @file{.emacs}:

@example
(diary)
@end example

@node Diary File, Sexp Diary Entries, Diary, Calendar
@subsection The Diary File
@cindex diary file

@vindex diary-file
  Your @dfn{diary file} is a file that records events associated with
particular dates.  The name of the diary file is specified by the variable
@code{diary-file}; @file{~/diary} is the default.  You can use the same file
for the @code{calendar} utility program since the formats are consistent.

  Each entry in the file describes one event and consists of one or more
lines.  It always begins with a date specification at the left margin.
The rest of the entry is simply text to describe the event.  If the
entry has more than one line, then the lines after the first must begin
with whitespace to indicate they continue a previous entry.

  Dates can be given numerically, as in @samp{@var{month}/@var{day}} or
@samp{@var{month}/@var{day}/@var{year}}.  This must be followed by a
nondigit.  In the date itself, @var{month} and @var{day} are numbers of
one or two digits.  @var{year} is a number and may be abbreviated to the
last two digits; that is, you can use @samp{11/12/1989} or
@samp{11/12/89}.

@cindex generic date
  A date may be @dfn{generic}, or partially unspecified.  Then the entry
applies to all dates that match the specification.  If the date does
not contain a year, it is generic and applies to any year.
Alternatively, @var{month}, @var{day}, or @var{year} can be a @samp{*};
this matches any month, day, or year, respectively.  Thus, a diary entry
@samp{3/*/*} will match any day in March of any year.@refill

  Dates can also have the form @samp{@var{monthname} @var{day}} or
@samp{@var{monthname} @var{day}, @var{year}}, where the month's name can
be spelled in full or abbreviated to three characters (with or without a
period).  Case is not significant.  If the date does not contain a year,
it is generic and applies to any year.  Also, @var{monthname},
@var{day}, or @var{year} can be a @samp{*} which matches any month, day,
or year, respectively.@refill

@vindex european-calendar-style
@findex european-calendar
  If you prefer the European style of writing dates---in which the day comes
before the month---type @kbd{M-x european-calendar} while in the calendar or
set the variable @code{european-calendar-style} to @code{t} in your
@file{.emacs} file before the calendar or diary command.  This causes
all dates in the diary to be interpreted in the European manner, and any dates
displayed on the terminal will be shown in the European form. (Note that there
is no comma after the @var{monthname} in the European style.)

@findex american-calendar
  To revert to the (default) American style of writing dates, type @kbd{M-x
american-calendar} while in the calendar.

  Dates can also have the form @var{dayname}.  The day name can be
spelled out in full (say, @samp{Tuesday}) or it can be abbreviated to
three characters (with or without a period); it need not be capitalized.
This form of date is generic and applies to any date on that day of the
week.@refill

  You may want entries that are not marked in the calendar window; this is
especially true of @var{dayname} style entries or entries such as
@samp{12/*}, each of which causes many marks in the calendar.  You can make
diary entries nonmarking by preceding them with an ampersand (@samp{&}).
Such entries are not marked on dates in the calendar window, but will
appear in a diary window.@refill

  Lines that do not begin with valid dates and do not continue a preceding
entry are ignored.

  Here are some sample diary entries:

@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

  If the first line of a diary entry consists only of the date or day
name with no following blanks or punctuation, then that line is not
displayed in the diary window; only the continuation lines are shown.
For example:

@example
02/11/1989
      Bill B. visits Princeton today
      2pm Cognitive Studies Committee meeting
      2:30-5:30 Liz at Lawrenceville
      4:00pm Dentist appt
      7:30pm Dinner at George's
      8:00-10:00pm concert
@end example

@noindent
will appear in the diary window without the date line at the beginning.
This facility allows the diary window to look neater when a single day's
entries are displayed, but can cause confusion if you ask for more than one
day's entries to be displayed.

  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 the cursor
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 will not cause problems; watch out for @kbd{C-e}
(@code{end-of-line}), however; it may put you at the end of a concealed
line far from where the cursor appears to be!  Before editing the diary, it
is best to display the entire file with @kbd{s}
(@code{show-all-diary-entries}).@refill

  While in the calendar, there are several commands to help you in making
entries to your diary.

@table @kbd
@item C-c d
Add a diary entry for the selected date (@code{insert-diary-entry}).
@item C-c w
Add a diary entry for the selected day of the week (@code{insert-weekly-diary-entry}).
@item C-c m
Add a diary entry for the selected day of the month (@code{insert-monthly-diary-entry}).
@item C-c y
Add a diary entry for the selected day of the year (@code{insert-yearly-diary-entry}).
@end table

@kindex C-c d (Calendar mode)
@findex insert-diary-entry
  You can make a diary entry for a specific date by moving point to that
date in the calendar window and using the @kbd{C-c d} command.  This
command causes the end of your diary file to be displayed in another
window and the date to be inserted; you can then type the diary entry.

@kindex C-c w (Calendar mode)
@findex insert-weekly-diary-entry
  If you want to make a diary entry that will apply to a specific day of
the week, move point to that day of the week (any occurrence will do) and
use the @kbd{C-c w} command.  The end of your file will be displayed in
another window and the name of the day of the week will be inserted; you
can then type the diary entry.

@kindex C-c m (Calendar mode)
@findex insert-monthly-diary-entry
@kindex C-c y (Calendar mode)
@findex insert-yearly-diary-entry
  You make a monthly diary entry in the same fashion.  Move point to the
day of the month, use the @kbd{C-c m} command, and type the diary entry.
Similarly, you make a yearly diary entry with the @kbd{C-c y} command.

  All of the above commands make marking diary entries.  If you want the diary
entry to be nonmarking, give a prefix argument to the command.  For example,
@kbd{C-u C-c w} will make a nonmarking, weekly diary entry.

  If you modify the diary, be sure to write the file before exiting from the
calendar.

@node Special Diary Entries, Customization, Diary File, Calendar
@subsection Special Diary Entries (Sexps)
@cindex diary file
  In addition to entries based on calendar dates, your diary file can contain
entries based on expressions (sexps) to be evaluated as the diary file is
scanned for entries for a given date.  Such an entry is indicated by @samp{%%}
at the beginning (preceded by @samp{&} for a nonmarking entry), followed by an
sexp in parentheses.  Here is such a diary entry that will apply to all dates
from June 24, 1990 through July 10, 1990:

@example
%%(diary-block 6 24 1990 7 10 1990) Vacation
@end example

@noindent
The @samp{6 24 1990} indicates the starting date and the @samp{7 10 1990}
indicates the stopping date.  (If you are using the European calendar style,
the months and days would be interchanged.)  Or, as another example, here is a
nonmarking diary entry that applies to the last Thursday in November:

@example
&%%(diary-float 11 4 -1) Payday
@end example

@noindent
In this last example, the @samp{11} specifies November, the @samp{4} specifies
Thursday (the fourth day of the week, counting Sunday as zero), and the
@samp{-1} specifies ``last'' (@samp{1} would mean ``first'', @samp{2} would
mean ``second'', @samp{-2} would mean ``second-to-last'', and so on).

  Anniversaries of dates can be specifed in the diary with, for example,

@example
%%(diary-anniversary 10 31 1948) Arthur's birthday
@end example

@noindent
This entry will apply to October 31 in any year after 1948; @samp{10 31 1948}
specifies the date.  (Again, if you are using the European calendar style, the
month and day would be interchanged.)

  You can specify cyclic diary entries that repeat after a fixed interval of
days.  For example,

@example
%%(diary-cyclic 50 1 1 1990) Renew medication
@end example

@noindent
will apply to January 1, 1990 and every 50th day following; @samp{1 1 1990}
specifies the starting date.  (Again, if you are using the European calendar
style, the month and day would be interchanged.)

  There are Calendar mode commands to help you in making block and anniversary
entries to your diary.

@table @kbd
@item C-c a
Add an anniversary diary entry for the selected date (@code{insert-anniversary-diary-entry}).
@item C-c b
Add a block diary entry for the current region (@code{insert-block-diary-entry}).
@item C-c c
Add a cyclic diary entry starting at the date (@code{insert-cyclic-diary-entry}).
@end table

@kindex C-c a (Calendar mode)
@findex insert-anniversary-diary-entry
  If you want to make a diary entry that will apply to the anniversary of a
specific date, move point to that date and use the @kbd{C-c a} command.  The
end of your diary file will be displayed in another window and the anniversary
description will be inserted; you can then type the diary entry.

@kindex C-c b (Calendar mode)
@findex insert-block-diary-entry
  You can make a diary entry entry for a block of dates by setting the mark
at the date at one end of the block, moving point to the date at the other
end of the block, and using the @kbd{C-c b} command.  This command
causes the end of your diary file to be displayed in another window and the
block description to be inserted; you can then type the diary entry.

@kindex C-c c (Calendar mode)
@findex insert-cyclic-diary-entry
  If you want to make a cyclic diary entry that will apply to a specific date
and every so many days afterward, move point to the starting date and use the
@kbd{C-c c} command.  You will be asked to type the interval, the end of your
diary file will be displayed in another window, and the cyclic description
will be inserted; you can then type the diary entry.

  All three of the these commands make marking diary entries.  If you want the
diary entry to be nonmarking, give a numeric argument to the command.  For
example, @kbd{C-u C-c a} will make 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 these diary entries are much better if they are
nonmarking.

  The sexp feature of the diary allows you to specify diary entries based on
any Emacs-Lisp expression.  You can use a library of built-in functions or you
can write your own functions.  The built-in functions include
@samp{diary-block}, @samp{diary-float}, @samp{diary-anniversary},
@samp{diary-cyclic}, and others (@pxref{Fancy Diary Display}).  For
more details on these functions and a description of how to write your own
functions, use @kbd{C-h f list-sexp-diary-entries @key{RET}} after entering
the diary.@refill

@node Customization,, Sexp Diary Entries, Calendar
@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
* Customizing Calendar::   Defaults you can set.
* Customizing Diary::      Defaults you can set.
* Hebrew/Islamic Entries:: How to obtain them.
* Fancy Diary Display::    Enhancing the diary display, sorting entries.
* Sharing Diary Files::    Including other files in the diary.
* Sexp Diary Entries::     Fancy things you can do.
@end menu

@node Customizing Calendar, Customizing Diary, Customization, Customization
@subsubsection Customizing the Calendar
@vindex view-diary-entries-initially
  The variable @code{view-diary-entries-initially}, whose default is
@code{nil}, can be set to to @code{t} to cause diary entries for the
current date to be displayed in another window when the calendar is first
displayed, if the current date is visible.  If you add the lines

@example
(setq view-diary-entries-initially t)
(calendar)
@end example

@noindent
to your @file{.emacs} file, then whenever you start the editor, you'll see
the calendar and the diary windows.

@vindex view-calendar-holidays-initially
  Similarly, if you set the variable
@code{view-calendar-holidays-initially} to @code{t}, it will cause the
holidays for the current three month period will be displayed on entry
to the calendar.  The holidays are displayed in a separate window.

@vindex mark-diary-entries-in-calendar
@vindex diary-entry-marker
  Setting the variable @code{mark-diary-entries-in-calendar} to @code{t}
causes any dates visible in the calendar window with diary entries to be
marked with the symbol specified by the variable @code{diary-entry-marker},
normally a plus sign (@samp{+}).  Whenever the calendar window is displayed or
redisplayed, the diary entries will be automatically marked.

@vindex mark-holidays-in-calendar
@vindex calendar-holiday-marker
  Similarly, setting the variable @code{mark-holidays-in-calendar} to
@code{t} causes any holidays visible in the calendar window to be marked
with the symbol specified by the variable @code{calendar-holiday-marker},
normally an asterisk (@samp{*}).  Whenever the calendar window is
displayed or redisplayed, the holidays will be automatically marked.

@vindex initial-calendar-window-hook
  There are many customizations that you can make with the hooks provided.
For example, the variable @code{initial-calendar-window-hook}, whose
default value is @code{nil}, is a list of functions to be called when the
calendar window is first opened.  The functions invoked are called after
the calendar window is opened, but once opened is never called again.
Leaving the calendar with the @kbd{q} command and reentering it will cause
these functions to be called again.

@vindex today-visible-calendar-hook
  The variable @code{today-visible-calendar-hook}, whose default value is
@code{nil}, is the list of functions called after the calendar buffer has
been prepared with the calendar when the current date is visible in the
window.  This hook can be used, for example, to replace today's date with
asterisks; a function @code{calendar-star-date} is included for this
purpose.  To use it, you would execute this expression:

@example
(setq today-visible-calendar-hook 'calendar-star-date)
@end example

@noindent
This hook could also be used to mark the current date with an asterisk; a
function is also provided for this, too:

@example
(setq today-visible-calendar-hook 'calendar-mark-today)
@end example

@vindex today-invisible-calendar-hook
@noindent
There is a corresponding variable @code{today-invisible-calendar-hook},
whose default value is @code{nil}, is the list of functions called after
the calendar buffer has been prepared with the calendar when the current
date is @emph{not} visible in the window.

@node Customizing Diary, Hebrew/Islamic Entries, Customizing Calendar, Customization
@subsubsection Customizing the Diary
@vindex holidays-in-diary-buffer
  Ordinarily, the mode line of the diary buffer window will indicate any
holidays that fall on the date of the diary entries.  The process of
checking for holidays takes several seconds, so the display of the diary
buffer is delayed slightly because the holiday information is included.
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}.

@vindex number-of-diary-entries
  The variable @code{number-of-diary-entries} controls the number of days of
diary entries that will be displayed initially (when
@code{view-diary-entries-initially} is set to @code{t}) or with the
command @kbd{M-x diary}.  For example, if the default value 1 is used,
then only the current day's diary entries will be displayed.  If the
value 2 is used, both the current day's and the next day's entries will
be displayed.  The value can also be a vector of seven elements: if the
value is @code{[0 2 2 2 2 4 1]} then no diary entries will be displayed
on Sunday, the current date's and the next day's diary entries will be
displayed Monday through Thursday, Friday through Monday's entries will
be displayed on Friday, while on Saturday only that day's entries will
be displayed.@refill

@vindex today-visible-calendar-hook
@vindex print-diary-entries-hook
@findex print-diary-entries
  The variable @code{print-diary-entries-hook} is the list of functions
called after a temporary buffer is prepared with the diary entries
currently visible in the diary buffer.  The default value of this hook adds
a heading (composed from the diary buffer's mode line), does the printing
with the command @code{lpr-buffer}, and kills the temporary 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
@vindex calendar-date-display-form
  You can customize the form of dates in your diary file if neither the
standard American nor European styles suits your needs; to find out how,
use @kbd{C-h v diary-date-forms @key{RET}} after entering the calendar.
You can similarly customize the form in which dates are displayed in the
diary, in mode lines, and in messages; use @kbd{C-h v
calendar-date-display-form @key{RET}} after entering the calendar.@refill

@node Hebrew/Islamic Entries, Fancy Diary Display, Customizing Diary, Customization
@subsubsection Hebrew- and Islamic-Date Diary Entries
  Your diary file can have entries based on Hebrew or Islamic dates, as well
as entries based on our usual Gregorian calendar.  However, because the
processing of such entries is time-consuming and most people don't need
them, you must customize the processing of your diary file to specify that
you want such entries recognized.  If you want Hebrew-date diary entries,
for example, you must include the lines

@vindex nongregorian-diary-listing-hook
@vindex nongregorian-diary-marking-hook
@findex list-hebrew-diary-entries
@findex mark-hebrew-diary-entries
@example
(setq nongregorian-diary-listing-hook 'list-hebrew-diary-entries)
(setq nongregorian-diary-marking-hook 'mark-hebrew-diary-entries)
@end example

@noindent
in your @file{.emacs} file.  If you want Islamic-date entries, include the
lines

@findex list-islamic-diary-entries
@findex mark-islamic-diary-entries
@example
(setq nongregorian-diary-listing-hook 'list-islamic-diary-entries)
(setq nongregorian-diary-marking-hook 'mark-islamic-diary-entries)
@end example

@noindent
If you want both Hebrew- and Islamic-date entries, include the lines

@example
(setq nongregorian-diary-listing-hook
      '(list-hebrew-diary-entries list-islamic-diary-entries))
(setq nongregorian-diary-marking-hook
      '(mark-hebrew-diary-entries mark-islamic-diary-entries))
@end example

  Hebrew- and Islamic-date diary entries have the same formats as
Gregorian-date diary entries, except that the date must be preceded with an
@samp{H} for Hebrew dates and an @samp{I} for Islamic dates.  Moreover,
because the Hebrew and Islamic month names are not uniquely specified by
the first three letters, they must be spelled out fully.  For example, a
diary entry for the Hebrew date Heshvan 25 could look like

@example
HHeshvan 25 Happy Hebrew birthday!
@end example

@noindent
and would appear in the diary for any date that corresponds to Heshvan 25
on the Hebrew calendar.  Similarly, an Islamic-date diary entry might be

@example
IDhu al-Qada 25 Happy Islamic birthday!
@end example

@noindent
and would appear in the diary for any date that corresponds to Dhu al-Qada 25
on the Islamic calendar.

  As with Gregorian-date diary entries, Hebrew- and Islamic-date entries
are nonmarking if they are preceded with an ampersand (@samp{&}).

There are commands to help you in making Hebrew- and Islamic-date entries
to your diary:


@table @kbd
@item C-c H d
Add a diary entry for the Hebrew date corresponding to the selected date
(@code{insert-hebrew-diary-entry}).
@item C-c H m
Add a diary entry for the day of the Hebrew month corresponding to the
selected date (@code{insert-monthly-hebrew-diary-entry}).
@item C-c H y
Add a diary entry for the day of the Hebrew year corresponding to the
selected date (@code{insert-yearly-hebrew-diary-entry}).
@item C-c I d
Add a diary entry for the Islamic date corresponding to the selected date
(@code{insert-islamic-diary-entry}).
@item C-c 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 C-c 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

@kindex C-c H d (Calendar mode)
@findex insert-hebrew-diary-entry
@kindex C-c H m (Calendar mode)
@findex insert-monthly-hebrew-diary-entry
@kindex C-c H y (Calendar mode)
@findex insert-yearly-hebrew-diary-entry
@kindex C-c I d (Calendar mode)
@findex insert-islamic-diary-entry
@kindex C-c I m (Calendar mode)
@findex insert-monthly-islamic-diary-entry
@kindex C-c I y (Calendar mode)
@findex insert-yearly-islamic-diary-entry
  These commands work exactly like the corresponding commands for ordinary
diary entries: Move point to a date in the calendar window and the above
commands insert the Hebrew or Islamic date (corresponding to the date
indicated by point) at the end of your diary file and you can then type the
diary entry.  If you want the diary entry to be nonmarking, give a numeric
argument to the command.

@node Fancy Diary Display, Sharing Diary Files, Hebrew/Islamic Entries, Customization
@subsubsection Fancy Diary Display
@vindex diary-display-hook
  After the diary buffer has been prepared, the functions specified by the
variable @code{diary-display-hook} are called.  The default value of
this hook simply displays the diary file using selective display to conceal
irrelevant diary entries.  However, if you specify the hook as follows,

@cindex diary buffer
@example
(setq diary-display-hook 'fancy-diary-buffer)
@end example

@noindent
Emacs will prepare a noneditable buffer with a neatly organized
day-by-day listing of relevant diary entries and known holidays.  If you
are using the fancy diary display, you get a hard copy of the buffer
with @kbd{M-x lpr-buffer}; you should @emph{not} use @kbd{M-x
print-diary-entries}.  Thus you can get a hard copy of a day-by-day
diary for a week by positioning the point on Sunday of that week, using
@kbd{7 d}, switching to the fancy diary, and using @kbd{M-x lpr-buffer}.
As in the standard diary buffer, 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}.@refill

@vindex diary-list-include-blanks
  Ordinarily, the fancy diary buffer will 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
@code{list-diary-entries-hook} to sort each day's diary entries.  Add the lines

@example
(setq list-diary-entries-hook
      '(lambda nil
         (setq diary-entries-list
               (sort diary-entries-list 'diary-entry-compare))))
@end example

@noindent
to your @file{.emacs} file.  For each day, diary entries that begin with a
recognizable time of day will be sorted into order, preceded by any diary
entries that do not begin with a time of day.

@node Sharing Diary Files, Sexp Diary Entries, Fancy Diary Display, Customization
@subsubsection Including Other Diary Files
@cindex diary include mechanism
  If you use the fancy diary display, you can have diary entries from other
files included with your own by an ``include'' mechanism.  This facility makes
possible the sharing of common diary files among groups of users.  Lines in
the diary file of the form

@example
#include "@var{filename}"
@end example

@noindent
cause the diary entries in the file @var{filename} to included in the
fancy diary buffer (because the ordinary diary buffer is just the buffer
associated with your diary file, you cannot use the include mechanism
unless you use the fancy diary buffer).  The include mechanism is
recursive, by the way, so that included files can cause other files to be
included, and so on; you must be careful not to have a cycle of inclusions,
of course.  To obtain the include facility, add lines as follows:

@vindex list-diary-entries-hook
@vindex mark-diary-entries-hook
@example
(setq list-diary-entries-hook 'include-other-diary-files)
(setq mark-diary-entries-hook 'mark-included-diary-files)
@end example

@noindent
to your @file{.emacs} file.

@noindent
To have both included files @emph{and} sorted diary entries, use the lines

@example
(setq list-diary-entries-hook
      '(include-other-diary-files
        (lambda nil
          (setq diary-entries-list
                (sort diary-entries-list 'diary-entry-compare)))))
(setq mark-diary-entries-hook 'mark-included-diary-files)
@end example

@node Sexp Diary Entries,, Sharing Diary Files, Customization
@subsubsection Sexp Entries and the Fancy Diary Display
@cindex sexp diary entries
  Sexp diary entries are especially powerful when the fancy diary display is
used because the function called can generate the text of the entry depending
on the date itself.  For example, the anniversary diary entry described above
(@pxref{Special Diary Entries}) can insert the number of years since
the anniversary date into the text of the diary entry.  Thus the dairy entry

@example
%%(diary-anniversary 10 31 1948) Arthur's birthday (%d years old)
@end example

@noindent
will have the @samp{%d} replaced by the age, so on October 31, 1990 the entry
will appear in the fancy diary buffer as

@example
Arthur's birthday (42 years old)
@end example

@noindent
If the diary file instead contains the entry

@example
%%(diary-anniversary 10 31 1948) Arthur's %d%s birthday
@end example

@noindent
the entry in the fancy diary buffer for October 31, 1990 will be

@example
Arthur's 42nd birthday
@end example

  Similarly, cyclic diary entries can interpolate the number of repetitions
that have occurred:

@example
%%(diary-cyclic 50 1 1 1990) Renew medication (%d%s time)
@end example

@noindent
will cause the diary entry

@example
Renew medication (5th time)
@end example

@noindent
to appear in the fancy diary display on September 8, 1990.

  The following sexp diary entries take advantage of the ability (in the fancy
diary display) to concoct diary entries based on the date:

@table @code
@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-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.
@end table

@noindent
Thus including the diary entry

@example
&%%(diary-hebrew-date)
@end example

@noindent
will cause every day's diary display to contain the equivalent date on the
Hebrew calendar, if you are using the fancy diary display.  (If you are not
using the fancy diary display, you will simply see the line
@samp{&%%(diary-hebrew-date)} when your diary file is displayed with any day's
diary entries.)

  There are a number of other available sexp diary entries that are important
to those who follow the Hebrew calendar:

@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 diary entry that tells the weekly synagogue scripture reading.
@item %%(diary-omer)
Make a diary entry that gives the omer count, when appropriate.
@item %%(diary-yahrzeit MONTH DAY YEAR) 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 will appear on
the proper Hebrew calendar anniversary and on the day before.  (If the
European style is used, the order of the parameters should be changed to
@code{DAY}, @code{MONTH}, @code{YEAR}.)
@end table


@bye

