cal-xtra.texi 32.2 KB
Newer Older
Eli Zaretskii's avatar
Eli Zaretskii committed
1
@c This is part of the Emacs manual.
Glenn Morris's avatar
Glenn Morris committed
2
@c Copyright (C) 2004, 2005, 2006, 2007, 2008 Free Software Foundation, Inc.
Eli Zaretskii's avatar
Eli Zaretskii committed
3 4
@c See file emacs.texi for copying conditions.
@c
5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34
@c This file is included either in emacs-xtra.texi (when producing the
@c printed version) or in the main Emacs manual (for the on-line version).

@c Moved here from the Emacs Lisp Reference Manual, 2005-03-26.
@node Advanced Calendar/Diary Usage
@section 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.
* 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.
@end menu

@node Calendar Customizing
@subsection Customizing the Calendar
@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
35 36
to mark a date that has diary entries.  By default, the calendar uses
faces named @code{holiday} and @code{diary} for these purposes.
37 38 39 40 41 42

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

43
@vindex calendar-initial-window-hook
44
  Starting the calendar runs the normal hook
45
@code{calendar-initial-window-hook}.  Recomputation of the calendar
46 47 48
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

49 50
@vindex calendar-today-visible-hook
  The variable @code{calendar-today-visible-hook} is a normal hook run
51 52 53 54 55 56 57
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
58
(add-hook 'calendar-today-visible-hook 'calendar-star-date)
59 60 61 62 63 64 65 66
@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
67
(add-hook 'calendar-today-visible-hook 'calendar-mark-today)
68 69 70 71 72 73 74
@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
75 76
face named @code{calendar-today} is provided for this purpose; that
symbol is the default for this variable.
77

78
@vindex calendar-today-invisible-hook
79
@noindent
80
  A similar normal hook, @code{calendar-today-invisible-hook} is run if
81 82 83 84 85 86 87 88 89 90
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
@subsection Customizing the Holidays

@vindex calendar-holidays
91 92 93 94
@vindex holiday-bahai-holidays
@vindex holiday-christian-holidays
@vindex holiday-hebrew-holidays
@vindex holiday-islamic-holidays
95 96 97
  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
98 99 100 101 102 103 104 105 106 107 108
general holidays (@code{holiday-general-holidays}), local holidays
(@code{holiday-local-holidays}), Baha'i holidays
(@code{holiday-bahai-holidays}), Christian holidays
(@code{holiday-christian-holidays}), Hebrew (Jewish) holidays
(@code{holiday-hebrew-holidays}), Islamic (Muslim) holidays
(@code{holiday-islamic-holidays}), Oriental holidays
(@code{holiday-oriental-holidays}), sun- and moon-related holidays
(@code{holiday-solar-holidays}), and other holidays
(@code{holiday-other-holidays}).

@vindex holiday-general-holidays
109
  The general holidays are, by default, holidays common throughout the
110 111
United States.  To eliminate these holidays, set
@code{holiday-general-holidays} to @code{nil}.
112

113
@vindex holiday-local-holidays
114
  There are no default local holidays (but sites may supply some).  You
115 116
can set the variable @code{holiday-local-holidays} to any list of
holidays, as described below.
117

118 119 120 121
@vindex calendar-bahai-all-holidays-flag
@vindex calendar-christian-all-holidays-flag
@vindex calendar-hebrew-all-holidays-flag
@vindex calendar-islamic-all-holidays-flag
122 123 124
  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
125 126 127 128
all) of the variables @code{calendar-bahai-all-holidays-flag},
@code{calendar-christian-all-holidays-flag},
@code{calendar-hebrew-all-holidays-flag}, or
@code{calendar-islamic-all-holidays-flag} to @code{t}.  If you want to
129
eliminate the religious holidays, set any or all of the corresponding
130 131 132
variables @code{holiday-bahai-holidays}, @code{holiday-christian-holidays},
@code{holiday-hebrew-holidays}, and @code{holiday-islamic-holidays} to
@code{nil}.@refill
133

134 135
@vindex holiday-other-holidays
  You can set the variable @code{holiday-other-holidays} to any list of
136 137 138
holidays.  This list, normally empty, is intended for individual use.

@cindex holiday forms
139 140 141 142 143 144
  Each of the lists (@code{holiday-general-holidays},
@code{holiday-local-holidays}, @code{holiday-bahai-holidays},
@code{holiday-christian-holidays}, @code{holiday-hebrew-holidays},
@code{holiday-islamic-holidays}, @code{holiday-oriental-holidays},
@code{holiday-solar-holidays}, and @code{holiday-other-holidays}) is a
list of @dfn{holiday forms}, each holiday form describing a holiday (or
145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210
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).

211 212
  You can specify holidays that occur on fixed days of the Baha'i,
Hebrew, Islamic, and Julian calendars too.  For example,
213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247

@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
248
           (calendar-extract-day
249 250 251 252 253 254 255 256 257 258
             (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,
259
for example, add @code{(eclipses)} to @code{holiday-other-holidays}
260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335
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
@subsection 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
@subsection 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 Diary Customizing
@subsection Customizing the Diary

336
@vindex diary-show-holidays-flag
337 338 339 340 341
  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
342
holiday information, set the variable @code{diary-show-holidays-flag} to
343 344
@code{nil}.@refill

345 346
@vindex diary-number-of-entries
  The variable @code{diary-number-of-entries} controls the number of
347
days of diary entries to be displayed at one time.  It affects the
348 349 350 351 352 353 354 355 356 357 358 359 360 361
initial display when @code{calendar-view-diary-initially-flag} 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 diary-print-entries-hook
@findex diary-print-entries
  The variable @code{diary-print-entries-hook} is a normal hook run
362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 407 408 409 410 411 412 413 414 415 416 417 418 419 420 421 422 423 424 425 426 427 428 429 430 431
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.

432
@c FIXME Baha'i.
433 434 435
@node Hebrew/Islamic Entries
@subsection Hebrew- and Islamic-Date Diary Entries

436 437 438 439 440 441 442 443 444 445 446
  Your diary file can have entries based on Baha'i, 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 diary-nongregorian-listing-hook
@vindex diary-nongregorian-marking-hook
@findex diary-hebrew-list-entries
@findex diary-hebrew-mark-entries
447
@smallexample
448 449
(add-hook 'diary-nongregorian-listing-hook 'diary-hebrew-list-entries)
(add-hook 'diary-nongregorian-marking-hook 'diary-hebrew-mark-entries)
450 451 452 453 454
@end smallexample

@noindent
If you want Islamic-date entries, do this:

455 456
@findex diary-islamic-list-entries
@findex diary-islamic-mark-entries
457
@smallexample
458 459
(add-hook 'diary-nongregorian-listing-hook 'diary-islamic-list-entries)
(add-hook 'diary-nongregorian-marking-hook 'diary-islamic-mark-entries)
460 461 462 463 464 465 466 467 468 469 470 471 472 473 474 475 476 477 478 479 480 481 482 483 484 485 486 487 488 489 490 491
@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
492
(@code{diary-hebrew-insert-entry}).
493 494
@item i h m
Add a diary entry for the day of the Hebrew month corresponding to the
495
selected date (@code{diary-hebrew-insert-monthly-entry}).  This diary
496 497 498 499
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
500
selected date (@code{diary-hebrew-insert-yearly-entry}).  This diary
501 502 503 504
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
505
(@code{diary-islamic-insert-entry}).
506 507
@item i i m
Add a diary entry for the day of the Islamic month corresponding to the
508
selected date (@code{diary-islamic-insert-monthly-entry}).
509 510
@item i i y
Add a diary entry for the day of the Islamic year corresponding to the
511
selected date (@code{diary-islamic-insert-yearly-entry}).
512 513
@end table

514 515 516 517 518 519
@findex diary-hebrew-insert-entry
@findex diary-hebrew-insert-monthly-entry
@findex diary-hebrew-insert-yearly-entry
@findex diary-islamic-insert-entry
@findex diary-islamic-insert-monthly-entry
@findex diary-islamic-insert-yearly-entry
520 521 522 523 524 525 526 527 528
  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
@subsection Fancy Diary Display
@vindex diary-display-hook
529
@findex diary-simple-display
530 531 532

  Diary display works by preparing the diary buffer and then running the
hook @code{diary-display-hook}.  The default value of this hook
533
(@code{diary-simple-display}) hides the irrelevant diary entries and
534 535 536
then displays the buffer.  However, if you specify the hook as follows,

@cindex diary buffer
537
@findex diary-fancy-display
538
@example
539
(add-hook 'diary-display-hook diary-'fancy-display)
540 541 542 543 544 545 546 547 548 549
@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
550
with @code{diary-print-entries}.  To print a hard copy of a day-by-day
551
diary for a week, position point on Sunday of that week, type
552
@kbd{7 d}, and then do @kbd{M-x diary-print-entries}.  As usual, the
553
inclusion of the holidays slows down the display slightly; you can speed
554
things up by setting the variable @code{diary-show-holidays-flag} to
555 556 557 558 559 560 561 562 563 564
@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
565
@code{diary-list-entries-hook} to sort each day's diary entries by their
566 567
time of day.  Here's how:

568
@findex diary-sort-entries
569
@example
570
(add-hook 'diary-list-entries-hook 'diary-sort-entries t)
571 572 573 574 575 576 577 578 579 580 581 582 583 584 585 586 587 588 589 590 591 592
@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:

593 594 595 596
@vindex diary-list-entries-hook
@vindex diary-mark-entries-hook
@findex diary-include-other-diary-files
@findex diary-mark-included-diary-files
597
@smallexample
598 599
(add-hook 'diary-list-entries-hook 'diary-include-other-diary-files)
(add-hook 'diary-mark-entries-hook 'diary-mark-included-diary-files)
600 601 602 603 604 605 606 607 608 609 610 611 612 613
@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
@subsection 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
614
diary entry.  Thus the @samp{%d} in this diary entry:
615 616 617 618 619 620 621 622 623 624 625 626 627 628 629 630 631 632 633 634 635 636 637 638 639 640 641 642 643 644 645 646 647 648 649 650 651 652 653 654 655 656 657 658 659 660 661 662 663 664 665 666 667 668 669 670 671 672 673 674 675 676 677 678 679 680 681 682 683 684 685 686 687 688 689 690 691 692 693 694 695 696 697 698 699 700 701 702 703 704 705 706 707 708 709 710 711 712 713 714 715 716 717 718 719 720 721 722 723 724 725 726 727 728 729 730 731 732 733 734 735 736 737 738 739 740 741 742 743 744 745 746 747 748 749 750 751 752 753 754 755 756 757 758 759 760 761 762 763 764 765 766 767

@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
768
@findex diary-bahai-date
769 770 771 772 773 774 775 776 777 778 779 780 781 782 783 784 785 786
@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.
787 788
@item %%(diary-bahai-date)
Make a diary entry with today's equivalent date on the Baha'i calendar.
789 790 791 792 793 794 795 796 797 798 799 800 801 802 803 804 805 806 807 808 809 810 811 812 813 814 815 816
@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
817
@findex diary-hebrew-rosh-hodesh
818
@cindex parasha, weekly
819
@findex diary-hebrew-parasha
820
@cindex candle lighting times
821
@findex diary-hebrew-sabbath-candles
822
@cindex omer count
823
@findex diary-hebrew-omer
824
@cindex yahrzeits
825
@findex diary-hebrew-yahrzeit
826
@table @code
827
@item %%(diary-hebrew-rosh-hodesh)
828 829
Make a diary entry that tells the occurrence and ritual announcement of each
new Hebrew month.
830
@item %%(diary-hebrew-parasha)
831
Make a Saturday diary entry that tells the weekly synagogue scripture reading.
832
@item %%(diary-hebrew-sabbath-candles)
833 834
Make a Friday diary entry that tells the @emph{local time} of Sabbath
candle lighting.
835
@item %%(diary-hebrew-omer)
836
Make a diary entry that gives the omer count, when appropriate.
837
@item %%(diary-hebrew-yahrzeit @var{month} @var{day} @var{year}) @var{name}
838 839 840 841 842 843 844 845 846 847 848
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}.
Miles Bader's avatar
Miles Bader committed
849 850 851 852

@ignore
   arch-tag: 52cb299f-fd1f-4616-bfe6-91b988669431
@end ignore