Your diary file is a file that records events associated with
particular dates. The name of the diary file is specified by the variable
diary-file; `~/diary' is the default. You can use the same file
for the calendar utility program since the formats are consistent.
Each entry in the file describes one event and consists of one or more lines. It always begins with a date specification at the left margin. The rest of the entry is simply text to describe the event. If the entry has more than one line, then the lines after the first must begin with whitespace to indicate they continue a previous entry.
Dates can be given numerically, as in `month/day' or `month/day/year'. This must be followed by a nondigit. In the date itself, month and day are numbers of one or two digits. year is a number and may be abbreviated to the last two digits; that is, you can use `11/12/1989' or `11/12/89'.
A date may be generic, or partially unspecified. Then the entry applies to all dates that match the specification. If the date does not contain a year, it is generic and applies to any year. Alternatively, month, day, or year can be a `*'; this matches any month, day, or year, respectively. Thus, a diary entry `3/*/*' will match any day in March of any year.
Dates can also have the form `monthname day' or `monthname day, year', where the month's name can be spelled in full or abbreviated to three characters (with or without a period). Case is not significant. If the date does not contain a year, it is generic and applies to any year. Also, monthname, day, or year can be a `*' which matches any month, day, or year, respectively.
If you prefer the European style of writing dates--in which the day comes
before the month--type M-x european-calendar while in the calendar or
set the variable european-calendar-style to t in your
`.emacs' file before the calendar or diary command. This causes
all dates in the diary to be interpreted in the European manner, and any dates
displayed on the terminal will be shown in the European form. (Note that there
is no comma after the monthname in the European style.)
To revert to the (default) American style of writing dates, type M-x american-calendar while in the calendar.
Dates can also have the form dayname. The day name can be spelled out in full (say, `Tuesday') or it can be abbreviated to three characters (with or without a period); it need not be capitalized. This form of date is generic and applies to any date on that day of the week.
You may want entries that are not marked in the calendar window; this is especially true of dayname style entries or entries such as `12/*', each of which causes many marks in the calendar. You can make diary entries nonmarking by preceding them with an ampersand (`&'). Such entries are not marked on dates in the calendar window, but will appear in a diary window.
Lines that do not begin with valid dates and do not continue a preceding entry are ignored.
Here are some sample diary entries:
12/22/1988 Twentieth wedding anniversary!!
&1/1. Happy New Year!
10/22 Ruth's birthday.
* 21, *: Payday
Tuesday--weekly meeting with grad students at 10am
Supowit, Shen, Bitner, and Kapoor to attend.
1/13/89 Friday the thirteenth!!
&thu 4pm squash game with Lloyd.
mar 16 Dad's birthday
April 15, 1989 Income tax due.
&* 15 time cards due.
If the first line of a diary entry consists only of the date or day name with no following blanks or punctuation, then that line is not displayed in the diary window; only the continuation lines are shown. For example:
02/11/1989
Bill B. visits Princeton today
2pm Cognitive Studies Committee meeting
2:30-5:30 Liz at Lawrenceville
4:00pm Dentist appt
7:30pm Dinner at George's
8:00-10:00pm concert
will appear in the diary window without the date line at the beginning. This facility allows the diary window to look neater when a single day's entries are displayed, but can cause confusion if you ask for more than one day's entries to be displayed.
You can edit the diary entries as they appear in the window, but it is
important to remember that the buffer displayed contains the entire
diary file, with portions of it concealed from view. This means, for
instance, that the C-f (forward-char) command can put the cursor
at what appears to be the end of the line, but what is in reality the
middle of some concealed line. Be careful when editing the diary
entries! Inserting additional lines or adding/deleting characters in the
middle of a visible line will not cause problems; watch out for C-e
(end-of-line), however; it may put you at the end of a concealed
line far from where the cursor appears to be! Before editing the diary, it
is best to display the entire file with s
(show-all-diary-entries).
While in the calendar, there are several commands to help you in making entries to your diary.
insert-diary-entry).
insert-weekly-diary-entry).
insert-monthly-diary-entry).
insert-yearly-diary-entry).
You can make a diary entry for a specific date by moving point to that date in the calendar window and using the C-c d command. This command causes the end of your diary file to be displayed in another window and the date to be inserted; you can then type the diary entry.
If you want to make a diary entry that will apply to a specific day of the week, move point to that day of the week (any occurrence will do) and use the C-c w command. The end of your file will be displayed in another window and the name of the day of the week will be inserted; you can then type the diary entry.
You make a monthly diary entry in the same fashion. Move point to the day of the month, use the C-c m command, and type the diary entry. Similarly, you make a yearly diary entry with the C-c y command.
All of the above commands make marking diary entries. If you want the diary entry to be nonmarking, give a prefix argument to the command. For example, C-u C-c w will make a nonmarking, weekly diary entry.
If you modify the diary, be sure to write the file before exiting from the calendar.