cal-xtra.texi 32.6 KB
Newer Older
Eli Zaretskii's avatar
Eli Zaretskii committed
1
@c This is part of the Emacs manual.
2 3
@c Copyright (C) 2004, 2005, 2006, 2007, 2008
@c   Free Software Foundation, Inc.
Eli Zaretskii's avatar
Eli Zaretskii committed
4 5
@c See file emacs.texi for copying conditions.
@c
6 7 8 9 10 11 12 13 14 15 16
@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
17
* Calendar Customizing::   Calendar layout and hooks.
18 19 20 21
* Holiday Customizing::    Defining your own holidays.
* Date Display Format::    Changing the format.
* Time Display Format::    Changing the format.
* Diary Customizing::      Defaults you can set.
22
* Non-Gregorian Diary::    Diary entries based on other calendars.
23 24 25 26 27 28 29
* 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
30 31 32

@vindex calendar-intermonth-text
@cindex calendar layout
33 34 35 36 37 38 39 40 41
@cindex calendar week numbers
  The calendar display unfortunately cannot be changed from three
months, but you can customize the whitespace used by setting the
variables: @code{calendar-left-margin},
@code{calendar-intermonth-spacing}, @code{calendar-column-width},
@code{calendar-day-header-width}, and @code{calendar-day-digit-width}.
To display text @emph{between} the months, for example week numbers,
customize the variables @code{calendar-intermonth-header} and
@code{calendar-intermonth-text} as described in their documentation.
42

43 44
@vindex calendar-holiday-marker
@vindex diary-entry-marker
45
@vindex calenday-today-marker
46
  The variable @code{calendar-holiday-marker} specifies how to mark a
47 48 49 50 51 52 53
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, and @code{calenday-today-marker} is used by
the function @code{calendar-mark-today} to mark today's date.  By
default, the calendar uses faces named @code{holiday}, @code{diary}, and
@code{calendar-today} for these purposes.
54 55 56 57 58 59

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

60
@vindex calendar-initial-window-hook
61
  Starting the calendar runs the normal hook
62
@code{calendar-initial-window-hook}.  Recomputation of the calendar
63 64 65
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

66
@vindex calendar-today-visible-hook
67
@findex calendar-star-date
68
  The variable @code{calendar-today-visible-hook} is a normal hook run
69 70
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
71 72
mark today's date; to do that use either of the functions
@code{calendar-mark-today} or @code{calendar-star-date}:
73 74

@findex calendar-mark-today
75
@smallexample
76
(add-hook 'calendar-today-visible-hook 'calendar-mark-today)
77
@end smallexample
78

79
@vindex calendar-today-invisible-hook
80
@noindent
81
  A similar normal hook, @code{calendar-today-invisible-hook} is run if
82 83 84 85 86 87 88 89 90 91
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
92 93
@vindex holiday-oriental-holidays
@vindex holiday-solar-holidays
94
  Emacs knows about holidays defined by entries on one of several lists.
95 96
The lists of holidays that Emacs uses are for general holidays
(@code{holiday-general-holidays}), local holidays
97 98 99 100 101 102 103 104 105
(@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}).

106 107 108 109
You can customize these lists of holidays to your own needs, deleting or
adding holidays as described below.  Set any of them to @code{nil} to
eliminate the associated holidays.

110
@vindex holiday-general-holidays
111
  The general holidays are, by default, holidays common throughout the
112
United States.
113

114
@vindex holiday-local-holidays
115
  There are no default local holidays, but your site may supply some.
116

117 118 119 120
@vindex holiday-bahai-holidays
@vindex holiday-christian-holidays
@vindex holiday-hebrew-holidays
@vindex holiday-islamic-holidays
121 122 123 124
@vindex calendar-bahai-all-holidays-flag
@vindex calendar-christian-all-holidays-flag
@vindex calendar-hebrew-all-holidays-flag
@vindex calendar-islamic-all-holidays-flag
125 126 127
  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
128 129 130
all) of the variables @code{calendar-bahai-all-holidays-flag},
@code{calendar-christian-all-holidays-flag},
@code{calendar-hebrew-all-holidays-flag}, or
131
@code{calendar-islamic-all-holidays-flag} to @code{t}.
132

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

@cindex holiday forms
138 139
  Each of the holiday variables is a list of @dfn{holiday forms}, each
form describing a holiday (or sometimes a list of holidays).
140 141 142 143

  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
144
description of the holiday, as a string.
145 146 147 148 149

@table @code
@item (holiday-fixed @var{month} @var{day} @var{string})
A fixed date on the Gregorian calendar.

150 151 152 153 154 155
@item (holiday-float @var{month} @var{dayname} @var{k} @var{string}
      &optional @var{day})
The @var{k}th @var{dayname} (@var{dayname}=0 for Sunday, and so on)
after or before Gregorian date @var{month}, @var{day}.  Negative @var{k}
means count back from the end of the month.  Optional @var{day} defaults
to 1 if @var{k} is positive, and the last day of @var{month} otherwise.
156

157 158 159
@item (holiday-chinese @var{month} @var{day} @var{string})
A fixed date on the Chinese calendar.

160 161 162 163 164 165 166 167 168 169 170 171
@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
172 173
holiday in the form of a list @code{(@var{month} @var{day} @var{year})},
or @code{nil} if the holiday doesn't happen this year.
174 175 176 177 178 179 180 181 182 183

@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
184 185
France on July 14 (i.e., the fourteenth day of the seventh month).  You
can do this as follows:
186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205

@smallexample
(setq other-holidays '((holiday-fixed 7 14 "Bastille Day")))
@end smallexample

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

206
  You can specify holidays that occur on fixed days of the Baha'i,
207
Chinese, Hebrew, Islamic, and Julian calendars too.  For example,
208 209 210 211 212 213 214 215 216 217 218 219 220 221 222

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

223 224 225 226
  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:
227 228

@smallexample
229
(holiday-sexp '(if (zerop (% year 4))
230 231 232 233 234 235 236 237 238 239 240
                   (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
241 242
(if (zerop (% displayed-year 4))
    (holiday-fixed 11
243
           (calendar-extract-day
244 245 246 247 248 249 250 251 252 253
             (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,
254
for example, add @code{(eclipses)} to @code{holiday-other-holidays}
255 256 257 258 259 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
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
287
The default ISO date representation is:
288 289

@smallexample
290 291
((format "%s-%.2d-%.2d" year (string-to-number month)
         (string-to-number day)))
292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312
@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
313
both alphabetic strings.  The default value is:
314 315 316 317 318 319 320 321 322 323 324 325 326 327

@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

328 329 330
Note that few calendar functions return a time of day (at present, only
solar functions).

331 332 333
@node Diary Customizing
@subsection Customizing the Diary

334
@vindex diary-show-holidays-flag
335 336 337 338 339
  Ordinarily, the mode line of the diary window indicates any holidays
that fall on the date of the diary entries.  The process of checking for
holidays can be slow, depending on the defined holidays.  In that case,
setting @code{diary-show-holidays-flag} to @code{nil} will speed up the
diary display.
340

341 342
@vindex diary-number-of-entries
  The variable @code{diary-number-of-entries} controls the number of
343
days of diary entries to be displayed at one time.  It affects the
344
initial display when @code{calendar-view-diary-initially-flag} is
345 346 347 348 349 350 351 352
@code{t}, as well as the command @kbd{M-x diary}.  For example, a value
of 1 (the default) displays only the current day's diary entries,
whereas a value of 2 will also show the next day's entries.  The value
can also be a vector of seven integers: 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.
353 354 355 356

@vindex diary-print-entries-hook
@findex diary-print-entries
  The variable @code{diary-print-entries-hook} is a normal hook run
357 358 359 360 361 362 363 364 365 366
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
367
  You can customize the form of dates in your diary file by setting the
368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384
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
385 386 387 388 389
capitalization and abbreviation (as specified by
@code{calendar-month-abbrev-array} and
@code{calendar-day-abbrev-array}).  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.
390 391

  The default value of @code{diary-date-forms} in the American style is
392
provided by @code{diary-american-date-forms}:
393 394 395 396 397 398 399 400 401

@example
((month "/" day "[^/0-9]")
 (month "/" day "/" year "[^0-9]")
 (monthname " *" day "[^,0-9]")
 (monthname " *" day ", *" year "[^0-9]")
 (dayname "\\W"))
@end example

402 403 404 405
@noindent
Other default styles are provided by @code{diary-european-date-forms}
and @code{diary-iso-date-forms}.

406 407 408 409 410 411 412 413 414
  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
415 416
diary entry.  For example, the default value of
@code{diary-european-date-forms} is:
417 418 419 420

@example
((day "/" month "[^/0-9]")
 (day "/" month "/" year "[^0-9]")
421
 (backup day " *" monthname "\\W+\\<\\([^*0-9]\\|\\([0-9]+[:aApP]\\)\\)")
422 423 424 425 426 427 428 429 430
 (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.

431
@node Non-Gregorian Diary
432
@subsection Diary Entries Using non-Gregorian Calendars
433

434 435 436 437 438 439
  As well as entries based on the standard Gregorian calendar, your
diary can have entries based on Baha'i, Hebrew, or Islamic dates.
Recognition of such entries can be time-consuming, however, and since
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:
440 441 442 443 444

@vindex diary-nongregorian-listing-hook
@vindex diary-nongregorian-marking-hook
@findex diary-hebrew-list-entries
@findex diary-hebrew-mark-entries
445 446 447 448
@findex diary-islamic-list-entries
@findex diary-islamic-mark-entries
@findex diary-bahai-list-entries
@findex diary-bahai-mark-entries
449
@smallexample
450 451
(add-hook 'diary-nongregorian-listing-hook 'diary-hebrew-list-entries)
(add-hook 'diary-nongregorian-marking-hook 'diary-hebrew-mark-entries)
452 453 454
@end smallexample

@noindent
455 456 457 458 459 460 461 462 463 464 465 466 467 468 469
Similarly, for Islamic and Baha'i entries, add
@code{diary-islamic-list-entries} and @code{diary-islamic-mark-entries}, or
@code{diary-bahai-list-entries} and @code{diary-bahai-mark-entries}.

@vindex diary-bahai-entry-symbol
@vindex diary-hebrew-entry-symbol
@vindex diary-islamic-entry-symbol
  These diary entries have the same formats as Gregorian-date diary
entries; except that @code{diary-bahai-entry-symbol} (default @samp{B})
must precede a Baha'i date, @code{diary-hebrew-entry-symbol} (default
@samp{H}) a Hebrew date, and @code{diary-islamic-entry-symbol} (default
@samp{I}) an Islamic date.  Moreover, non-Gregorian month names may not
be abbreviated (because the first three letters are often not unique).
For example, a diary entry for the Hebrew date Heshvan 25 could look
like this:
470 471 472 473 474 475 476 477 478 479 480 481 482 483

@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

484 485 486
  As with Gregorian-date diary entries, non-Gregorian entries are
nonmarking if preceded by @code{diary-nonmarking-symbol} (default
@samp{&}).
487

488 489 490
  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 Baha'i, Hebrew, or Islamic calendars:
491 492 493

@table @kbd
@item i h d
494
@code{diary-hebrew-insert-entry}
495
@item i h m
496
@code{diary-hebrew-insert-monthly-entry}
497
@item i h y
498
@code{diary-hebrew-insert-yearly-entry}
499
@item i i d
500
@code{diary-islamic-insert-entry}
501
@item i i m
502
@code{diary-islamic-insert-monthly-entry}
503
@item i i y
504 505 506 507 508 509 510
@code{diary-islamic-insert-yearly-entry}
@item i B d
@code{diary-bahai-insert-entry}
@item i B m
@code{diary-bahai-insert-monthly-entry}
@item i B y
@code{diary-bahai-insert-yearly-entry}
511 512
@end table

513 514 515 516 517 518
@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
519 520 521
@findex diary-bahai-insert-entry
@findex diary-bahai-insert-monthly-entry
@findex diary-bahai-insert-yearly-entry
522 523
  These commands work much like the corresponding commands for ordinary
diary entries: they apply to the date that point is on in the calendar
524 525 526 527 528 529
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.  The basic commands add an entry for the specific
non-Gregorian date, the @samp{monthly} commands for the given
non-Gregorian day-within-month in every month, and the @samp{yearly}
commands for the given non-Gregorian day and month in every year.
530 531 532

@node Fancy Diary Display
@subsection Fancy Diary Display
533
@vindex diary-display-function
534
@findex diary-simple-display
535 536
@findex diary-fancy-display
@cindex diary buffer
537 538

  Diary display works by preparing the diary buffer and then running the
539 540
function specified by the variable @code{diary-display-function}.  The
default value (@code{diary-simple-display}) hides the irrelevant diary
541 542 543 544 545 546
entries and then displays the buffer.  The alternative
@code{diary-fancy-display} 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.
547 548

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

567
@findex diary-sort-entries
568
@example
569
(add-hook 'diary-list-entries-hook 'diary-sort-entries t)
570 571 572 573 574 575 576
@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.

577
@vindex diary-include-string
578 579
  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
580 581
that apply to all of them.  Lines in the diary file starting with
@code{diary-include-string}:
582 583 584 585 586 587

@smallexample
#include "@var{filename}"
@end smallexample

@noindent
588 589 590 591 592
include 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 597
@vindex diary-list-entries-hook
@vindex diary-mark-entries-hook
@findex diary-include-other-diary-files
@findex diary-mark-included-diary-files
598
@smallexample
599 600
(add-hook 'diary-list-entries-hook 'diary-include-other-diary-files)
(add-hook 'diary-mark-entries-hook 'diary-mark-included-diary-files)
601 602 603 604 605 606 607 608 609
@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

610
@vindex diary-sexp-entry-symbol
611
  Sexp diary entries allow you to do more than just have complicated
612 613 614 615 616 617
conditions under which a diary entry applies.  Sexp entries should be
preceded by @code{diary-sexp-entry-symbol} (default @samp{%%}) in the
diary file.  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
618
the number of years since the anniversary date into the text of the
619
diary entry.  Thus the @samp{%d} in this diary entry:
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

@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
677 678
and the fancy diary will show @samp{Ed's anniversary} both on December
15 and on December 22.
679 680 681 682

@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
683
integers, or @code{t} (meaning all values).  For example,
684 685 686 687 688 689 690 691 692 693 694 695 696 697 698 699 700 701 702

@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},
703
and an index @var{n}.  The entry appears on the @var{n}th @var{dayname}
704 705 706 707 708 709 710 711
after the first day 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} on or after/before @var{day} of @var{month}; 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,
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

@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))
753
         (day (cadr date)))
754 755 756 757 758 759 760 761 762
      (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
763
@findex diary-lunar-phases
764 765 766 767
@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
@findex diary-chinese-date
@findex diary-coptic-date
@findex diary-ethiopic-date
772 773 774 775
@findex diary-hebrew-date
@findex diary-islamic-date
@findex diary-french-date
@findex diary-mayan-date
776
@findex diary-persian-date
777 778
@table @code
@item %%(diary-sunrise-sunset)
779
Make a diary entry for today's local times of sunrise and sunset.
780
@item %%(diary-lunar-phases)
781 782 783 784 785 786 787
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)
788
Make a diary entry with today's equivalent Julian calendar date.
789 790
@item %%(diary-astro-day-number)
Make a diary entry with today's equivalent astronomical (Julian) day number.
791
@item %%(diary-bahai-date)
792 793 794 795 796 797 798
Make a diary entry with today's equivalent Baha'i calendar date.
@item %%(diary-chinese-date)
Make a diary entry with today's equivalent Chinese calendar date.
@item %%(diary-coptic-date)
Make a diary entry with today's equivalent Coptic calendar date.
@item %%(diary-ethiopic-date)
Make a diary entry with today's equivalent Ethiopic calendar date.
799 800 801
@item %%(diary-french-date)
Make a diary entry with today's equivalent date on the French Revolutionary
calendar.
802 803 804 805
@item %%(diary-hebrew-date)
Make a diary entry with today's equivalent Hebrew calendar date.
@item %%(diary-islamic-date)
Make a diary entry with today's equivalent Islamic calendar date.
806
@item %%(diary-mayan-date)
807 808 809
Make a diary entry with today's equivalent Mayan calendar date.
@item %%(diary-persian-date)
Make a diary entry with today's equivalent Persian calendar date.
810 811 812
@end table

@noindent
813
For example, including the diary entry
814

815
@smallexample
816
&%%(diary-hebrew-date)
817
@end smallexample
818 819 820 821

@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
822 823
diary display, the literal line @samp{&%%(diary-hebrew-date)} appears in
the diary for any date.)
824

825 826
  This function has been used to construct certain standard Hebrew sexp
diary entries:
827 828

@cindex rosh hodesh
829
@findex diary-hebrew-rosh-hodesh
830
@cindex parasha, weekly
831
@findex diary-hebrew-parasha
832
@cindex candle lighting times
833
@findex diary-hebrew-sabbath-candles
834
@cindex omer count
835
@findex diary-hebrew-omer
836
@cindex yahrzeits
837
@findex diary-hebrew-yahrzeit
838
@table @code
839
@item %%(diary-hebrew-rosh-hodesh)
840 841
Make a diary entry that tells the occurrence and ritual announcement of each
new Hebrew month.
842
@item %%(diary-hebrew-parasha)
843
Make a Saturday diary entry that tells the weekly synagogue scripture reading.
844
@item %%(diary-hebrew-sabbath-candles)
845 846
Make a Friday diary entry that tells the @emph{local time} of Sabbath
candle lighting.
847
@item %%(diary-hebrew-omer)
848
Make a diary entry that gives the omer count, when appropriate.
849
@item %%(diary-hebrew-yahrzeit @var{month} @var{day} @var{year}) @var{name}
850 851
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
852 853 854
on the proper Hebrew calendar anniversary and on the day before.  (The
order of the parameters changes according to the calendar date style;
for example in the European style to @var{day}, @var{month}, @var{year}.)
855 856 857 858 859
@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,
860
it returns a value that contains @var{mark}, as described above.
Miles Bader's avatar
Miles Bader committed
861 862 863 864

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