Path: utzoo!utgpu!jarvis.csri.toronto.edu!clyde.concordia.ca!uunet!cs.utexas.edu!usc!brutus.cs.uiuc.edu!ux1.cso.uiuc.edu!ux1.cso.uiuc.edu!m.cs.uiuc.edu!p.cs.uiuc.edu!reingold
From: reingold@p.cs.uiuc.edu
Newsgroups: comp.emacs
Subject: Re: Calendar.el, revised
Message-ID: <77000014@p.cs.uiuc.edu>
Date: 2 Jan 90 17:39:30 GMT
References: <77000010@p.cs.uiuc.edu>
Lines: 746
Nf-ID: #R:p.cs.uiuc.edu:77000010:p.cs.uiuc.edu:77000014:000:31650
Nf-From: p.cs.uiuc.edu!reingold    Jan  1 15:54:00 1990


@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.
* 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.
* Customizing Calendar:: 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::
* Beg or End Calendar Motion::
@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 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}).
@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.

  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.

@node Misc Calendar, Holidays, Scroll Calendar, Calendar
@subsection Miscellaneous Calendar Commands

@table @kbd
@item c
Move point to today's date (@code{calendar-current-month}).
@item o
Prompt for month and year and move point to that month
(@code{calendar-other-month}).
@item D
Display day-in-year (@code{cursor-to-calendar-day-of-year}).
@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 o (Calendar mode)
@findex calendar-other-month
  You can move to an absolute date with
@kbd{o} (@code{calendar-other-month}).  This command prompts for a month
and year, and goes to the beginning of that month.  You must enter
the year in its entirety; that is, type @samp{1990}, not @samp{90}.

@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 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 calendar-holiday-list
  You can easily customize the list of holidays to your own needs; to
find out how, use @kbd{C-h v calendar-holiday-list @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}).
@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.

@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.

@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 dairy 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; see @ref{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, Customizing Calendar, Diary, Calendar
@subsection The Diary File
@cindex diary file

  Your @dfn{diary file} is a file that records events associated with
particular dates.  It is ordinarily named @file{~/diary}.

  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.  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{foward-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 @code{show-all-diary-entries}.  If
you modify the diary, be sure to write the file before exiting from the
calendar.@refill

@vindex diary-file
  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.

@node Customizing Calendar,, Diary File, Calendar
@subsection Customizing the Calendar and Diary

@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 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 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 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 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.

@vindex today-visible-calendar-hook
@vindex print-diary-entries-hook
  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.

  After the diary buffer has been prepared, the functions specified by the
variable @code{list-diary-entries-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 list-diary-entries-hook 'prepare-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 and using @kbd{7 d 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 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:

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

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

@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
@bye