@c This is part of the Emacs manual.
-@c Copyright (C) 1985,86,87,93,94,95,1997,2000 Free Software Foundation, Inc.
+@c Copyright (C) 1985,86,87,93,94,95,1997,2000,2001 Free Software Foundation, Inc.
@c See file emacs.texi for copying conditions.
@node Calendar/Diary, Gnus, Dired, Top
@chapter The Calendar and the Diary
* Other Calendars:: Converting dates to other calendar systems.
* Diary:: Displaying events from your diary.
* Appointments:: Reminders when it's time to do something.
+* iCalendar:: Converting diary events to/from iCalendar format.
* Daylight Savings:: How to specify when daylight savings time is active.
* Time Intervals:: Keeping track of time intervals.
@end menu
@table @kbd
@item g d
Move point to specified date (@code{calendar-goto-date}).
+@item g D
+Move point to specified day of year (@code{calendar-goto-day-of-year}).
@item o
Center calendar around specified month (@code{calendar-other-month}).
@item .
dates from the beginning of the current era, you must type the year in its
entirety; that is, type @samp{1990}, not @samp{90}.
+@kindex g D @r{(Calendar mode)}
+@findex calendar-goto-day-of-year
+ @kbd{g D} (@code{calendar-goto-day-of-year}) prompts for a year and
+day number, and moves to that date. Negative day numbers count backward
+from the end of the year.
+
@kindex o @r{(Calendar mode)}
@findex calendar-other-month
@kbd{o} (@code{calendar-other-month}) prompts for a month and year,
@kindex M-= @r{(Calendar mode)}
@findex calendar-count-days-region
To determine the number of days in the region, type @kbd{M-=}
-(@code{calendar-count-days-region}). The numbers of days printed is
+(@code{calendar-count-days-region}). The numbers of days shown is
@emph{inclusive}; that is, it includes the days specified by mark and
point.
@kindex p d @r{(Calendar mode)}
@cindex day of year
@findex calendar-print-day-of-year
- To print the number of days elapsed since the start of the year, or
+ To display the number of days elapsed since the start of the year, or
the number of days remaining in the year, type the @kbd{p d} command
(@code{calendar-print-day-of-year}). This displays both of those
numbers in the echo area. The number of days elapsed includes the
@kindex g @var{char} @r{(Calendar mode)}
@findex calendar-goto-iso-date
+@findex calendar-goto-iso-week
@findex calendar-goto-julian-date
@findex calendar-goto-astro-day-number
@findex calendar-goto-hebrew-date
@item g c
Move to a date specified in the ISO commercial calendar
(@code{calendar-goto-iso-date}).
+@item g w
+Move to a week specified in the ISO commercial calendar
+(@code{calendar-goto-iso-week}).
@item g j
Move to a date specified in the Julian calendar
(@code{calendar-goto-julian-date}).
Dates can also have the form @samp{@var{monthname} @var{day}} or
@samp{@var{monthname} @var{day}, @var{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.
+be spelled in full or abbreviated (with or without a period). The
+preferred abbreviations can be controlled using the variables
+@code{calendar-abbrev-length}, @code{calendar-month-abbrev-array}, and
+@code{calendar-day-abbrev-array}. The default is to use the first three
+letters of a name as its abbreviation. Case is not significant.
A date may be @dfn{generic}; that is, partially unspecified. Then the
entry applies to all dates that match the specification. If the date
Thursday of January, February, and March. If the month is @code{t}, the
entry applies to all months of the year.@refill
- Most generally, sexp diary entries can perform arbitrary
-computations to determine when they apply. @xref{Sexp Diary Entries,,
-Sexp Diary Entries, elisp, The Emacs Lisp Reference Manual}.
+ Each of the standard sexp diary entries takes an optional parameter
+specifying the name of a face or a single-character string to use when
+marking the entry in the calendar. Most generally, sexp diary entries
+can perform arbitrary computations to determine when they apply.
+@xref{Sexp Diary Entries,, Sexp Diary Entries, elisp, The Emacs Lisp
+Reference Manual}.
@node Appointments
@section Appointments
@cindex appointment notification
+@vindex appt-display-format
+@vindex appt-audible
If you have a diary entry for an appointment, and that diary entry
begins with a recognizable time of day, Emacs can warn you several
minutes beforehand that that appointment is pending. Emacs alerts you
-to the appointment by displaying a message in the mode line.
-
-@vindex diary-hook
-@findex appt-make-list
- To enable appointment notification, you must enable the time display
-feature of Emacs, @kbd{M-x display-time} (@pxref{Mode Line}). You must
-also add the function @code{appt-make-list} to the
-@code{diary-hook}, like this:
-
-@example
-(add-hook 'diary-hook 'appt-make-list)
-@end example
-
-@noindent
-Adding this text to your @file{.emacs} file does the whole job:
-
-@example
-(display-time)
-(add-hook 'diary-hook 'appt-make-list)
-(diary 0)
-@end example
-
- With these preparations done, when you display the diary (either with
-the @kbd{d} command in the calendar window or with the @kbd{M-x diary}
-command), it sets up an appointment list of all the diary entries found
-with recognizable times of day, and reminds you just before each of
-them.
+to the appointment by displaying a message in your chosen format, as
+specified by the variable @code{appt-display-format}. If the value
+of @code{appt-audible} is non-@code{nil}, an audible reminder is also given.
+
+@findex appt-activate
+ To enable appointment notification, call the function
+@code{appt-activate} with a positive argument. This sets up an
+appointment list for today from the diary file, giving all diary entries
+found with recognizable times of day, and reminds you just before each
+of them. Calling @code{appt-activate} with a negative argument disables
+the appointment package.
For example, suppose the diary file contains these lines:
@example
Monday
9:30am Coffee break
- 12:00pm Lunch
+ 12:00pm Lunch
@end example
+@vindex appt-message-warning-time
@noindent
-Then on Mondays, after you have displayed the diary, you will be
-reminded at 9:20am about your coffee break and at 11:50am about lunch.
+Then on Mondays, you will be reminded at around 9:20am about your coffee
+break and at around 11:50am about lunch. How many minutes in advance you
+are first warned is determined by the value of
+@code{appt-message-warning-time}.
You can write times in am/pm style (with @samp{12:00am} standing
for midnight and @samp{12:00pm} standing for noon), or 24-hour
European/military style. You need not be consistent; your diary file
-can have a mixture of the two styles.
+can have a mixture of the two styles. Times must be at the beginning
+of lines if they are to be recognized.
@vindex appt-display-diary
- Emacs updates the appointments list automatically just after
-midnight. This also displays the next day's diary entries in the diary
-buffer, unless you set @code{appt-display-diary} to @code{nil}.
+ Emacs updates the appointments list from the diary file automatically
+just after midnight. An update can be forced at any time by
+re-activating the appointment package. Both these actions also display
+the day's diary buffer, unless you set @code{appt-display-diary} to
+@code{nil}. The appointments list is also updated whenever the
+diary file is saved.
@findex appt-add
@findex appt-delete
list without affecting your diary file. You delete entries from the
appointment list with @kbd{M-x appt-delete}.
-@vindex appt-issue-message
- You can turn off the appointment notification feature at any time by
-setting @code{appt-issue-message} to @code{nil}.
+@node iCalendar
+@section iCalendar
+@cindex iCalendar support
+
+ The icalendar package aims at providing an implementation of the
+iCalendar standard, as defined in ``RFC 2445 -- Internet Calendaring and
+Scheduling Core Object Specification (iCalendar)''. It provides a means
+for importing iCalendar (and the earlier vCalendar format) data into
+Emacs diary files and vice versa.
+
+ Importing works for ``ordinary'' (i.e. non-recurring) events, but (at
+present) may not work correctly (if at all) for recurring events.
+Exporting of diary files into iCalendar files should work correctly for
+most diary entries. Please note that @file{icalendar.el} is work in
+progress, so usage may evolve in future.
+
+ To activate the package, use @code{(require 'icalendar)}.
+
+@findex icalendar-import-buffer
+ The command @code{icalendar-import-buffer} extracts
+iCalendar data from the current buffer and adds it to your (default)
+diary file. This function is also suitable for automatic extraction of
+iCalendar data; for example with the Rmail mail client one could use:
+
+@example
+(add-hook 'rmail-show-message-hook 'icalendar-import-buffer)
+@end example
+
+@findex icalendar-import-file
+ The command @code{icalendar-import-file} imports an iCalendar file
+and adds the results to an Emacs diary file. For example:
+
+@example
+(icalendar-import-file "/here/is/calendar.ics" "/there/goes/ical-diary")
+@end example
+
+@noindent
+You can use an @code{#include} directive to add the import file contents
+to the main diary file, if these are distinct. @xref{Fancy Diary
+Display,,, elisp, The Emacs Lisp Reference Manual}.
+
+@findex icalendar-export-file, icalendar-export-region
+ Use @code{icalendar-export-file} to interactively export an entire
+Emacs diary file to iCalendar format. To export only a part of a diary
+file, mark the relevant area, and call @code{icalendar-export-region}.
+In both cases the result is appended to the target file.
+
@node Daylight Savings
@section Daylight Savings Time
timeclock's customizable variables, you should run the command
@kbd{M-x timeclock-reread-log} to update the data in Emacs from the
file.
+
+@ignore
+ arch-tag: 4531ef09-9df3-449d-9c52-2b5a4a337f92
+@end ignore