@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
@item S
Display times of sunrise and sunset for the selected date
(@code{calendar-sunrise-sunset}).
-@item Mouse-2 Sunrise/Sunset
+@item Mouse-2 Sunrise/sunset
Display times of sunrise and sunset for the date you click on.
@item M-x sunrise-sunset
Display times of sunrise and sunset for today's date.
Within the calendar, to display the @emph{local times} of sunrise and
sunset in the echo area, move point to the date you want, and type
@kbd{S}. Alternatively, click @kbd{Mouse-2} on the date, then choose
-@kbd{Sunrise/Sunset} from the menu that appears. The command @kbd{M-x
+@samp{Sunrise/sunset} from the menu that appears. The command @kbd{M-x
sunrise-sunset} is available outside the calendar to display this
information for today's date or a specified date. To specify a date
other than today, use @kbd{C-u M-x sunrise-sunset}, which prompts for
in various other calendar systems:
@table @kbd
-@item Mouse-2 Other Calendars
+@item Mouse-2 Other calendars
Display the date that you click on, expressed in various other calendars.
@kindex p @r{(Calendar mode)}
@findex calendar-print-iso-date
If you are using X, the easiest way to translate a date into other
calendars is to click on it with @kbd{Mouse-2}, then choose @kbd{Other
-Calendars} from the menu that appears. This displays the equivalent
+calendars} from the menu that appears. This displays the equivalent
forms of the date in all the calendars Emacs understands, in the form of
a menu. (Choosing an alternative from this menu doesn't actually do
anything---the menu is used only for display.)
- Put point on the desired date of the Gregorian calendar, then type the
-appropriate keys. The @kbd{p} is a mnemonic for ``print'' since Emacs
-``prints'' the equivalent date in the echo area.
+ Otherwise, move point to the date you want to convert, then type the
+appropriate command starting with @kbd{p} from the table above. The
+prefix @kbd{p} is a mnemonic for ``print,'' since Emacs ``prints'' the
+equivalent date in the echo area.
@node From Other Calendar
@subsection Converting From Other Calendars
@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
following day.
Another way to display the diary entries for a date is to click
-@kbd{Mouse-2} on the date, and then choose @kbd{Diary} from the menu
-that appears.
+@kbd{Mouse-2} on the date, and then choose @kbd{Diary entries} from
+the menu that appears.
@kindex m @r{(Calendar mode)}
@findex mark-diary-entries
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-extract-ical-from-buffer
+ The command @code{icalendar-extract-ical-from-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-extract-ical-from-buffer)
+@end example
+
+@findex icalendar-import-file
+ The command @code{icalendar-import-file} imports an iCalendar file.
+@strong{Caution:} the contents of the target diary file are
+@emph{deleted} by default! It is highly recommended to use a dedicated
+diary file for importing. 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 diary. @xref{Fancy Diary Display,,, elisp, The Emacs Lisp
+Reference Manual}.
+
+@findex icalendar-convert-diary-to-ical
+ The command @code{icalendar-convert-diary-to-ical} exports an Emacs
+diary file to iCalendar format. @strong{Caution:} the contents of the
+target file are @emph{deleted} by default!
+
@node Daylight Savings
@section Daylight Savings Time
@cindex @file{.timelog} file
@vindex timeclock-file
@findex timeclock-reread-log
- The timeclock functions work by accumulating the data on a file
+ The timeclock functions work by accumulating the data in a file
called @file{.timelog} in your home directory. (On MS-DOS, this file
is called @file{_timelog}, since an initial period is not allowed in
file names on MS-DOS.) You can specify a different name for this file
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
HCoop / bpt / emacs.git / blobdiff