[Emacs-diffs] Changes to emacs/man/emacs-xtra.texi

[Glenn Morris]

Index: emacs/man/emacs-xtra.texi
diff -c emacs/man/emacs-xtra.texi:1.8 emacs/man/emacs-xtra.texi:1.9
*** emacs/man/emacs-xtra.texi:1.8       Wed Feb  9 15:50:35 2005
--- emacs/man/emacs-xtra.texi   Sat Mar 26 17:45:40 2005
***************
*** 10,16 ****
  @copying
  This manual describes specialized features of Emacs.
  
! Copyright (C) 2004
  Free Software Foundation, Inc.
  
  @quotation
--- 10,16 ----
  @copying
  This manual describes specialized features of Emacs.
  
! Copyright (C) 2004, 2005
  Free Software Foundation, Inc.
  
  @quotation
***************
*** 59,64 ****
--- 59,65 ----
  * 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,312 ****
--- 308,1307 ----
  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 address@hidden
+ 
+ @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 @address@hidden
+ 
+ @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} @address@hidden@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
+ @address@hidden
+ 
+ @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 @address@hidden
+ 
+ @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 address@hidden, 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 address@hidden, 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 address@hidden, Emacs rings the
+ terminal bell for appointment reminders.  The default is @code{t}.
+ @item appt-visible
+ If this is address@hidden, Emacs displays the appointment
+ message in the echo area.  The default is @code{t}.
+ @item appt-display-mode-line
+ If this is address@hidden, 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 address@hidden, 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