(emacs)Special Diary Entries


Prev: Adding to Diary Up: Diary

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

   In addition to entries based on calendar dates, your diary file can
contain "special 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 special 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
special 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.

   You can make a diary entry entry for a block of dates by setting the
mark at the date at one end of the block, moving point to the date at
the other end of the block, and using the `i b' command.  This command
causes the end of your diary file to be displayed in another window and
the block description to be inserted; you can then type the diary
entry.  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.)

   "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.  It
looks like this:

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

which 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 the these commands make marking diary entries.  If you
want the diary entry to be nonmarking, 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, special diary entries can perform arbitrary
computations to determine when they apply.  *Note Sexp Diary Entries:
(elisp)Sexp Diary Entries.


automatically generated by info2www