Mercurial > emacs

--- a/man/emacs-xtra.texi	Sat Mar 26 17:45:16 2005 +0000
+++ b/man/emacs-xtra.texi	Sat Mar 26 17:45:40 2005 +0000
@@ -10,7 +10,7 @@
 @copying
 This manual describes specialized features of Emacs.

-Copyright (C) 2004
+Copyright (C) 2004, 2005
 Free Software Foundation, Inc.

 @quotation
@@ -59,6 +59,7 @@
 * Introduction::                  What documentation belongs here?
 * Autorevert::                    Auto Reverting non-file buffers.
 * Subdir switches::               Subdirectory switches in Dired.
+* Advanced Calendar/Diary Usage:: Advanced Calendar/Diary customization.
 * Index::
 @end menu

@@ -307,6 +308,1000 @@
 all subdirectories with the buffer's default switches using
 @kbd{M-x dired-reset-subdir-switches}.  This also reverts the Dired buffer.

+
+@c Moved here from the Emacs Lisp Reference Manual, 2005-03-26.
+@node Advanced Calendar/Diary Usage
+@chapter Customizing the Calendar and Diary
+
+  There are many customizations that you can use to make the calendar and
+diary suit your personal tastes.
+
+@menu
+* Calendar Customizing::   Defaults you can set.
+* Holiday Customizing::    Defining your own holidays.
+* Date Display Format::    Changing the format.
+* Time Display Format::    Changing the format.
+* Daylight Savings::       Changing the default.
+* Diary Customizing::      Defaults you can set.
+* Hebrew/Islamic Entries:: How to obtain them.
+* Fancy Diary Display::    Enhancing the diary display, sorting entries,
+                             using included diary files.
+* Sexp Diary Entries::     Fancy things you can do.
+* Appt Customizing::	   Customizing appointment reminders.
+@end menu
+
+@node Calendar Customizing
+@section Customizing the Calendar
+@vindex view-diary-entries-initially
+
+  If you set the variable @code{view-diary-entries-initially} to
+@code{t}, calling up the calendar automatically displays the diary
+entries for the current date as well.  The diary dates appear only if
+the current date is visible.  If you add both of the following lines to
+your init file:@refill
+
+@example
+(setq view-diary-entries-initially t)
+(calendar)
+@end example
+
+@noindent
+this displays both the calendar and diary windows whenever you start Emacs.
+
+@vindex view-calendar-holidays-initially
+  Similarly, if you set the variable
+@code{view-calendar-holidays-initially} to @code{t}, entering the
+calendar automatically displays a list of holidays for the current
+three-month period.  The holiday list appears in a separate
+window.
+
+@vindex mark-diary-entries-in-calendar
+  You can set the variable @code{mark-diary-entries-in-calendar} to
+@code{t} in order to mark any dates with diary entries.  This takes
+effect whenever the calendar window contents are recomputed.  There are
+two ways of marking these dates: by changing the face
+(@pxref{Faces,,, elisp, the Emacs Lisp Reference Manual}), 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} 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 single-character string
+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
+  The variable @code{calendar-load-hook} is a normal hook run when the
+calendar package is first loaded (before actually starting to display
+the calendar).
+
+@vindex initial-calendar-window-hook
+  Starting the calendar runs the normal hook
+@code{initial-calendar-window-hook}.  Recomputation of the calendar
+display does not run this hook.  But if you leave the calendar with the
+@kbd{q} command and reenter it, the hook runs again.@refill
+
+@vindex today-visible-calendar-hook
+  The variable @code{today-visible-calendar-hook} is a normal hook run
+after the calendar buffer has been prepared with the calendar when the
+current date is visible in the window.  One use of this hook is to
+replace today's date with asterisks; to do that, use the hook function
+@code{calendar-star-date}.
+
+@findex calendar-star-date
+@example
+(add-hook 'today-visible-calendar-hook 'calendar-star-date)
+@end example
+
+@noindent
+Another standard hook function marks the current date, either by
+changing its face or by adding an asterisk.  Here's how to use it:
+
+@findex calendar-mark-today
+@example
+(add-hook 'today-visible-calendar-hook 'calendar-mark-today)
+@end example
+
+@noindent
+@vindex calendar-today-marker
+The variable @code{calendar-today-marker} specifies how to mark
+today's date.  Its value should be a single-character string 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 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
+  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
+
+@vindex calendar-holidays
+@vindex christian-holidays
+@vindex hebrew-holidays
+@vindex islamic-holidays
+  Emacs knows about holidays defined by entries on one of several lists.
+You can customize these lists of holidays to your own needs, adding or
+deleting holidays.  The lists of holidays that Emacs uses are for
+general holidays (@code{general-holidays}), local holidays
+(@code{local-holidays}), Christian holidays (@code{christian-holidays}),
+Hebrew (Jewish) holidays (@code{hebrew-holidays}), Islamic (Muslim)
+holidays (@code{islamic-holidays}), and other holidays
+(@code{other-holidays}).
+
+@vindex general-holidays
+  The general holidays are, by default, holidays common throughout the
+United States.  To eliminate these holidays, set @code{general-holidays}
+to @code{nil}.
+
+@vindex local-holidays
+  There are no default local holidays (but sites may supply some).  You
+can set the variable @code{local-holidays} to any list of holidays, as
+described below.
+
+@vindex all-christian-calendar-holidays
+@vindex all-hebrew-calendar-holidays
+@vindex all-islamic-calendar-holidays
+  By default, Emacs does not include all the holidays of the religions
+that it knows, only those commonly found in secular calendars.  For a
+more extensive collection of religious holidays, you can set any (or
+all) of the variables @code{all-christian-calendar-holidays},
+@code{all-hebrew-calendar-holidays}, or
+@code{all-islamic-calendar-holidays} to @code{t}.  If you want to
+eliminate the religious holidays, set any or all of the corresponding
+variables @code{christian-holidays}, @code{hebrew-holidays}, and
+@code{islamic-holidays} to @code{nil}.@refill
+
+@vindex other-holidays
+  You can set the variable @code{other-holidays} to any list of
+holidays.  This list, normally empty, is intended for individual use.
+
+@cindex holiday forms
+  Each of the lists (@code{general-holidays}, @code{local-holidays},
+@code{christian-holidays}, @code{hebrew-holidays},
+@code{islamic-holidays}, and @code{other-holidays}) is a list of
+@dfn{holiday forms}, each holiday form describing a holiday (or
+sometimes a list of holidays).
+
+  Here is a table of the possible kinds of holiday form.  Day numbers
+and month numbers count starting from 1, but ``dayname'' numbers
+count Sunday as 0.  The element @var{string} is always the
+name of the holiday, as a string.
+
+@table @code
+@item (holiday-fixed @var{month} @var{day} @var{string})
+A fixed date on the Gregorian calendar.
+
+@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.
+
+@item (holiday-hebrew @var{month} @var{day} @var{string})
+A fixed date on the Hebrew calendar.
+
+@item (holiday-islamic @var{month} @var{day} @var{string})
+A fixed date on the Islamic calendar.
+
+@item (holiday-julian @var{month} @var{day} @var{string})
+A fixed date on the Julian calendar.
+
+@item (holiday-sexp @var{sexp} @var{string})
+A date calculated by the Lisp expression @var{sexp}.  The expression
+should use the variable @code{year} to compute and return the date of a
+holiday, or @code{nil} if the holiday doesn't happen this year.  The
+value of @var{sexp} must represent the date as a list of the form
+@code{(@var{month} @var{day} @var{year})}.
+
+@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 as follows:
+
+@smallexample
+(setq other-holidays '((holiday-fixed 7 14 "Bastille Day")))
+@end smallexample
+
+@noindent
+The holiday form @code{(holiday-fixed 7 14 "Bastille Day")} specifies the
+fourteenth day of the seventh month (July).
+
+  Many holidays occur on a specific day of the week, at a specific time
+of month.  Here is a holiday form describing Hurricane Supplication Day,
+celebrated in the Virgin Islands on the fourth Monday in August:
+
+@smallexample
+(holiday-float 8 1 4 "Hurricane Supplication Day")
+@end smallexample
+
+@noindent
+Here the 8 specifies August, the 1 specifies Monday (Sunday is 0,
+Tuesday is 2, and so on), and the 4 specifies the fourth occurrence in
+the month (1 specifies the first occurrence, 2 the second occurrence,
+@minus{}1 the last occurrence, @minus{}2 the second-to-last occurrence, and
+so on).
+
+  You can specify holidays that occur on fixed days of the Hebrew,
+Islamic, and Julian calendars too.  For example,
+
+@smallexample
+(setq other-holidays
+      '((holiday-hebrew 10 2 "Last day of Hanukkah")
+        (holiday-islamic 3 12 "Mohammed's Birthday")
+        (holiday-julian 4 2 "Jefferson's Birthday")))
+@end smallexample
+
+@noindent
+adds the last day of Hanukkah (since the Hebrew months are numbered with
+1 starting from Nisan), the Islamic feast celebrating Mohammed's
+birthday (since the Islamic months are numbered from 1 starting with
+Muharram), and Thomas Jefferson's birthday, which is 2 April 1743 on the
+Julian calendar.
+
+  To include a holiday conditionally, use either Emacs Lisp's @code{if} or the
+@code{holiday-sexp} form.  For example, American presidential elections
+occur on the first Tuesday after the first Monday in November of years
+divisible by 4:
+
+@smallexample
+(holiday-sexp '(if (= 0 (% year 4))
+                   (calendar-gregorian-from-absolute
+                    (1+ (calendar-dayname-on-or-before
+                          1 (+ 6 (calendar-absolute-from-gregorian
+                                  (list 11 1 year)))))))
+              "US Presidential Election")
+@end smallexample
+
+@noindent
+or
+
+@smallexample
+(if (= 0 (% displayed-year 4))
+    (fixed 11
+           (extract-calendar-day
+             (calendar-gregorian-from-absolute
+               (1+ (calendar-dayname-on-or-before
+                     1 (+ 6 (calendar-absolute-from-gregorian
+                              (list 11 1 displayed-year)))))))
+           "US Presidential Election"))
+@end smallexample
+
+  Some holidays just don't fit into any of these forms because special
+calculations are involved in their determination.  In such cases you
+must write a Lisp function to do the calculation.  To include eclipses,
+for example, add @code{(eclipses)} to @code{other-holidays}
+and write an Emacs Lisp function @code{eclipses} that returns a
+(possibly empty) list of the relevant Gregorian dates among the range
+visible in the calendar window, with descriptive strings, like this:
+
+@smallexample
+(((6 27 1991) "Lunar Eclipse") ((7 11 1991) "Solar Eclipse") ... )
+@end smallexample
+
+@node Date Display Format
+@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 holds a list of expressions that can involve the variables
+@code{month}, @code{day}, and @code{year}, which are all numbers in
+string form, and @code{monthname} and @code{dayname}, which are both
+alphabetic strings.  In the American style, the default value of this
+list is as follows:
+
+@smallexample
+((if dayname (concat dayname ", ")) monthname " " day ", " year)
+@end smallexample
+
+@noindent
+while in the European style this value is the default:
+
+@smallexample
+((if dayname (concat dayname ", ")) day " " monthname " " year)
+@end smallexample
+
+@noindent
+The ISO standard date representation is this:
+
+@smallexample
+(year "-" month "-" day)
+@end smallexample
+
+@noindent
+This specifies a typical American format:
+
+@smallexample
+(month "/" day "/" (substring year -2))
+@end smallexample
+
+@node Time Display Format
+@section Time Display Format
+@vindex calendar-time-display-form
+
+  The calendar and diary by default display times of day in the
+conventional American style with the hours from 1 through 12, minutes,
+and either @samp{am} or @samp{pm}.  If you prefer the European style,
+also known in the US as military, in which the hours go from 00 to 23,
+you can alter the variable @code{calendar-time-display-form}.  This
+variable is a list of expressions that can involve the variables
+@code{12-hours}, @code{24-hours}, and @code{minutes}, which are all
+numbers in string form, and @code{am-pm} and @code{time-zone}, which are
+both alphabetic strings.  The default value of
+@code{calendar-time-display-form} is as follows:
+
+@smallexample
+(12-hours ":" minutes am-pm
+          (if time-zone " (") time-zone (if time-zone ")"))
+@end smallexample
+
+@noindent
+Here is a value that provides European style times:
+
+@smallexample
+(24-hours ":" minutes
+          (if time-zone " (") time-zone (if time-zone ")"))
+@end smallexample
+
+@node Daylight Savings
+@section Daylight Savings Time
+@cindex daylight savings time
+
+  Emacs understands the difference between standard time and daylight
+savings time---the times given for sunrise, sunset, solstices,
+equinoxes, and the phases of the moon take that into account.  The rules
+for daylight savings time vary from place to place and have also varied
+historically from year to year.  To do the job properly, Emacs needs to
+know which rules to use.
+
+  Some operating systems keep track of the rules that apply to the place
+where you are; on these systems, Emacs gets the information it needs
+from the system automatically.  If some or all of this information is
+missing, Emacs fills in the gaps with the rules currently used in
+Cambridge, Massachusetts, which is the center of GNU's world.
+
+
+@vindex calendar-daylight-savings-starts
+@vindex calendar-daylight-savings-ends
+  If the default choice of rules is not appropriate for your location,
+you can tell Emacs the rules to use by setting the variables
+@code{calendar-daylight-savings-starts} and
+@code{calendar-daylight-savings-ends}.  Their values should be Lisp
+expressions that refer to the variable @code{year}, and evaluate to the
+Gregorian date on which daylight savings time starts or (respectively)
+ends, in the form of a list @code{(@var{month} @var{day} @var{year})}.
+The values should be @code{nil} if your area does not use daylight
+savings time.
+
+  Emacs uses these expressions to determine the 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:
+
+@example
+@group
+(calendar-nth-named-day 1 0 4 year)
+(calendar-nth-named-day -1 0 10 year)
+@end group
+@end example
+
+@noindent
+i.e., the first 0th day (Sunday) of the fourth month (April) in
+the year specified by @code{year}, and the last Sunday of the tenth month
+(October) of that year.  If daylight savings time were
+changed to start on October 1, you would set
+@code{calendar-daylight-savings-starts} to this:
+
+@example
+(list 10 1 year)
+@end example
+
+  For a more complex example, suppose daylight savings time begins on
+the first of Nisan on the Hebrew calendar.  You should set
+@code{calendar-daylight-savings-starts} to this value:
+
+@example
+(calendar-gregorian-from-absolute
+  (calendar-absolute-from-hebrew
+    (list 1 1 (+ year 3760))))
+@end example
+
+@noindent
+because Nisan is the first month in the Hebrew calendar and the Hebrew
+year differs from the Gregorian year by 3760 at Nisan.
+
+  If there is no daylight savings time at your location, or if you want
+all times in standard time, set @code{calendar-daylight-savings-starts}
+and @code{calendar-daylight-savings-ends} to @code{nil}.
+
+@vindex calendar-daylight-time-offset
+  The variable @code{calendar-daylight-time-offset} specifies the
+difference between daylight savings time and standard time, measured in
+minutes.  The value for Cambridge is 60.
+
+@vindex calendar-daylight-savings-starts-time
+@vindex calendar-daylight-savings-ends-time
+  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
+
+@vindex holidays-in-diary-buffer
+  Ordinarily, the mode line of the diary buffer window indicates any
+holidays that fall on the date of the diary entries.  The process of
+checking for holidays can take several seconds, so including holiday
+information delays the display of the diary buffer noticeably.  If you'd
+prefer to have a faster display of the diary buffer but without the
+holiday information, set the variable @code{holidays-in-diary-buffer} to
+@code{nil}.@refill
+
+@vindex number-of-diary-entries
+  The variable @code{number-of-diary-entries} controls the number of
+days of diary entries to be displayed at one time.  It affects the
+initial display when @code{view-diary-entries-initially} is @code{t}, as
+well as the command @kbd{M-x diary}.  For example, the default value is
+1, which says to display only the current day's diary entries.  If the
+value is 2, both the current day's and the next day's entries are
+displayed.  The value can also be a vector of seven elements: for
+example, if the value is @code{[0 2 2 2 2 4 1]} then no diary entries
+appear on Sunday, the current date's and the next day's diary entries
+appear Monday through Thursday, Friday through Monday's entries appear
+on Friday, while on Saturday only that day's entries appear.
+
+@vindex print-diary-entries-hook
+@findex print-diary-entries
+  The variable @code{print-diary-entries-hook} is a normal hook run
+after preparation of a temporary buffer containing just the diary
+entries currently visible in the diary buffer.  (The other, irrelevant
+diary entries are really absent from the temporary buffer; in the diary
+buffer, they are merely hidden.)  The default value of this hook does
+the printing with the command @code{lpr-buffer}.  If you want to use a
+different command to do the printing, just change the value of this
+hook.  Other uses might include, for example, rearranging the lines into
+order by day and time.
+
+@vindex diary-date-forms
+  You can customize the form of dates in your diary file, if neither the
+standard American nor European styles suits your needs, by setting the
+variable @code{diary-date-forms}.  This variable is a list of patterns
+for recognizing a date.  Each date pattern is a list whose elements may
+be regular expressions (@pxref{Regular Expressions,,, elisp, the Emacs
+Lisp Reference Manual}) or the symbols @code{month}, @code{day},
+@code{year}, @code{monthname}, and @code{dayname}.  All these elements
+serve as patterns that match certain kinds of text in the diary file.
+In order for the date pattern, as a whole, to match, all of its elements
+must match consecutively.
+
+  A regular expression in a date pattern matches in its usual fashion,
+using the standard syntax table altered so that @samp{*} is a word
+constituent.
+
+  The symbols @code{month}, @code{day}, @code{year}, @code{monthname},
+and @code{dayname} match the month number, day number, year number,
+month name, and day name of the date being considered.  The symbols that
+match numbers allow leading zeros; those that match names allow
+three-letter abbreviations and capitalization.  All the symbols can
+match @samp{*}; since @samp{*} in a diary entry means ``any day'', ``any
+month'', and so on, it should match regardless of the date being
+considered.
+
+  The default value of @code{diary-date-forms} in the American style is
+this:
+
+@example
+((month "/" day "[^/0-9]")
+ (month "/" day "/" year "[^0-9]")
+ (monthname " *" day "[^,0-9]")
+ (monthname " *" day ", *" year "[^0-9]")
+ (dayname "\\W"))
+@end example
+
+  The date patterns in the list must be @emph{mutually exclusive} and
+must not match any portion of the diary entry itself, just the date and
+one character of whitespace.  If, to be mutually exclusive, the pattern
+must match a portion of the diary entry text---beyond the whitespace
+that ends the date---then the first element of the date pattern
+@emph{must} be @code{backup}.  This causes the date recognizer to back
+up to the beginning of the current word of the diary entry, after
+finishing the match.  Even if you use @code{backup}, the date pattern
+must absolutely not match more than a portion of the first word of the
+diary entry.  The default value of @code{diary-date-forms} in the
+European style is this list:
+
+@example
+((day "/" month "[^/0-9]")
+ (day "/" month "/" year "[^0-9]")
+ (backup day " *" monthname "\\W+\\<[^*0-9]")
+ (day " *" monthname " *" year "[^0-9]")
+ (dayname "\\W"))
+@end example
+
+@noindent
+Notice the use of @code{backup} in the third pattern, because it needs
+to match part of a word beyond the date itself to distinguish it from
+the fourth pattern.
+
+@node Hebrew/Islamic Entries
+@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 the world-standard Gregorian calendar.
+However, because recognition of such entries is time-consuming and most
+people don't use them, you must explicitly enable their use.  If you
+want the diary to recognize Hebrew-date diary entries, for example,
+you must do this:
+
+@vindex nongregorian-diary-listing-hook
+@vindex nongregorian-diary-marking-hook
+@findex list-hebrew-diary-entries
+@findex mark-hebrew-diary-entries
+@smallexample
+(add-hook 'nongregorian-diary-listing-hook 'list-hebrew-diary-entries)
+(add-hook 'nongregorian-diary-marking-hook 'mark-hebrew-diary-entries)
+@end smallexample
+
+@noindent
+If you want Islamic-date entries, do this:
+
+@findex list-islamic-diary-entries
+@findex mark-islamic-diary-entries
+@smallexample
+(add-hook 'nongregorian-diary-listing-hook 'list-islamic-diary-entries)
+(add-hook 'nongregorian-diary-marking-hook 'mark-islamic-diary-entries)
+@end smallexample
+
+  Hebrew- and Islamic-date diary entries have the same formats as
+Gregorian-date diary entries, except that @samp{H} precedes a Hebrew
+date and @samp{I} precedes an Islamic date.  Moreover, because the
+Hebrew and Islamic month names are not uniquely specified by the first
+three letters, you may not abbreviate them.  For example, a diary entry
+for the Hebrew date Heshvan 25 could look like this:
+
+@smallexample
+HHeshvan 25 Happy Hebrew birthday!
+@end smallexample
+
+@noindent
+and would appear in the diary for any date that corresponds to Heshvan 25
+on the Hebrew calendar.  And here is an Islamic-date diary entry that matches
+Dhu al-Qada 25:
+
+@smallexample
+IDhu al-Qada 25 Happy Islamic birthday!
+@end smallexample
+
+  As with Gregorian-date diary entries, Hebrew- and Islamic-date entries
+are nonmarking if they are preceded with an ampersand (@samp{&}).
+
+  Here is a table of commands used in the calendar to create diary entries
+that match the selected date and other dates that are similar in the Hebrew
+or Islamic calendar:
+
+@table @kbd
+@item i h d
+Add a diary entry for the Hebrew date corresponding to the selected date
+(@code{insert-hebrew-diary-entry}).
+@item i h m
+Add a diary entry for the day of the Hebrew month corresponding to the
+selected date (@code{insert-monthly-hebrew-diary-entry}).  This diary
+entry matches any date that has the same Hebrew day-within-month as the
+selected date.
+@item i h y
+Add a diary entry for the day of the Hebrew year corresponding to the
+selected date (@code{insert-yearly-hebrew-diary-entry}).  This diary
+entry matches any date which has the same Hebrew month and day-within-month
+as the selected date.
+@item i i d
+Add a diary entry for the Islamic date corresponding to the selected date
+(@code{insert-islamic-diary-entry}).
+@item i i m
+Add a diary entry for the day of the Islamic month corresponding to the
+selected date (@code{insert-monthly-islamic-diary-entry}).
+@item i i y
+Add a diary entry for the day of the Islamic year corresponding to the
+selected date (@code{insert-yearly-islamic-diary-entry}).
+@end table
+
+@findex insert-hebrew-diary-entry
+@findex insert-monthly-hebrew-diary-entry
+@findex insert-yearly-hebrew-diary-entry
+@findex insert-islamic-diary-entry
+@findex insert-monthly-islamic-diary-entry
+@findex insert-yearly-islamic-diary-entry
+  These commands work much like the corresponding commands for ordinary
+diary entries: they apply to the date that point is on in the calendar
+window, and what they do is insert just the date portion of a diary entry
+at the end of your diary file.  You must then insert the rest of the
+diary entry.
+
+@node Fancy Diary Display
+@section Fancy Diary Display
+@vindex diary-display-hook
+@findex simple-diary-display
+
+  Diary display works by preparing the diary buffer and then running the
+hook @code{diary-display-hook}.  The default value of this hook
+(@code{simple-diary-display}) hides the irrelevant diary entries and
+then displays the buffer.  However, if you specify the hook as follows,
+
+@cindex diary buffer
+@findex fancy-diary-display
+@example
+(add-hook 'diary-display-hook 'fancy-diary-display)
+@end example
+
+@noindent
+this enables fancy diary display.  It displays diary entries and
+holidays by copying them into a special buffer that exists only for the
+sake of display.  Copying to a separate buffer provides an opportunity
+to change the displayed text to make it prettier---for example, to sort
+the entries by the dates they apply to.
+
+  As with simple diary display, you can print a hard copy of the buffer
+with @code{print-diary-entries}.  To print a hard copy of a day-by-day
+diary for a week, 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}.
+
+@vindex diary-list-include-blanks
+  Ordinarily, the fancy diary buffer does not show days for which there are
+no diary entries, even if that day is a holiday.  If you want such days to be
+shown in the fancy diary buffer, set the variable
+@code{diary-list-include-blanks} to @code{t}.@refill
+
+@cindex sorting diary entries
+  If you use the fancy diary display, you can use the normal hook
+@code{list-diary-entries-hook} to sort each day's diary entries by their
+time of day.  Here's how:
+
+@findex sort-diary-entries
+@example
+(add-hook 'list-diary-entries-hook 'sort-diary-entries t)
+@end example
+
+@noindent
+For each day, this sorts diary entries that begin with a recognizable
+time of day according to their times.  Diary entries without times come
+first within each day.
+
+  Fancy diary display also has the ability to process included diary
+files.  This permits a group of people to share a diary file for events
+that apply to all of them.  Lines in the diary file of this form:
+
+@smallexample
+#include "@var{filename}"
+@end smallexample
+
+@noindent
+includes the diary entries from the file @var{filename} in the fancy
+diary buffer.  The include mechanism is recursive, so that included files
+can include other files, and so on; you must be careful not to have a
+cycle of inclusions, of course.  Here is how to enable the include
+facility:
+
+@vindex list-diary-entries-hook
+@vindex mark-diary-entries-hook
+@findex include-other-diary-files
+@findex mark-included-diary-files
+@smallexample
+(add-hook 'list-diary-entries-hook 'include-other-diary-files)
+(add-hook 'mark-diary-entries-hook 'mark-included-diary-files)
+@end smallexample
+
+The include mechanism works only with the fancy diary display, because
+ordinary diary display shows the entries directly from your diary file.
+
+@node Sexp Diary Entries
+@section Sexp Entries and the Fancy Diary Display
+@cindex sexp diary entries
+
+  Sexp diary entries allow you to do more than just have complicated
+conditions under which a diary entry applies.  If you use the fancy
+diary display, sexp entries can generate the text of the entry depending
+on the date itself.  For example, an anniversary diary entry can insert
+the number of years since the anniversary date into the text of the
+diary entry.  Thus the @samp{%d} in this dairy entry:
+
+@findex diary-anniversary
+@smallexample
+%%(diary-anniversary 10 31 1948) Arthur's birthday (%d years old)
+@end smallexample
+
+@noindent
+gets replaced by the age, so on October 31, 1990 the entry appears in
+the fancy diary buffer like this:
+
+@smallexample
+Arthur's birthday (42 years old)
+@end smallexample
+
+@noindent
+If the diary file instead contains this entry:
+
+@smallexample
+%%(diary-anniversary 10 31 1948) Arthur's %d%s birthday
+@end smallexample
+
+@noindent
+the entry in the fancy diary buffer for October 31, 1990 appears like this:
+
+@smallexample
+Arthur's 42nd birthday
+@end smallexample
+
+  Similarly, cyclic diary entries can interpolate the number of repetitions
+that have occurred:
+
+@findex diary-cyclic
+@smallexample
+%%(diary-cyclic 50 1 1 1990) Renew medication (%d%s time)
+@end smallexample
+
+@noindent
+looks like this:
+
+@smallexample
+Renew medication (5th time)
+@end smallexample
+
+@noindent
+in the fancy diary display on September 8, 1990.
+
+  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))
+         (day (car (cdr date))))
+      (or (and (= day 21) (memq dayname '(1 2 3 4 5)))
+          (and (memq day '(19 20)) (= dayname 5)))
+         ) Pay check deposited
+@end smallexample
+
+  The following sexp diary entries take advantage of the ability (in the fancy
+diary display) to concoct diary entries whose text varies based on the date:
+
+@findex diary-sunrise-sunset
+@findex diary-phases-of-moon
+@findex diary-day-of-year
+@findex diary-iso-date
+@findex diary-julian-date
+@findex diary-astro-day-number
+@findex diary-hebrew-date
+@findex diary-islamic-date
+@findex diary-french-date
+@findex diary-mayan-date
+@table @code
+@item %%(diary-sunrise-sunset)
+Make a diary entry for the local times of today's sunrise and sunset.
+@item %%(diary-phases-of-moon)
+Make a diary entry for the phases (quarters) of the moon.
+@item %%(diary-day-of-year)
+Make a diary entry with today's day number in the current year and the number
+of days remaining in the current year.
+@item %%(diary-iso-date)
+Make a diary entry with today's equivalent ISO commercial date.
+@item %%(diary-julian-date)
+Make a diary entry with today's equivalent date on the Julian calendar.
+@item %%(diary-astro-day-number)
+Make a diary entry with today's equivalent astronomical (Julian) day number.
+@item %%(diary-hebrew-date)
+Make a diary entry with today's equivalent date on the Hebrew calendar.
+@item %%(diary-islamic-date)
+Make a diary entry with today's equivalent date on the Islamic calendar.
+@item %%(diary-french-date)
+Make a diary entry with today's equivalent date on the French Revolutionary
+calendar.
+@item %%(diary-mayan-date)
+Make a diary entry with today's equivalent date on the Mayan calendar.
+@end table
+
+@noindent
+Thus including the diary entry
+
+@example
+&%%(diary-hebrew-date)
+@end example
+
+@noindent
+causes every day's diary display to contain the equivalent date on the
+Hebrew calendar, if you are using the fancy diary display.  (With simple
+diary display, the line @samp{&%%(diary-hebrew-date)} appears in the
+diary for any date, but does nothing particularly useful.)
+
+  These functions can be used to construct sexp diary entries based on
+the Hebrew calendar in certain standard ways:
+
+@cindex rosh hodesh
+@findex diary-rosh-hodesh
+@cindex parasha, weekly
+@findex diary-parasha
+@cindex candle lighting times
+@findex diary-sabbath-candles
+@cindex omer count
+@findex diary-omer
+@cindex yahrzeits
+@findex diary-yahrzeit
+@table @code
+@item %%(diary-rosh-hodesh)
+Make a diary entry that tells the occurrence and ritual announcement of each
+new Hebrew month.
+@item %%(diary-parasha)
+Make a Saturday diary entry that tells the weekly synagogue scripture reading.
+@item %%(diary-sabbath-candles)
+Make a Friday diary entry that tells the @emph{local time} of Sabbath
+candle lighting.
+@item %%(diary-omer)
+Make a diary entry that gives the omer count, when appropriate.
+@item %%(diary-yahrzeit @var{month} @var{day} @var{year}) @var{name}
+Make a diary entry marking the anniversary of a date of death.  The date
+is the @emph{Gregorian} (civil) date of death.  The diary entry appears
+on the proper Hebrew calendar anniversary and on the day before.  (In
+the European style, the order of the parameters is changed to @var{day},
+@var{month}, @var{year}.)
+@end table
+
+  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, by setting these variables:
+
+@vindex appt-message-warning-time
+@vindex appt-audible
+@vindex appt-visible
+@vindex appt-display-mode-line
+@vindex appt-msg-window
+@vindex appt-display-duration
+@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 12 minutes.
+@item appt-audible
+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 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 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 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 to display an appointment message.  The default
+is 10 seconds.
+@end table
+
+
 @node Index
 @unnumbered Index