GNU Info

(emacs)Special Diary Entries

---

Prev: Adding to Diary Up: Diary

---

Enter node , (file) or (file)node

Special Diary Entries
---------------------

   In addition to entries based on calendar dates, the diary file can
contain "sexp entries" for regular events such as anniversaries.  These
entries are based on Lisp expressions (sexps) that Emacs evaluates as
it scans the diary file.  Instead of a date, a sexp entry contains `%%'
followed by a Lisp expression which must begin and end with
parentheses.  The Lisp expression determines which dates the entry
applies to.

   Calendar mode provides commands to insert certain commonly used sexp
entries:

`i a'
     Add an anniversary diary entry for the selected date
     (`insert-anniversary-diary-entry').

`i b'
     Add a block diary entry for the current region
     (`insert-block-diary-entry').

`i c'
     Add a cyclic diary entry starting at the date
     (`insert-cyclic-diary-entry').

   If you want to make a diary entry that applies to the anniversary of
a specific date, move point to that date and use the `i a' command.
This displays the end of your diary file in another window and inserts
the anniversary description; you can then type the rest of the diary
entry.  The entry looks like this:

     %%(diary-anniversary 10 31 1948) Arthur's birthday

This entry applies to October 31 in any year after 1948; `10 31 1948'
specifies the date.  (If you are using the European calendar style, the
month and day are interchanged.)  The reason this expression requires a
beginning year is that advanced diary functions can use it to calculate
the number of elapsed years.

   A "block" diary entry applies to a specified range of consecutive
dates.  Here is a block diary entry that applies to all dates from June
24, 1990 through July 10, 1990:

     %%(diary-block 6 24 1990 7 10 1990) Vacation

The `6 24 1990' indicates the starting date and the `7 10 1990'
indicates the stopping date.  (Again, if you are using the European
calendar style, the month and day are interchanged.)

   To insert a block entry, place point and the mark on the two dates
that begin and end the range, and type `i b'.  This command displays
the end of your diary file in another window and inserts the block
description; you can then type the diary entry.

   "Cyclic" diary entries repeat after a fixed interval of days.  To
create one, select the starting date and use the `i c' command.  The
command prompts for the length of interval, then inserts the entry,
which looks like this:

     %%(diary-cyclic 50 3 1 1990) Renew medication

This entry applies to March 1, 1990 and every 50th day following; `3 1
1990' specifies the starting date.  (If you are using the European
calendar style, the month and day are interchanged.)

   All three of these commands make marking diary entries.  To insert a
nonmarking entry, give a numeric argument to the command.  For example,
`C-u i a' makes a nonmarking anniversary diary entry.

   Marking sexp diary entries in the calendar is _extremely_
time-consuming, since every date visible in the calendar window must be
individually checked.  So it's a good idea to make sexp diary entries
nonmarking (with `&') when possible.

   Another sophisticated kind of sexp entry, a "floating" diary entry,
specifies a regularly occurring event by offsets specified in days,
weeks, and months.  It is comparable to a crontab entry interpreted by
the `cron' utility.  Here is a nonmarking, floating diary entry that
applies to the last Thursday in November:

     &%%(diary-float 11 4 -1) American Thanksgiving

The 11 specifies November (the eleventh month), the 4 specifies Thursday
(the fourth day of the week, where Sunday is numbered zero), and the -1
specifies "last" (1 would mean "first," 2 would mean "second," -2 would
mean "second-to-last," and so on).  The month can be a single month or
a list of months.  Thus you could change the 11 above to `'(1 2 3)' and
have the entry apply to the last Thursday of January, February, and
March.  If the month is `t', the entry applies to all months of the
year.

   Most generally, sexp diary entries can perform arbitrary
computations to determine when they apply.  *Note Sexp Diary Entries:
(elisp)Sexp Diary Entries.