@c This is part of the Emacs manual.
@c Copyright (C) 1985, 1986, 1987, 1993, 1994, 1995, 1997, 2000, 2001,
-@c 2005 Free Software Foundation, Inc.
+@c 2002, 2003, 2004, 2005, 2006 Free Software Foundation, Inc.
@c See file emacs.texi for copying conditions.
@node Calendar/Diary, Gnus, Dired, Top
@chapter The Calendar and the Diary
calendar features that are independent of any particular date. To exit
the calendar, type @kbd{q}.
-The basic features of the Calendar/Diary are described here.
-@xref{Advanced Calendar/Diary Usage,,, emacs-xtra, Specialized Emacs
-Features}, for information about more specialized features.
+ This chapter describes the basic calendar features.
+@inforef{Advanced Calendar/Diary Usage,, emacs-xtra}, for information
+about more specialized features.
@menu
* Calendar Motion:: Moving through the calendar; selecting a date.
@section Movement in the Calendar
@cindex moving inside the calendar
- Calendar mode lets you move through the calendar in logical units of
-time such as days, weeks, months, and years. If you move outside the
-three months originally displayed, the calendar display ``scrolls''
-automatically through time to make the selected date visible. Moving to
-a date lets you view its holidays or diary entries, or convert it to other
-calendars; moving longer time periods is also useful simply to scroll the
-calendar.
+ Calendar mode provides commands to move through the calendar in
+logical units of time such as days, weeks, months, and years. If you
+move outside the three months originally displayed, the calendar
+display ``scrolls'' automatically through time to make the selected
+date visible. Moving to a date lets you view its holidays or diary
+entries, or convert it to other calendars; moving by long time periods
+is also useful simply to scroll the calendar.
@menu
* Calendar Unit Motion:: Moving by days, weeks, months, and years.
@findex calendar-forward-year
The commands for motion by months and years work like those for
weeks, but move a larger distance. The month commands @kbd{M-@}} and
-@kbd{M-@{} move forward or backward by an entire month's time. The
-year commands @kbd{C-x ]} and @w{@kbd{C-x [}} move forward or backward a
+@kbd{M-@{} move forward or backward by an entire month. The year
+commands @kbd{C-x ]} and @w{@kbd{C-x [}} move forward or backward a
whole year.
The easiest way to remember these commands is to consider months and
-years analogous to paragraphs and pages of text, respectively. But the
-commands themselves are not quite analogous. The ordinary Emacs paragraph
-commands move to the beginning or end of a paragraph, whereas these month
-and year commands move by an entire month or an entire year, which usually
-involves skipping across the end of a month or year.
+years analogous to paragraphs and pages of text, respectively. But
+the commands themselves are not quite analogous. The ordinary Emacs
+paragraph commands move to the beginning or end of a paragraph,
+whereas these month and year commands move by an entire month or an
+entire year, keeping the same date within the month or year.
All these commands accept a numeric argument as a repeat count.
For convenience, the digit keys and the minus sign specify numeric
horizontally, so that new months become visible in the window.
@table @kbd
-@item C-x <
+@item <
Scroll calendar one month forward (@code{scroll-calendar-left}).
-@item C-x >
+@item >
Scroll calendar one month backward (@code{scroll-calendar-right}).
@item C-v
@itemx @key{NEXT}
(@code{scroll-calendar-right-three-months}).
@end table
-@kindex C-x < @r{(Calendar mode)}
+@kindex < @r{(Calendar mode)}
@findex scroll-calendar-left
-@kindex C-x > @r{(Calendar mode)}
+@kindex > @r{(Calendar mode)}
@findex scroll-calendar-right
The most basic calendar scroll commands scroll by one month at a
time. This means that there are two months of overlap between the
-display before the command and the display after. @kbd{C-x <} scrolls
+display before the command and the display after. @kbd{<} scrolls
the calendar contents one month to the left; that is, it moves the
-display forward in time. @kbd{C-x >} scrolls the contents to the
+display forward in time. @kbd{>} scrolls the contents to the
right, which moves backwards in time.
@kindex C-v @r{(Calendar mode)}
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
-selected date. The number of days remaining does not include that
+numbers in the echo area. The count of days elapsed includes the
+selected date. The count of days remaining does not include that
date.
@kindex C-c C-l @r{(Calendar mode)}
click on that date with @kbd{Mouse-2} and then choose @kbd{Holidays}
from the menu that appears. Either way, this displays the holidays for
that date, in the echo area if they fit there, otherwise in a separate
-window. If the variable @code{view-calendar-holidays-initially} is
-non-@code{nil}, holidays are displayed when the calendar is created.
+window.
@kindex x @r{(Calendar mode)}
@findex mark-calendar-holidays
To view the distribution of holidays for all the dates shown in the
calendar, use the @kbd{x} command. This displays the dates that are
holidays in a different face (or places a @samp{*} after these dates, if
-display with multiple faces is not available). @xref{Calendar
-Customizing,, calendar-holiday-marker, emacs-xtra, Specialized Emacs
-Features}. The command applies both to the currently visible months and
-to other months that subsequently become visible by scrolling. To turn
-marking off and erase the current marks, type @kbd{u}, which also erases
-any diary marks (@pxref{Diary}). If the variable
-@code{mark-holidays-in-calendar} is non-@code{nil}, holidays are marked
-in the calendar when it is created (or recomputed).
-
+display with multiple faces is not available). @inforef{Calendar
+Customizing, calendar-holiday-marker, emacs-xtra}. The command applies
+both to the currently visible months and to other months that
+subsequently become visible by scrolling. To turn marking off and erase
+the current marks, type @kbd{u}, which also erases any diary marks
+(@pxref{Diary}). If the variable @code{mark-holidays-in-calendar} is
+non-@code{nil}, creating or updating the calendar marks holidays
+automatically.
@kindex a @r{(Calendar mode)}
@findex list-calendar-holidays
@findex holidays
The command @kbd{M-x holidays} displays the list of holidays for the
current month and the preceding and succeeding months; this works even
-if you don't have a calendar window. If you want the list of holidays
-centered around a different month, use @kbd{C-u M-x holidays}, which
-prompts for the month and year.
+if you don't have a calendar window. If the variable
+@code{view-calendar-holidays-initially} is non-@code{nil}, creating
+the calendar displays holidays in this way. If you want the list of
+holidays centered around a different month, use @kbd{C-u M-x
+holidays}, which prompts for the month and year.
The holidays known to Emacs include United States holidays and the
major Christian, Jewish, and Islamic holidays; also the solstices and
days, the next five have 30 days, and the last has 29 in ordinary years
and 30 in leap years. Leap years occur in a complicated pattern every
four or five years.
+The calendar implemented here is the arithmetical Persian calendar
+championed by Birashk, based on a 2,820-year cycle. It differs from
+the astronomical Persian calendar, which is based on astronomical
+events. As of this writing the first future discrepancy is projected
+to occur on March 20, 2025. It is currently not clear what the
+official calendar of Iran will be that far into the future.
@cindex Chinese calendar
The Chinese calendar is a complicated system of lunar months arranged
The name of the diary file is specified by the variable
@code{diary-file}; @file{~/diary} is the default. A sample diary file
-is:
+is (note that the file format is essentially the same as that used by
+the external shell utility @samp{calendar}):
@example
12/22/1988 Twentieth wedding anniversary!!
that fall on that date. If you specify a numeric argument with @kbd{d},
it shows all the diary entries for that many successive days. Thus,
@kbd{2 d} displays all the entries for the selected date and for the
-following day. If the variable @code{view-diary-entries-initially} is
-non-@code{nil}, the diary entries for the current date are displayed
-when the calendar is created (provided the current date is visible).
+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 entries} from
-the menu that appears.
+the menu that appears. If the variable
+@code{view-diary-entries-initially} is non-@code{nil}, creating the
+calendar lists the diary entries for the current date (provided the
+current date is visible).
@kindex m @r{(Calendar mode)}
@findex mark-diary-entries
To get a broader view of which days are mentioned in the diary, use
the @kbd{m} command. This displays the dates that have diary entries in
a different face (or places a @samp{+} after these dates, if display
-with multiple faces is not available). @xref{Calendar Customizing,,
-diary-entry-marker, emacs-xtra, Specialized Emacs Features}. The
-command applies both to the currently visible months and to other months
-that subsequently become visible by scrolling. To turn marking off and
-erase the current marks, type @kbd{u}, which also turns off holiday
-marks (@pxref{Holidays}). If the variable
-@code{mark-diary-entries-in-calendar} is non-@code{nil}, diary dates are
-marked in the calendar when it is created (or recomputed).
+with multiple faces is not available). @inforef{Calendar Customizing,
+diary-entry-marker, emacs-xtra}. The command applies both to the
+currently visible months and to other months that subsequently become
+visible by scrolling. To turn marking off and erase the current marks,
+type @kbd{u}, which also turns off holiday marks (@pxref{Holidays}).
+If the variable @code{mark-diary-entries-in-calendar} is
+non-@code{nil}, creating or updating the calendar marks diary dates
+automatically.
@kindex s @r{(Calendar mode)}
@findex show-all-diary-entries
the @kbd{s} command.
Display of selected diary entries uses the selective display feature
-to hide entries that don't apply.
-
- The diary buffer as you see it is an illusion, so simply printing the
-buffer does not print what you see on your screen. There is a special
-command to print hard copy of the diary buffer @emph{as it appears};
-this command is @kbd{M-x print-diary-entries}. It sends the data
-directly to the printer. You can customize it like @code{lpr-region}
-(@pxref{Hardcopy}).
+to hide entries that don't apply. The diary buffer as you see it is
+an illusion, so simply printing the buffer does not print what you see
+on your screen. There is a special command to print hard copy of the
+diary buffer @emph{as it appears}; this command is @kbd{M-x
+print-diary-entries}. It sends the data directly to the printer. You
+can customize it like @code{lpr-region} (@pxref{Printing}).
@findex diary
The command @kbd{M-x diary} displays the diary entries for the current
date, independently of the calendar display, and optionally for the next
few days as well; the variable @code{number-of-diary-entries} specifies
-how many days to include. @xref{Advanced Calendar/Diary Usage,
-Customizing the Calendar and Diary,, emacs-xtra, Specialized Emacs
-Features}.
+how many days to include. @inforef{Diary Customizing,, emacs-xtra}.
If you put @code{(diary)} in your @file{.emacs} file, this
automatically displays a window with the day's diary entries, when you
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, emacs-xtra, Specialized
-Emacs Features}.
+@inforef{Sexp Diary Entries,, emacs-xtra}.
@node Appointments
@section Appointments
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. In addition, if @code{appt-display-mode-line} is non-@code{nil},
-Emacs displays the number of minutes to the appointment on the mode
-line.
+@code{appt-audible} is non-@code{nil}, the warning includes an audible
+reminder. In addition, if @code{appt-display-mode-line} is
+non-@code{nil}, Emacs displays the number of minutes to the
+appointment on the mode line.
@vindex appt-display-duration
@vindex appt-disp-window-function
respectively.
@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. With no argument, it toggles.
+ To enable appointment notification, use the command @kbd{M-x
+appt-activate}. With a positive argument, it enables notification;
+with a negative argument, it disables notification; with no argument,
+it toggles. Enabling notification also 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.
For example, suppose the diary file contains these lines:
@vindex appt-message-warning-time
@noindent
-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}.
+Then on Mondays, you will be reminded at around 9:20am about your
+coffee break and at around 11:50am about lunch. The variable
+@code{appt-message-warning-time} specifies how many minutes in advance
+to warn you; its default value is 12 (12 minutes).
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
of lines if they are to be recognized.
@vindex appt-display-diary
- 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.
+ Emacs updates the appointments list from the diary file
+automatically just after midnight. You can force an update at any
+time by re-enabling appointment notification. 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
2445---Internet Calendaring and Scheduling Core Object Specification
(iCalendar)'' (as well as the earlier vCalendar format).
- 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.
+ 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. This feature is a work in progress, so the
+commands may evolve in future.
@findex icalendar-import-buffer
The command @code{icalendar-import-buffer} extracts
@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,,, emacs-xtra, Specialized Emacs Features}.
+to the main diary file, if these are different files. @inforef{Fancy Diary
+Display,, emacs-xtra}.
@findex icalendar-export-file, icalendar-export-region
Use @code{icalendar-export-file} to interactively export an entire
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
@cindex daylight savings time
@cindex timeclock
The timeclock feature adds up time intervals, so you can (for
-instance) keep track of how much time you spend working.
+instance) keep track of how much time you spend working on particular
+projects.
@findex timeclock-in
@findex timeclock-out
@code{t}, or invoke the @kbd{M-x timeclock-modeline-display} command.
@vindex timeclock-ask-before-exiting
- Terminating the current Emacs session might or might not mean that you
-have stopped working on the project and, by default, Emacs queries this.
-You can, however, set the value of the variable
+ Terminating the current Emacs session might or might not mean that
+you have stopped working on the project and, by default, Emacs asks
+you. You can, however, set the value of the variable
@code{timeclock-ask-before-exiting} to @code{nil} (via @kbd{M-x
-customize}) to avoid this behaviour; then, only an explicit @kbd{M-x
+customize}) to avoid the question; then, only an explicit @kbd{M-x
timeclock-out} or @kbd{M-x timeclock-change} will tell Emacs that the
current interval is over.