@c This is part of the Emacs manual.
-@c Copyright (C) 1985, 86, 87, 93, 94, 95, 1997 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
@findex calendar
Emacs provides the functions of a desk calendar, with a diary of
-planned or past events. To enter the calendar, type @kbd{M-x calendar};
-this displays a three-month calendar centered on the current month, with
-point on the current date. With a numeric argument, as in @kbd{C-u M-x
-calendar}, it prompts you for the month and year to be the center of the
-three-month calendar. The calendar uses its own buffer, whose major
-mode is Calendar mode.
+planned or past events. It also has facilities for managing your
+appointments, and keeping track of how much time you spend working on
+certain projects.
+
+ To enter the calendar, type @kbd{M-x calendar}; this displays a
+three-month calendar centered on the current month, with point on the
+current date. With a numeric argument, as in @kbd{C-u M-x calendar}, it
+prompts you for the month and year to be the center of the three-month
+calendar. The calendar uses its own buffer, whose major mode is
+Calendar mode.
@kbd{Mouse-2} in the calendar brings up a menu of operations on a
particular date; @kbd{C-Mouse-3} brings up a menu of commonly used
* Diary:: Displaying events from your diary.
* Appointments:: Reminders when it's time to do something.
* Daylight Savings:: How to specify when daylight savings time is active.
+* Time Intervals:: Keeping track of time intervals.
@end menu
@node Calendar Motion
@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
If the variable @code{cal-tex-diary} is non-@code{nil} (the default is
@code{nil}), diary entries are included also (in weekly and monthly
calendars only). If the variable @code{cal-tex-rules} is non-@code{nil}
-(the default is @code{nil}), the calendar styles with sufficient room
-have ruled pages.
+(the default is @code{nil}), the calendar displays ruled pages
+in styles that have sufficient room.
@node Holidays
@section Holidays
@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
@cindex astronomical day numbers
Astronomers use a simple counting of days elapsed since noon, Monday,
January 1, 4713 B.C. on the Julian calendar. The number of days elapsed
-is called the @emph{Julian day number} or the @emph{Astronomical day number}.
+is called the @dfn{Julian day number} or the @dfn{Astronomical day number}.
@cindex Hebrew calendar
The Hebrew calendar is used by tradition in the Jewish religion. The
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
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
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
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
+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
@example
Monday
9:30am Coffee break
- 12:00pm Lunch
+ 12:00pm Lunch
@end example
@noindent
after midnight local time when the transition to and from daylight
savings time should occur. For Cambridge, Massachusetts both variables'
values are 120.
+
+@node Time Intervals
+@section Summing Time Intervals
+@cindex time intervals, summing
+@cindex summing time intervals
+@cindex timeclock
+
+ The timeclock feature adds up time intervals, so you can (for
+instance) keep track of how much time you spend working.
+
+@findex timeclock-in
+@findex timeclock-out
+@findex timeclock-workday-remaining
+@findex timeclock-when-to-leave
+ Use the @kbd{M-x timeclock-in} command when you start working on a
+project, and @kbd{M-x timeclock-out} command when you're done. Each
+time you do this, it adds one time interval to the record of the project.
+
+ Once you've collected data from a number of time intervals, you can use
+@kbd{M-x timeclock-workday-remaining} to see how much time is left to
+work today (assuming a typical average of 8 hours a day), and @kbd{M-x
+timeclock-when-to-leave} which will calculate when you're ``done.''
+
+@vindex timeclock-modeline-display
+@findex timeclock-modeline-display
+ If you want Emacs to display the amount of time ``left'' of your
+workday in the mode line, either customize the
+@code{timeclock-modeline-display} variable and set its value to
+@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. If you'd like Emacs to ask
+you about this, set the value of the variable
+@code{timeclock-ask-before-exiting} to @code{t} (via @kbd{M-x
+customize}). By default, only an explicit @kbd{M-x timeclock-out}
+tells Emacs that the current interval is over.
+
+@cindex @file{.timelog} file
+@vindex timeclock-file
+@findex timeclock-reread-log
+ 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
+by customizing the variable @code{timeclock-file}. If you edit the
+timeclock file manually, or if you change the value of any of
+timeclock's customizable variables, you should run the command
+@kbd{M-x timeclock-reread-log} to update the data in Emacs from the
+file.