@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,
@section Scrolling in the Calendar
@cindex scrolling in the calendar
- The calendar display scrolls automatically through time when you move out
-of the visible portion. You can also scroll it manually. Imagine that the
-calendar window contains a long strip of paper with the months on it.
-Scrolling it means moving the strip so that new months become visible in
-the window.
+ The calendar display scrolls automatically through time when you
+move out of the visible portion. You can also scroll it manually.
+Imagine that the calendar window contains a long strip of paper with
+the months on it. Scrolling the calendar means moving the strip
+horizontally, so that new months become visible in the window.
@table @kbd
@item C-x <
@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}).
@item g a
-Move to a date specified in astronomical (Julian) day number
+Move to a date specified with an astronomical (Julian) day number
(@code{calendar-goto-astro-day-number}).
@item g h
Move to a date specified in the Hebrew calendar
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
the week, select that day of the week (any occurrence will do) and type
@kbd{i w}. This inserts the day-of-week as a generic date; you can then
type the rest of the diary entry. You can make a monthly diary entry in
-the same fashion. Select the day of the month, use the @kbd{i m}
-command, and type rest of the entry. Similarly, you can insert a yearly
-diary entry with the @kbd{i y} command.
+the same fashion: select the day of the month, use the @kbd{i m}
+command, and type the rest of the entry. Similarly, you can insert a
+yearly diary entry with the @kbd{i y} command.
All of the above commands make marking diary entries by default. To
make a nonmarking diary entry, give a numeric argument to the command.
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.
+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 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