[Top][All Lists]
[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[Emacs-diffs] Changes to cal-xtra.texi
|
From: |
Glenn Morris |
|
Subject: |
[Emacs-diffs] Changes to cal-xtra.texi |
|
Date: |
Thu, 06 Sep 2007 04:44:30 +0000 |
CVSROOT: /sources/emacs
Module name: emacs
Changes by: Glenn Morris <gm> 07/09/06 04:44:30
Index: cal-xtra.texi
===================================================================
RCS file: cal-xtra.texi
diff -N cal-xtra.texi
--- /dev/null 1 Jan 1970 00:00:00 -0000
+++ cal-xtra.texi 6 Sep 2007 04:44:30 -0000 1.1
@@ -0,0 +1,838 @@
address@hidden This is part of the Emacs manual.
address@hidden Copyright (C) 2004, 2005, 2006, 2007 Free Software Foundation,
Inc.
address@hidden See file emacs.texi for copying conditions.
address@hidden
address@hidden This file is included either in emacs-xtra.texi (when producing
the
address@hidden printed version) or in the main Emacs manual (for the on-line
version).
+
address@hidden Moved here from the Emacs Lisp Reference Manual, 2005-03-26.
address@hidden Advanced Calendar/Diary Usage
address@hidden Customizing the Calendar and Diary
+
+ There are many customizations that you can use to make the calendar and
+diary suit your personal tastes.
+
address@hidden
+* Calendar Customizing:: Defaults you can set.
+* Holiday Customizing:: Defining your own holidays.
+* Date Display Format:: Changing the format.
+* Time Display Format:: Changing the format.
+* 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.
address@hidden menu
+
address@hidden Calendar Customizing
address@hidden Customizing the Calendar
address@hidden calendar-holiday-marker
address@hidden 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.
+
address@hidden 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).
+
address@hidden initial-calendar-window-hook
+ Starting the calendar runs the normal hook
address@hidden Recomputation of the calendar
+display does not run this hook. But if you leave the calendar with the
address@hidden command and reenter it, the hook runs address@hidden
+
address@hidden 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
address@hidden
+
address@hidden calendar-star-date
address@hidden
+(add-hook 'today-visible-calendar-hook 'calendar-star-date)
address@hidden example
+
address@hidden
+Another standard hook function marks the current date, either by
+changing its face or by adding an asterisk. Here's how to use it:
+
address@hidden calendar-mark-today
address@hidden
+(add-hook 'today-visible-calendar-hook 'calendar-mark-today)
address@hidden example
+
address@hidden
address@hidden 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.
+
address@hidden today-invisible-calendar-hook
address@hidden
+ A similar normal hook, @code{today-invisible-calendar-hook} is run if
+the current date is @emph{not} visible in the window.
+
address@hidden calendar-move-hook
+ Each of the calendar cursor motion commands runs the hook
address@hidden after it moves the cursor.
+
address@hidden Holiday Customizing
address@hidden Customizing the Holidays
+
address@hidden calendar-holidays
address@hidden christian-holidays
address@hidden hebrew-holidays
address@hidden 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}).
+
address@hidden 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}.
+
address@hidden 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.
+
address@hidden all-christian-calendar-holidays
address@hidden all-hebrew-calendar-holidays
address@hidden 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},
address@hidden, or
address@hidden 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
address@hidden to @address@hidden
+
address@hidden other-holidays
+ You can set the variable @code{other-holidays} to any list of
+holidays. This list, normally empty, is intended for individual use.
+
address@hidden holiday forms
+ Each of the lists (@code{general-holidays}, @code{local-holidays},
address@hidden, @code{hebrew-holidays},
address@hidden, and @code{other-holidays}) is a list of
address@hidden 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.
+
address@hidden @code
address@hidden (holiday-fixed @var{month} @var{day} @var{string})
+A fixed date on the Gregorian calendar.
+
address@hidden (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.
+
address@hidden (holiday-hebrew @var{month} @var{day} @var{string})
+A fixed date on the Hebrew calendar.
+
address@hidden (holiday-islamic @var{month} @var{day} @var{string})
+A fixed date on the Islamic calendar.
+
address@hidden (holiday-julian @var{month} @var{day} @var{string})
+A fixed date on the Julian calendar.
+
address@hidden (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
address@hidden(@var{month} @var{day} @var{year})}.
+
address@hidden (if @var{condition} @var{holiday-form})
+A holiday that happens only if @var{condition} is true.
+
address@hidden (@var{function} @address@hidden@r{]})
+A list of dates calculated by the function @var{function}, called with
+arguments @var{args}.
address@hidden table
+
+ For example, suppose you want to add Bastille Day, celebrated in
+France on July 14. You can do this as follows:
+
address@hidden
+(setq other-holidays '((holiday-fixed 7 14 "Bastille Day")))
address@hidden smallexample
+
address@hidden
+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:
+
address@hidden
+(holiday-float 8 1 4 "Hurricane Supplication Day")
address@hidden smallexample
+
address@hidden
+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,
address@hidden 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,
+
address@hidden
+(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")))
address@hidden smallexample
+
address@hidden
+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
address@hidden form. For example, American presidential elections
+occur on the first Tuesday after the first Monday in November of years
+divisible by 4:
+
address@hidden
+(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")
address@hidden smallexample
+
address@hidden
+or
+
address@hidden
+(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"))
address@hidden 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:
+
address@hidden
+(((6 27 1991) "Lunar Eclipse") ((7 11 1991) "Solar Eclipse") ... )
address@hidden smallexample
+
address@hidden Date Display Format
address@hidden Date Display Format
address@hidden 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
address@hidden, @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:
+
address@hidden
+((if dayname (concat dayname ", ")) monthname " " day ", " year)
address@hidden smallexample
+
address@hidden
+while in the European style this value is the default:
+
address@hidden
+((if dayname (concat dayname ", ")) day " " monthname " " year)
address@hidden smallexample
+
address@hidden
+The ISO standard date representation is this:
+
address@hidden
+(year "-" month "-" day)
address@hidden smallexample
+
address@hidden
+This specifies a typical American format:
+
address@hidden
+(month "/" day "/" (substring year -2))
address@hidden smallexample
+
address@hidden Time Display Format
address@hidden Time Display Format
address@hidden 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
address@hidden, @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
address@hidden is as follows:
+
address@hidden
+(12-hours ":" minutes am-pm
+ (if time-zone " (") time-zone (if time-zone ")"))
address@hidden smallexample
+
address@hidden
+Here is a value that provides European style times:
+
address@hidden
+(24-hours ":" minutes
+ (if time-zone " (") time-zone (if time-zone ")"))
address@hidden smallexample
+
address@hidden Diary Customizing
address@hidden Customizing the Diary
+
address@hidden 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@refill
+
address@hidden 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.
+
address@hidden print-diary-entries-hook
address@hidden 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.
+
address@hidden 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},
address@hidden, @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:
+
address@hidden
+((month "/" day "[^/0-9]")
+ (month "/" day "/" year "[^0-9]")
+ (monthname " *" day "[^,0-9]")
+ (monthname " *" day ", *" year "[^0-9]")
+ (dayname "\\W"))
address@hidden 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
address@hidden 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:
+
address@hidden
+((day "/" month "[^/0-9]")
+ (day "/" month "/" year "[^0-9]")
+ (backup day " *" monthname "\\W+\\<[^*0-9]")
+ (day " *" monthname " *" year "[^0-9]")
+ (dayname "\\W"))
address@hidden example
+
address@hidden
+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.
+
address@hidden Hebrew/Islamic Entries
address@hidden 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:
+
address@hidden nongregorian-diary-listing-hook
address@hidden nongregorian-diary-marking-hook
address@hidden list-hebrew-diary-entries
address@hidden mark-hebrew-diary-entries
address@hidden
+(add-hook 'nongregorian-diary-listing-hook 'list-hebrew-diary-entries)
+(add-hook 'nongregorian-diary-marking-hook 'mark-hebrew-diary-entries)
address@hidden smallexample
+
address@hidden
+If you want Islamic-date entries, do this:
+
address@hidden list-islamic-diary-entries
address@hidden mark-islamic-diary-entries
address@hidden
+(add-hook 'nongregorian-diary-listing-hook 'list-islamic-diary-entries)
+(add-hook 'nongregorian-diary-marking-hook 'mark-islamic-diary-entries)
address@hidden 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:
+
address@hidden
+HHeshvan 25 Happy Hebrew birthday!
address@hidden smallexample
+
address@hidden
+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:
+
address@hidden
+IDhu al-Qada 25 Happy Islamic birthday!
address@hidden 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:
+
address@hidden @kbd
address@hidden i h d
+Add a diary entry for the Hebrew date corresponding to the selected date
+(@code{insert-hebrew-diary-entry}).
address@hidden 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.
address@hidden 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.
address@hidden i i d
+Add a diary entry for the Islamic date corresponding to the selected date
+(@code{insert-islamic-diary-entry}).
address@hidden 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}).
address@hidden 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}).
address@hidden table
+
address@hidden insert-hebrew-diary-entry
address@hidden insert-monthly-hebrew-diary-entry
address@hidden insert-yearly-hebrew-diary-entry
address@hidden insert-islamic-diary-entry
address@hidden insert-monthly-islamic-diary-entry
address@hidden 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.
+
address@hidden Fancy Diary Display
address@hidden Fancy Diary Display
address@hidden diary-display-hook
address@hidden 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,
+
address@hidden diary buffer
address@hidden fancy-diary-display
address@hidden
+(add-hook 'diary-display-hook 'fancy-diary-display)
address@hidden example
+
address@hidden
+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
address@hidden 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
address@hidden
+
address@hidden 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
address@hidden to @address@hidden
+
address@hidden sorting diary entries
+ If you use the fancy diary display, you can use the normal hook
address@hidden to sort each day's diary entries by their
+time of day. Here's how:
+
address@hidden sort-diary-entries
address@hidden
+(add-hook 'list-diary-entries-hook 'sort-diary-entries t)
address@hidden example
+
address@hidden
+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:
+
address@hidden
+#include "@var{filename}"
address@hidden smallexample
+
address@hidden
+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:
+
address@hidden list-diary-entries-hook
address@hidden mark-diary-entries-hook
address@hidden include-other-diary-files
address@hidden mark-included-diary-files
address@hidden
+(add-hook 'list-diary-entries-hook 'include-other-diary-files)
+(add-hook 'mark-diary-entries-hook 'mark-included-diary-files)
address@hidden smallexample
+
+The include mechanism works only with the fancy diary display, because
+ordinary diary display shows the entries directly from your diary file.
+
address@hidden Sexp Diary Entries
address@hidden Sexp Entries and the Fancy Diary Display
address@hidden 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 diary entry:
+
address@hidden diary-anniversary
address@hidden
+%%(diary-anniversary 10 31 1948) Arthur's birthday (%d years old)
address@hidden smallexample
+
address@hidden
+gets replaced by the age, so on October 31, 1990 the entry appears in
+the fancy diary buffer like this:
+
address@hidden
+Arthur's birthday (42 years old)
address@hidden smallexample
+
address@hidden
+If the diary file instead contains this entry:
+
address@hidden
+%%(diary-anniversary 10 31 1948) Arthur's %d%s birthday
address@hidden smallexample
+
address@hidden
+the entry in the fancy diary buffer for October 31, 1990 appears like this:
+
address@hidden
+Arthur's 42nd birthday
address@hidden smallexample
+
+ Similarly, cyclic diary entries can interpolate the number of repetitions
+that have occurred:
+
address@hidden diary-cyclic
address@hidden
+%%(diary-cyclic 50 1 1 1990) Renew medication (%d%s time)
address@hidden smallexample
+
address@hidden
+looks like this:
+
address@hidden
+Renew medication (5th time)
address@hidden smallexample
+
address@hidden
+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
+
address@hidden diary-remind
address@hidden
+%%(diary-remind '(diary-anniversary 12 22 1968) 7) Ed's anniversary
address@hidden smallexample
+
address@hidden
+and the fancy diary will show
address@hidden
+Ed's anniversary
address@hidden smallexample
address@hidden
+both on December 15 and on December 22.
+
address@hidden 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,
+
address@hidden
+%%(diary-date '(10 11 12) 22 t) Rake leaves
address@hidden smallexample
+
address@hidden
+causes the fancy diary to show
+
address@hidden
+Rake leaves
address@hidden smallexample
+
address@hidden
+on October 22, November 22, and December 22 of every year.
+
address@hidden 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
address@hidden 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
address@hidden 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
address@hidden is negative. For example,
+
address@hidden
+%%(diary-float t 1 -1) Pay rent
address@hidden smallexample
+
address@hidden
+causes the fancy diary to show
+
address@hidden
+Pay rent
address@hidden smallexample
+
address@hidden
+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
address@hidden 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
address@hidden(@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
address@hidden, 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:
+
address@hidden
+&%%(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
address@hidden 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:
+
address@hidden diary-sunrise-sunset
address@hidden diary-phases-of-moon
address@hidden diary-day-of-year
address@hidden diary-iso-date
address@hidden diary-julian-date
address@hidden diary-astro-day-number
address@hidden diary-hebrew-date
address@hidden diary-islamic-date
address@hidden diary-french-date
address@hidden diary-mayan-date
address@hidden @code
address@hidden %%(diary-sunrise-sunset)
+Make a diary entry for the local times of today's sunrise and sunset.
address@hidden %%(diary-phases-of-moon)
+Make a diary entry for the phases (quarters) of the moon.
address@hidden %%(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.
address@hidden %%(diary-iso-date)
+Make a diary entry with today's equivalent ISO commercial date.
address@hidden %%(diary-julian-date)
+Make a diary entry with today's equivalent date on the Julian calendar.
address@hidden %%(diary-astro-day-number)
+Make a diary entry with today's equivalent astronomical (Julian) day number.
address@hidden %%(diary-hebrew-date)
+Make a diary entry with today's equivalent date on the Hebrew calendar.
address@hidden %%(diary-islamic-date)
+Make a diary entry with today's equivalent date on the Islamic calendar.
address@hidden %%(diary-french-date)
+Make a diary entry with today's equivalent date on the French Revolutionary
+calendar.
address@hidden %%(diary-mayan-date)
+Make a diary entry with today's equivalent date on the Mayan calendar.
address@hidden table
+
address@hidden
+Thus including the diary entry
+
address@hidden
+&%%(diary-hebrew-date)
address@hidden example
+
address@hidden
+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:
+
address@hidden rosh hodesh
address@hidden diary-rosh-hodesh
address@hidden parasha, weekly
address@hidden diary-parasha
address@hidden candle lighting times
address@hidden diary-sabbath-candles
address@hidden omer count
address@hidden diary-omer
address@hidden yahrzeits
address@hidden diary-yahrzeit
address@hidden @code
address@hidden %%(diary-rosh-hodesh)
+Make a diary entry that tells the occurrence and ritual announcement of each
+new Hebrew month.
address@hidden %%(diary-parasha)
+Make a Saturday diary entry that tells the weekly synagogue scripture reading.
address@hidden %%(diary-sabbath-candles)
+Make a Friday diary entry that tells the @emph{local time} of Sabbath
+candle lighting.
address@hidden %%(diary-omer)
+Make a diary entry that gives the omer count, when appropriate.
address@hidden %%(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},
address@hidden, @var{year}.)
address@hidden table
+
+ All the functions documented above take an optional argument
address@hidden 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}.
+
address@hidden
+ arch-tag: 52cb299f-fd1f-4616-bfe6-91b988669431
address@hidden ignore