(lemacs.info)Format of Diary File


Next: Special Diary Entries Prev: Diary Commands Up: Diary

The Diary File
--------------

   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 its formats are a subset
of the ones allowed by the Emacs Calendar.

   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.

   Here are some sample diary entries, illustrating different ways of
formatting a date.  The examples all show dates in American order
(month, day, year), but Calendar mode offers (day, month, year)
ordering too.

     4/20/93  Switch-over to new tabulation system
     apr. 25  Start tabulating annual results
     4/30  Results for April are due
     */25  Monthly cycle finishes
     Friday  Don't leave without backing up files

   The first entry appears only once, on April 20, 1993.  The second and
third appear every year on the specified dates, and the fourth uses a
wildcard (asterisk) for the month, so it appears on the 25th of every
month.  The final entry appears every week on Friday.

   You can also use just numbers to express a date, 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/*/*' matches
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 mode
interprets all dates in the diary in the European manner, and also uses
European style for displaying diary dates.  (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'.

   You can use the name of a day of the week as a generic date which
applies to any date falling on that day of the week.  You can abbreviate
the day of the week to three letters (with or without a period) or spell
it in full; it need not be capitalized.

   You can inhibit the marking of certain diary entries in the calendar
window; to do this, insert an ampersand (`&') at the beginning of the
entry, before the date.  This has no effect on display of the entry in
the diary window; it affects only marks on dates in the calendar
window.  Nonmarking entries are especially useful for generic entries
that would otherwise mark many different dates.

   Lines that do not begin with valid dates and do not continue a
preceding entry are ignored.

   If the first line of a diary entry consists only of the date or day
name with no following blanks or punctuation, then the diary window
display doesn't include that line; only the continuation lines appear.
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

appears in the diary window without the date line at the beginning.
This style of entry looks neater when you display just a single day's
entries, but can cause confusion if you ask for more than one day's
entries.

   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 point 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 cannot 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 point 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.

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

`i w'
     Add a diary entry for the selected day of the week
     (`insert-weekly-diary-entry').

`i m'
     Add a diary entry for the selected day of the month
     (`insert-monthly-diary-entry').

`i y'
     Add a diary entry for the selected day of the year
     (`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 `i d' command.  This
command displays the end of your diary file in another window and
inserts the date; you can then type the rest of the diary entry.

   If you want to make a diary entry that applies to a specific day of
the week, move point to that day of the week (any occurrence will do)
and use the `i w' command.  This displays the end of your diary file in
another window and inserts the day-of-week as a generic date; you can
then type the rest of the diary entry.

   You make a monthly diary entry in the same fashion.  Move point to
the day of the month, use the `i m' command, and type the diary entry.
Similarly, you make a yearly diary entry with the `i 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 i w' makes a nonmarking, weekly diary entry.

   If you modify the diary, be sure to write the file before exiting
from the calendar.


automatically generated by info2www