Change position of @anchor's. Add anchor.
[bpt/emacs.git] / lispref / calendar.texi
index c23090b..f132ea8 100644 (file)
@@ -1,8 +1,8 @@
 @c -*-texinfo-*-
 @c This is part of the GNU Emacs Lisp Reference Manual.
-@c Copyright (C) 1990, 1991, 1992, 1993 Free Software Foundation, Inc. 
+@c Copyright (C) 1990, 1991, 1992, 1993, 1995, 1998 Free Software Foundation, Inc.
 @c See the file elisp.texi for copying conditions.
-@node Calendar, Tips, Display, Top
+@node Calendar, System Interface, Display, Top
 @chapter Customizing the Calendar and Diary
 
   There are many customizations that you can use to make the calendar and
@@ -16,8 +16,8 @@ diary suit your personal tastes.
 * 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.
+* Fancy Diary Display::    Enhancing the diary display, sorting entries,
+                             using included diary files.
 * Sexp Diary Entries::     Fancy things you can do.
 * Appt Customizing::      Customizing appointment reminders.
 @end menu
@@ -30,7 +30,7 @@ diary suit your personal tastes.
 @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
+your init file:@refill
 
 @example
 (setq view-diary-entries-initially t)
@@ -38,68 +38,85 @@ your @file{.emacs} file:@refill
 @end example
 
 @noindent
-they display both the calendar and diary windows whenever you start Emacs.
+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.@refill
+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 place a plus sign (@samp{+}) beside any dates with diary entries.
-Whenever the calendar window is displayed or redisplayed, the diary entries
-are automatically marked for holidays.
+  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}),
+or by placing a plus sign (@samp{+}) beside the date.
 
 @vindex mark-holidays-in-calendar
   Similarly, setting the variable @code{mark-holidays-in-calendar} to
-@code{t} places an asterisk (@samp{*}) after all holiday dates visible
-in the calendar window.
+@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.
 
 @vindex calendar-load-hook
-  There are many customizations that you can make with the hooks
-provided.  For example, the variable @code{calendar-load-hook}, whose
-default value is @code{nil}, is a normal hook run when the calendar
-package is first loaded (before actually starting to display the
-calendar).
+  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
-  The variable @code{initial-calendar-window-hook}, whose default value
-is @code{nil}, is a normal hook run the first time the calendar window
-is displayed.  The function is invoked only when you first enter
-Calendar mode, not when you redisplay an existing Calendar window.  But
-if you leave the calendar with the @kbd{q} command and reenter it, the
-hook runs again.@refill
+  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}, whose default value
-is @code{nil}, is a normal hook run after the calendar buffer has been
-prepared with the calendar when the current date is visible in the
-window.  One use of this hook is to replace today's date with asterisks;
-a function @code{calendar-star-date} is included for this purpose.  In
-your @file{.emacs} file, put:@refill
+  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
-(setq today-visible-calendar-hook 'calendar-star-date)
+(add-hook 'today-visible-calendar-hook 'calendar-star-date)
 @end example
 
 @noindent
-Another standard hook function adds asterisks around the current date.
-Here's how to use it:
+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
-(setq today-visible-calendar-hook 'calendar-mark-today)
+(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.
+
 @vindex today-invisible-calendar-hook
 @noindent
-  A corresponding variable, @code{today-invisible-calendar-hook}, whose
-default value is @code{nil}, is a normal hook run after the calendar
-buffer text has been prepared, if the current date is @emph{not} visible
-in the window.@refill
+  A similar normal hook, @code{today-invisible-calendar-hook} is run if
+the current date is @emph{not} visible in the window.
+
+@vindex calendar-move-hook
+  Starting in Emacs 21, each of the calendar cursor motion commands
+runs the hook @code{calendar-move-hook} after it moves the cursor.
 
 @node Holiday Customizing
 @section Customizing the Holidays
@@ -109,13 +126,13 @@ in the window.@refill
 @vindex hebrew-holidays
 @vindex islamic-holidays
   Emacs knows about holidays defined by entries on one of several lists.
-You can customize theses lists of holidays to your own needs, adding
-holidays or deleting lists of holidays.  The lists of holidays that
-Emacs uses are for general holidays (@code{general-holidays}), local
-holidays (@code{local-holidays}), Christian holidays
-(@code{christian-holidays}), Hebrew (Jewish) holidays
-(@code{hebrew-holidays}), Islamic (Moslem) holidays
-(@code{islamic-holidays}), and other holidays (@code{other-holidays}).
+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
@@ -130,10 +147,10 @@ described below.
 @vindex all-christian-calendar-holidays
 @vindex all-hebrew-calendar-holidays
 @vindex all-islamic-calendar-holidays
-  By default, Emacs does not consider all the holidays of these
-religions, only those commonly found in secular calendars.  For a more
-extensive collection of religious holidays, you can set any (or all) of
-the variables @code{all-christian-calendar-holidays},
+  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
@@ -142,56 +159,55 @@ variables @code{christian-holidays}, @code{hebrew-holidays}, and
 
 @vindex other-holidays
   You can set the variable @code{other-holidays} to any list of
-holidays.  This list, normally empty, is intended for your use.
+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).  Holiday forms may have the following
-formats:
+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.
+A fixed date on the Gregorian calendar.
 
 @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.
+from the end of the month.
 
 @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.
+A fixed date on the Hebrew calendar.
 
 @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.
+A fixed date on the Islamic calendar.
 
 @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.
+A fixed date on the Julian calendar.
 
 @item (holiday-sexp @var{sexp} @var{string})
-@var{sexp} is a Lisp expression that should use the variable @code{year}
-to compute the date of a holiday, or @code{nil} if the holiday doesn't
-happen this year.  The value represents the date as a list of the form
-@code{(@var{month} @var{day} @var{year})}.  @var{string} is the name of
-the holiday.
-
-@item (if @var{boolean} @var{holiday-form} &optional @var{holiday-form})
-A choice between two holidays based on the value of @var{boolean}.
-
-@item (@var{function} &optional @var{args})
-Dates requiring special computation; @var{args}, if any, are passed in
-a list to the function @code{calendar-holiday-function-@var{function}}.
+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})}.
+
+@item (if @var{condition} @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:
+France on July 14.  You can do this as follows:
 
 @smallexample
 (setq other-holidays '((holiday-fixed 7 14 "Bastille Day")))
@@ -233,18 +249,18 @@ birthday (since the Islamic months are numbered from 1 starting with
 Muharram), and Thomas Jefferson's birthday, which is 2 April 1743 on the
 Julian calendar.
 
-  To include a holiday conditionally, use either the @samp{if} or the
-@samp{sexp} form.  For example, American presidential elections occur on
-the first Tuesday after the first Monday in November of years divisible
-by 4:
+  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))
+(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"))
+                    (1+ (calendar-dayname-on-or-before
+                          1 (+ 6 (calendar-absolute-from-gregorian
+                                  (list 11 1 year)))))))
+              "US Presidential Election")
 @end smallexample
 
 @noindent
@@ -263,13 +279,11 @@ or
 
   Some holidays just don't fit into any of these forms because special
 calculations are involved in their determination.  In such cases you
-must write a Lisp function to do the calculation.  To include
-eclipses of the sun, for example, add @code{(eclipses)} to
-@code{other-holidays} and write an Emacs Lisp function
-@code{eclipses} that returns a (possibly
-empty) list of the relevant Gregorian dates among the
-range visible in the calendar window, with descriptive strings, like
-this:
+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") ... )
@@ -279,13 +293,13 @@ this:
 @section Date Display Format
 @vindex calendar-date-display-form
 
-  You can customize the manner of displaying dates in the diary,
-in mode lines, and in messages by setting
-@code{calendar-date-display-form}.  This variable is a list of
-expressions that can involve the variables @code{month}, @code{day}, and
-@code{year}, all numbers in string form, and @code{monthname} and
-@code{dayname}, both alphabetic strings.  In the American style, the
-default value of this list is as follows:
+  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)
@@ -298,6 +312,7 @@ while in the European style this value is the default:
 ((if dayname (concat dayname ", ")) day " " monthname " " year)
 @end smallexample
 
+@noindent
 The ISO standard date representation is this:
 
 @smallexample
@@ -315,33 +330,30 @@ This specifies a typical American format:
 @section Time Display Format
 @vindex calendar-time-display-form
 
-  In the calendar, diary, and related buffers, Emacs displays times of
-day in the conventional American style with the hours from 1 through 12,
-minutes, and either @samp{am} or @samp{pm}.  If you prefer the
-``military'' (European) style of writing times---in which the hours go
-from 00 to 23---you can alter the variable
-@code{calendar-time-display-form}.  This variable is a list of
-expressions that can involve the variables @code{12-hours},
-@code{24-hours}, and @code{minutes}, all numbers in string form, and
-@code{am-pm} and @code{time-zone}, both alphabetic strings.  The default
-definition of @code{calendar-time-display-form} is as follows:
+  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
 
-  Setting @code{calendar-time-display-form} to
+@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
 @section Daylight Savings Time
 @cindex daylight savings time
@@ -357,23 +369,24 @@ know which rules to use.
 where you are; on these systems, Emacs gets the information it needs
 from the system automatically.  If some or all of this information is
 missing, Emacs fills in the gaps with the rules currently used in
-Cambridge, Massachusetts.  If the default choice of rules is not
-appropriate for your location, you can tell Emacs the rules to use by
-setting certain variables.
+Cambridge, Massachusetts, which is the center of GNU's world.
+
 
 @vindex calendar-daylight-savings-starts
 @vindex calendar-daylight-savings-ends
-  These variables are @code{calendar-daylight-savings-starts} together
-with @code{calendar-daylight-savings-ends}.  Their values should be Lisp
+  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.
+  Emacs uses these expressions to determine the start and end dates of
+daylight savings time as holidays and for correcting times of day in the
+solar and lunar calculations.
 
   The values for Cambridge, Massachusetts are as follows:
 
@@ -396,8 +409,8 @@ changed to start on October 1, you would set
 @end example
 
   For a more complex example, suppose daylight savings time begins on
-the first of Nisan on the Hebrew calendar.  You would set
-@code{calendar-daylight-savings-starts} as follows:
+the first of Nisan on the Hebrew calendar.  You should set
+@code{calendar-daylight-savings-starts} to this value:
 
 @example
 (calendar-gregorian-from-absolute
@@ -414,14 +427,17 @@ all times in standard time, set @code{calendar-daylight-savings-starts}
 and @code{calendar-daylight-savings-ends} to @code{nil}.
 
 @vindex calendar-daylight-time-offset
-  This variable specifies the difference between daylight savings time and
-standard time, measured in minutes.  The value for Cambridge is 60.
+  The variable @code{calendar-daylight-time-offset} specifies the
+difference between daylight savings time and standard time, measured in
+minutes.  The value for Cambridge is 60.
 
 @vindex calendar-daylight-savings-starts-time
 @vindex calendar-daylight-savings-ends-time
-  These variables specify is the number of minutes after midnight local time
-when the transition to and from daylight savings time should occur.  For
-Cambridge, both variables' values are 120.
+  The variable @code{calendar-daylight-savings-starts-time} and the
+variable @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, both variables'
+values are 120.
 
 @node Diary Customizing
 @section Customizing the Diary
@@ -442,11 +458,11 @@ initial display when @code{view-diary-entries-initially} is @code{t}, as
 well as the command @kbd{M-x diary}.  For example, the default value is
 1, which says to display only the current day's diary entries.  If the
 value is 2, both the current day's and the next day's entries are
-displayed.  The value can also be a vector of seven elements: if the
-value is @code{[0 2 2 2 2 4 1]} then no diary entries appear on Sunday,
-the current date's and the next day's diary entries appear Monday
-through Thursday, Friday through Monday's entries appear on Friday,
-while on Saturday only that day's entries appear.
+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
@@ -463,18 +479,29 @@ order by day and time.
 @vindex diary-date-forms
   You can customize the form of dates in your diary file, if neither the
 standard American nor European styles suits your needs, by setting the
-variable @code{diary-date-forms}.  This variable is a list of forms of
-dates recognized in the diary file.  Each form is a list of regular
-expressions (@pxref{Regular Expressions}) and the variables
+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{Regular Expressions}) or the symbols
 @code{month}, @code{day}, @code{year}, @code{monthname}, and
-@code{dayname}.  The variable @code{monthname} matches the name of the
-month, capitalized or not, or its three-letter abbreviation, followed by
-a period or not; it matches @samp{*}.  Similarly, @code{dayname} matches
-the name of the day, capitalized or not, or its three-letter
-abbreviation, followed by a period or not.  The variables @code{month},
-@code{day}, and @code{year} match those numerical values, preceded by
-arbitrarily many zeros; they also match @samp{*}.  The default value of
-@code{diary-date-forms} in the American style is
+@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]")
@@ -484,19 +511,16 @@ arbitrarily many zeros; they also match @samp{*}.  The default value of
  (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}), but
-with the @samp{*} changed so that it is a word constituent.
-
-  The forms on the list must be @emph{mutually exclusive} and must not
-match any portion of the diary entry itself, just the date.  If, to be
-mutually exclusive, the pattern must match a portion of the diary entry
-itself, the first element of the form @emph{must} be @code{backup}.
-This causes the date recognizer to back up to the beginning of the
-current word of the diary entry.  Even if you use @code{backup}, the
-form must absolutely not match more than a portion of the first word of
-the diary entry.  The default value of @code{diary-date-forms} in the
+  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
@@ -508,56 +532,45 @@ European style is this list:
 @end example
 
 @noindent
-Notice the use of @code{backup} in the middle form because part of the
-diary entry must be matched to distinguish this form from the following one.
+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
 @section Hebrew- and Islamic-Date Diary Entries
 
   Your diary file can have entries based on Hebrew or Islamic dates, as
-well as entries based on our usual Gregorian calendar.  However, because
-the processing of such entries is time-consuming and most people don't
-need them, you must customize the processing of your diary file to
-specify that you want such entries recognized.  If you want Hebrew-date
-diary entries, for example, you must include these lines in your
-@file{.emacs} file:
+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
-(setq nongregorian-diary-listing-hook 'list-hebrew-diary-entries)
-(setq nongregorian-diary-marking-hook 'mark-hebrew-diary-entries)
+(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, include these lines in your
-@file{.emacs} file:
+If you want Islamic-date entries, do this:
 
 @findex list-islamic-diary-entries
 @findex mark-islamic-diary-entries
 @smallexample
-(setq nongregorian-diary-listing-hook 'list-islamic-diary-entries)
-(setq nongregorian-diary-marking-hook 'mark-islamic-diary-entries)
-@end smallexample
-
-@noindent
-If you want both Hebrew- and Islamic-date entries, include these lines:
-
-@smallexample
-(setq nongregorian-diary-listing-hook
-      '(list-hebrew-diary-entries list-islamic-diary-entries))
-(setq nongregorian-diary-marking-hook
-      '(mark-hebrew-diary-entries mark-islamic-diary-entries))
+(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 the date must be preceded with
-an @samp{H} for Hebrew dates and an @samp{I} for Islamic dates.
-Moreover, because the Hebrew and Islamic month names are not uniquely
-specified by the first three letters, you may not abbreviate them.  For
-example, a diary entry for the Hebrew date Heshvan 25 could look like
+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!
@@ -565,21 +578,19 @@ HHeshvan 25 Happy Hebrew birthday!
 
 @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
+on the Hebrew calendar.  And here is an 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{&}).
 
-  There are commands to help you in making Hebrew- and Islamic-date
-entries to your diary:
+  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
@@ -587,10 +598,14 @@ 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}).
+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}).
+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}).
@@ -608,12 +623,11 @@ selected date (@code{insert-yearly-islamic-diary-entry}).
 @findex insert-islamic-diary-entry
 @findex insert-monthly-islamic-diary-entry
 @findex insert-yearly-islamic-diary-entry
-  These commands work exactly like the corresponding commands for ordinary
-diary entries: Move point to a date in the calendar window and the above
-commands insert the Hebrew or Islamic date (corresponding to the date
-indicated by point) at the end of your diary file and you can then type the
-diary entry.  If you want the diary entry to be nonmarking, give a numeric
-argument to the command.
+  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
 @section Fancy Diary Display
@@ -621,10 +635,9 @@ argument to the command.
 @findex simple-diary-display
 
   Diary display works by preparing the diary buffer and then running the
-hook @code{diary-display-hook}.  The default value of this hook hides
-the irrelevant diary entries and then displays the buffer
-(@code{simple-diary-display}).  However, if you specify the hook as
-follows,
+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
@@ -633,15 +646,16 @@ follows,
 @end example
 
 @noindent
-then fancy mode displays diary entries and holidays by copying them into
-a special buffer that exists only for display.  Copying provides an
-opportunity to change the displayed text to make it prettier---for
-example, to sort the entries by the dates they apply to.
+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
+diary for a week, position 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}.
@@ -655,11 +669,11 @@ shown in the fancy diary buffer, set the variable
 @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:
+time of day.  Here's how:
 
 @findex sort-diary-entries
 @example
-(add-hook 'list-diary-entries-hook 'sort-diary-entries)
+(add-hook 'list-diary-entries-hook 'sort-diary-entries t)
 @end example
 
 @noindent
@@ -667,13 +681,9 @@ 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
-@section Included Diary Files
-
-  If you use the fancy diary display, you can have diary entries from other
-files included with your own by an ``include'' mechanism.  This facility makes
-possible the sharing of common diary files among groups of users.  Lines in
-the diary file of this form:
+  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}"
@@ -681,13 +691,10 @@ the diary file of this form:
 
 @noindent
 includes the diary entries from the file @var{filename} in the fancy
-diary buffer (because the ordinary diary buffer is just the buffer
-associated with your diary file, you cannot use the include mechanism
-unless you use the fancy diary buffer).  The include mechanism is
-recursive, by the way, so that included files can include other files,
-and so on; you must be careful not to have a cycle of inclusions, of
-course.  To enable the include facility, add lines as follows to your
-@file{.emacs} file:
+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
@@ -698,6 +705,9 @@ course.  To enable the include facility, add lines as follows to your
 (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
 @section Sexp Entries and the Fancy Diary Display
 @cindex sexp diary entries
@@ -754,10 +764,95 @@ Renew medication (5th time)
 @noindent
 in the fancy diary display on September 8, 1990.
 
-  The generality of sexp diary entries lets you specify any diary entry
-that you can describe algorithmically.  Suppose you get paid on the 21st
-of the month if it is a weekday, and to the Friday before if the 21st is
-on a weekend.  The diary entry
+  There is an early reminder diary sexp that includes its entry in the
+diary not only on the date of occurrence, but also on earlier dates.
+For example, if you want a reminder a week before your anniversary, you
+can use
+
+@findex diary-remind
+@smallexample
+%%(diary-remind '(diary-anniversary 12 22 1968) 7) Ed's anniversary
+@end smallexample
+
+@noindent
+and the fancy diary will show
+@smallexample
+Ed's anniversary
+@end smallexample
+@noindent
+both on December 15 and on December 22.
+
+@findex diary-date
+  The function @code{diary-date} applies to dates described by a month,
+day, year combination, each of which can be an integer, a list of
+integers, or @code{t}. The value @code{t} means all values.  For
+example,
+
+@smallexample
+%%(diary-date '(10 11 12) 22 t) Rake leaves
+@end smallexample
+
+@noindent
+causes the fancy diary to show
+
+@smallexample
+Rake leaves
+@end smallexample
+
+@noindent
+on October 22, November 22, and December 22 of every year.
+
+@findex diary-float
+  The function @code{diary-float} allows you to describe diary entries
+that apply to dates like the third Friday of November, or the last
+Tuesday in April.  The parameters are the @var{month}, @var{dayname},
+and an index @var{n}. The entry appears on the @var{n}th @var{dayname}
+of @var{month}, where @var{dayname}=0 means Sunday, 1 means Monday, and
+so on.  If @var{n} is negative it counts backward from the end of
+@var{month}.  The value of @var{month} can be a list of months, a single
+month, or @code{t} to specify all months.  You can also use an optional
+parameter @var{day} to specify the @var{n}th @var{dayname} of
+@var{month} on or after/before @var{day}; the value of @var{day} defaults
+to 1 if @var{n} is positive and to the last day of @var{month} if
+@var{n} is negative.  For example,
+
+@smallexample
+%%(diary-float t 1 -1) Pay rent
+@end smallexample
+
+@noindent
+causes the fancy diary to show
+
+@smallexample
+Pay rent
+@end smallexample
+
+@noindent
+on the last Monday of every month.
+
+  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.
+
+  The sexp diary entry applies to a date when the expression's value
+is non-@code{nil}, but some values have more specific meanings.  If
+the value is a string, that string is a description of the event which
+occurs on that date.  The value can also have the form
+@code{(@var{mark} . @var{string})}; then @var{mark} specifies how to
+mark the date in the calendar, and @var{string} is the description of
+the event.  If @var{mark} is a single-character string, that character
+appears next to the date in the calendar.  If @var{mark} is a face
+name, the date is displayed in that face.  If @var{mark} is
+@code{nil}, that specifies no particular highlighting for the date.
+
+  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))
@@ -767,16 +862,8 @@ on a weekend.  The diary entry
          ) Pay check deposited
 @end smallexample
 
-@noindent
-applies to just those dates.  This example illustrates how the sexp can
-depend on the variable @code{date}; this variable is a list (@var{month}
-@var{day} @var{year}) that gives the Gregorian date for which the diary
-entries are being found.  If the value of the expression is @code{t},
-the entry applies to that date.  If the expression evaluates to
-@code{nil}, the entry does @emph{not} apply to that date.
-
   The following sexp diary entries take advantage of the ability (in the fancy
-diary display) to concoct diary entries based on the date:
+diary display) to concoct diary entries whose text varies based on the date:
 
 @findex diary-sunrise-sunset
 @findex diary-phases-of-moon
@@ -816,9 +903,9 @@ Make a diary entry with today's equivalent date on the Mayan calendar.
 @noindent
 Thus including the diary entry
 
-@smallexample
+@example
 &%%(diary-hebrew-date)
-@end smallexample
+@end example
 
 @noindent
 causes every day's diary display to contain the equivalent date on the
@@ -826,8 +913,8 @@ Hebrew calendar, if you are using the fancy diary display.  (With simple
 diary display, the line @samp{&%%(diary-hebrew-date)} appears in the
 diary for any date, but does nothing particularly useful.)
 
-  There are a number of other available sexp diary entries that are important
-to those who follow the Hebrew calendar:
+  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
@@ -858,12 +945,16 @@ the European style, the order of the parameters is changed to @var{day},
 @var{month}, @var{year}.)
 @end table
 
+  All the functions documented above take an optional argument
+@var{mark} which specifies how to mark the date in the calendar display.
+If one of these functions decides that it applies to a certain date,
+it returns a value that contains @var{mark}.
+
 @node Appt Customizing
 @section Customizing Appointment Reminders
 
-  You can specify exactly how Emacs reminds you of an appointment and
-how far in advance it begins doing so.  Here are the variables that you
-can set:
+  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
@@ -871,23 +962,35 @@ can set:
 @vindex appt-display-mode-line
 @vindex appt-msg-window
 @vindex appt-display-duration
+@vindex appt-disp-window-function
+@vindex appt-delete-window-function
 @table @code
 @item appt-message-warning-time
 The time in minutes before an appointment that the reminder begins.  The
-default is 10 minutes.
+default is 12 minutes.
 @item appt-audible
-If this is @code{t} (the default), Emacs rings the terminal bell for
-appointment reminders.
+If this is non-@code{nil}, Emacs rings the
+terminal bell for appointment reminders.  The default is @code{t}.
 @item appt-visible
-If this is @code{t} (the default), Emacs displays the appointment
-message in echo area.
+If this is non-@code{nil}, Emacs displays the appointment
+message in the echo area.  The default is @code{t}.
 @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.
+If this is non-@code{nil}, Emacs displays the number of minutes
+to the appointment on the mode line.  The default is @code{t}.
 @item appt-msg-window
-If this is @code{t} (the default), Emacs displays the appointment
-message in another window.
+If this is non-@code{nil}, Emacs displays the appointment
+message in another window.  The default is @code{t}.
+@item appt-disp-window-function
+This variable holds a function to use to create the other window
+for the appointment message.
+@item appt-delete-window-function
+This variable holds a function to use to get rid of the appointment
+message window, when its time is up.
 @item appt-display-duration
-The number of seconds an appointment message is displayed.  The default
-is 5 seconds.
+The number of seconds to display an appointment message.  The default
+is 10 seconds.
 @end table
+
+@ignore
+   arch-tag: 8e50c766-4703-4888-a421-af15244cca7e
+@end ignore