(lemacs.info)Special Diary Entries


Prev: Format of Diary File Up: Diary

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

   In addition to entries based on calendar dates, your diary file can
contain entries for regularly occurring events such as anniversaries.
These entries are based on expressions (sexps) that Emacs evaluates as
it scans the diary file.  Such an entry is indicated by `%%' at the
beginning (preceded by `&' for a nonmarking entry), followed by a sexp
in parentheses.  Calendar mode offers commands to make it easier to put
some of these special entries in your diary.

`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 effect of `i a' is to add a `diary-anniversary' sexp to your
diary file.  You can also add one manually, for instance:

     %%(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 sexp requires a
beginning year is that advanced diary functions can use it to calculate
the number of elapsed years (Note: Sexp Diary Entries.).

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

   You can specify cyclic diary entries that repeat after a fixed
interval of days.  Move point to the starting date and use the `i c'
command.  After you specify the length of interval, this command
displays the end of your diary file in another window and inserts the
cyclic event description; you can then type the rest of the diary entry.

   The sexp corresponding to the `i c' command looks like:

     %%(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 `&'.

   One sophisticated kind of sexp, a floating diary entry, has no
corresponding command.  The 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 on Unix systems.

   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.

   The sexp feature of the diary allows you to specify diary entries
based on any Emacs Lisp expression.  You can use the library of built-in
functions or you can write your own functions.  The built-in functions
include the ones shown in this section, plus a few others (Note: Sexp
Diary Entries.).

   The generality of sexps lets you specify any diary entry that you can
describe algorithmically.  Suppose you get paid on the 21st of the month
if it is a weekday, and to the Friday before if the 21st is on a
weekend.  The diary entry

     &%%(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

to just those dates.  This example illustrates how the sexp can depend
on the variable `date'; this variable is a list (MONTH DAY YEAR) that
gives the Gregorian date for which the diary entries are being found.
If the value of the sexp is `t', the entry applies to that date.  If
the sexp evaluates to `nil', the entry does *not* apply to that date.


automatically generated by info2www