@c This is part of the Emacs manual.
-@c Copyright (C) 1985, 1986, 1987, 1993, 1994, 1995, 1997, 2000, 2001,
-@c 2002, 2003, 2004, 2005, 2006, 2007, 2008 Free Software Foundation, Inc.
+@c Copyright (C) 1985-1987, 1993-1995, 1997, 2000-2011
+@c Free Software Foundation, Inc.
@c See file emacs.texi for copying conditions.
-@node Calendar/Diary, Gnus, Dired, Top
+@node Calendar/Diary, Document View, Dired, Top
@chapter The Calendar and the Diary
@cindex calendar
@findex calendar
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{Mouse-3} brings up a menu of commonly used
+ @kbd{Mouse-3} in the calendar brings up a menu of operations on a
+particular date; @kbd{Mouse-2} brings up a menu of commonly used
calendar features that are independent of any particular date. To exit
the calendar, type @kbd{q}.
* Lunar Phases:: Displaying phases of the moon.
* Other Calendars:: Converting dates to other calendar systems.
* Diary:: Displaying events from your diary.
-* Appointments:: Reminders when it's time to do something.
+* Appointments:: Reminders when it's time to do something.
* Importing Diary:: Converting diary events to/from other formats.
* Daylight Saving:: How to specify when daylight saving time is active.
* Time Intervals:: Keeping track of time intervals.
@item g D
Move point to specified day of year (@code{calendar-goto-day-of-year}).
@item g w
-Move point to specified week of year (@code{calendar-goto-iso-week}).
+Move point to specified week of year (@code{calendar-iso-goto-week}).
@item o
Center calendar around specified month (@code{calendar-other-month}).
@item .
@kindex g D @r{(Calendar mode)}
@findex calendar-goto-day-of-year
@kindex g w @r{(Calendar mode)}
-@findex calendar-goto-iso-week
+@findex calendar-iso-goto-week
@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. @kbd{g w}
-(@code{calendar-goto-iso-week}) prompts for a year and week number,
+(@code{calendar-iso-goto-week}) prompts for a year and week number,
and moves to that week.
@kindex o @r{(Calendar mode)}
@item <
Scroll calendar one month backward (@code{calendar-scroll-right}).
@item C-v
-@itemx @key{NEXT}
+@itemx @key{next}
Scroll calendar three months forward
(@code{calendar-scroll-left-three-months}).
@item M-v
-@itemx @key{PRIOR}
+@itemx @key{prior}
Scroll calendar three months backward
(@code{calendar-scroll-right-three-months}).
@end table
by four, typing @kbd{C-u C-v} scrolls the calendar forward by a year and
typing @kbd{C-u M-v} scrolls the calendar backward by a year.
- The function keys @key{NEXT} and @key{PRIOR} are equivalent to
+ The function keys @key{next} and @key{prior} are equivalent to
@kbd{C-v} and @kbd{M-v}, just as they are in other modes.
@node Counting Days
@kindex SPC @r{(Calendar mode)}
In Calendar mode, you can use @kbd{SPC} (@code{scroll-other-window})
and @kbd{DEL} (@code{scroll-other-window-down}) to scroll the other
-window up or down, respectively. This is handy when you display a list
-of holidays or diary entries in another window.
+window (if there is one) up or down, respectively. This is handy when
+you display a list of holidays or diary entries in another window.
@kindex q @r{(Calendar mode)}
@findex exit-calendar
@node Writing Calendar Files
@section Writing Calendar Files
- These packages produce files of various formats containing calendar
-and diary entries, for display purposes.
+ You can write calendars and diary entries to HTML and La@TeX{} files.
@cindex calendar and HTML
The Calendar HTML commands produce files of HTML code that contain
@section Holidays
@cindex holidays
- The Emacs calendar knows about all major and many minor holidays,
-and can display them.
+ The Emacs calendar knows about many major and minor holidays,
+and can display them. You can add your own holidays to the default list.
@table @kbd
@item h
Display holidays for the selected date
(@code{calendar-cursor-holidays}).
-@item Mouse-2 Holidays
+@item Mouse-3 Holidays
Display any holidays for the date you click on.
@item x
Mark holidays in the calendar window (@code{calendar-mark-holidays}).
@vindex calendar-view-holidays-initially-flag
To see if any holidays fall on a given date, position point on that
date in the calendar window and use the @kbd{h} command. Alternatively,
-click on that date with @kbd{Mouse-2} and then choose @kbd{Holidays}
+click on that date with @kbd{Mouse-3} 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.
@vindex calendar-mark-holidays-flag
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
-a color display is not available, or if @code{font-lock-mode} is off).
+holidays in a different face.
@iftex
@inforef{Calendar Customizing, calendar-holiday-marker, emacs-xtra}.
@end iftex
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
-equinoxes.
+major Baha'i, Chinese, Christian, Islamic, and Jewish holidays; also the
+solstices and equinoxes.
@findex list-holidays
The command @kbd{M-x holiday-list} displays the list of holidays for
@item S
Display times of sunrise and sunset for the selected date
(@code{calendar-sunrise-sunset}).
-@item Mouse-2 Sunrise/sunset
+@item Mouse-3 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.
@item C-u M-x sunrise-sunset
Display times of sunrise and sunset for a specified date.
+@item M-x calendar-sunrise-sunset-month
+Display times of sunrise and sunset for the selected month.
@end table
@kindex S @r{(Calendar mode)}
@findex sunrise-sunset
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{S}. Alternatively, click @kbd{Mouse-3} on the date, then choose
@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
@table @kbd
@item M
Display the dates and times for all the quarters of the moon for the
-three-month period shown (@code{calendar-phases-of-moon}).
-@item M-x phases-of-moon
+three-month period shown (@code{calendar-lunar-phases}).
+@item M-x lunar-phases
Display dates and times of the quarters of the moon for three months around
today's date.
@end table
@kindex M @r{(Calendar mode)}
-@findex calendar-phases-of-moon
+@findex calendar-lunar-phases
Within the calendar, use the @kbd{M} command to display a separate
buffer of the phases of the moon for the current three-month range. The
dates and times listed are accurate to within a few minutes.
-@findex phases-of-moon
- Outside the calendar, use the command @kbd{M-x phases-of-moon} to
+@findex lunar-phases
+ Outside the calendar, use the command @kbd{M-x lunar-phases} to
display the list of the phases of the moon for the current month and the
preceding and succeeding months. For information about a different
-month, use @kbd{C-u M-x phases-of-moon}, which prompts for the month and
+month, use @kbd{C-u M-x lunar-phases}, which prompts for the month and
year.
The dates and times given for the phases of the moon are given in
-local time (corrected for daylight saving, when appropriate); but if
-the variable @code{calendar-time-zone} is void, Coordinated Universal
-Time (the Greenwich time zone) is used. @xref{Daylight Saving}.
+local time (corrected for daylight saving, when appropriate).
+See the discussion in the previous section. @xref{Sunrise/Sunset}.
@node Other Calendars
@section Conversion To and From Other Calendars
and from several other calendars.
@menu
-* Calendar Systems:: The calendars Emacs understands
- (aside from Gregorian).
-* To Other Calendar:: Converting the selected date to various calendars.
-* From Other Calendar:: Moving to a date specified in another calendar.
-* Mayan Calendar:: Moving to a date specified in a Mayan calendar.
+* Calendar Systems:: The calendars Emacs understands
+ (aside from Gregorian).
+* To Other Calendar:: Converting the selected date to various calendars.
+* From Other Calendar:: Moving to a date specified in another calendar.
+* Mayan Calendar:: Moving to a date specified in a Mayan calendar.
@end menu
@node Calendar Systems
in various other calendar systems:
@table @kbd
-@item Mouse-2 Other calendars
+@item Mouse-3 Other calendars
Display the date that you click on, expressed in various other calendars.
@kindex p @r{(Calendar mode)}
+@findex calendar-print-other-dates
+@item p o
+Display the selected date in various other calendars.
+(@code{calendar-print-other-dates}).
@findex calendar-iso-print-date
@item p c
Display ISO commercial calendar equivalent for selected day
Display Mayan date for selected day (@code{calendar-mayan-print-date}).
@end table
- 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
-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.)
+ If you are using a graphic display, the easiest way to translate a
+date into other calendars is to click on it with @kbd{Mouse-3}, then
+choose @kbd{Other 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.)
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.
+equivalent date in the echo area. @kbd{p o} displays the
+date in all forms known to Emacs.
@node From Other Calendar
@subsection Converting From Other Calendars
@findex calendar-iso-goto-week
@findex calendar-julian-goto-date
@findex calendar-astro-goto-day-number
+@findex calendar-bahai-goto-date
@findex calendar-hebrew-goto-date
@findex calendar-islamic-goto-date
@findex calendar-french-goto-date
@item g a
Move to a date specified with an astronomical (Julian) day number
(@code{calendar-astro-goto-day-number}).
+@item g b
+Move to a date specified in the Baha'i calendar
+(@code{calendar-bahai-goto-date}).
@item g h
Move to a date specified in the Hebrew calendar
(@code{calendar-hebrew-goto-date}).
These commands ask you for a date on the other calendar, move point to
the Gregorian calendar date equivalent to that date, and display the
other calendar's date in the echo area. Emacs uses strict completion
-(@pxref{Completion}) whenever it asks you to type a month name, so you
+(@pxref{Strict Completion}) whenever it asks you to type a month name, so you
don't have to worry about the spelling of Hebrew, Islamic, or French names.
+@c FIXME move?
@findex calendar-hebrew-list-yahrzeits
@cindex yahrzeits
One common question concerning the Hebrew calendar is the computation
@menu
* Displaying the Diary:: Viewing diary entries and associated calendar dates.
* Format of Diary File:: Entering events in your diary.
-* Date Formats:: Various ways you can specify dates.
-* Adding to Diary:: Commands to create diary entries.
+* Date Formats:: Various ways you can specify dates.
+* Adding to Diary:: Commands to create diary entries.
* Special Diary Entries:: Anniversaries, blocks of dates, cyclic entries, etc.
@end menu
@subsection Displaying the Diary
Once you have created a diary file, you can use the calendar to view
-it. You can also view today's events outside of Calendar mode.
+it. You can also view today's events outside of Calendar mode. In the
+following, key bindings refer to the Calendar buffer.
@table @kbd
@item d
Display all diary entries for the selected date
(@code{diary-view-entries}).
-@item Mouse-2 Diary
+@item Mouse-3 Diary
Display all diary entries for the date you click on.
@item s
Display the entire diary file (@code{diary-show-all-entries}).
@vindex calendar-view-diary-initially-flag
Displaying the diary entries with @kbd{d} shows in a separate window
the diary entries for the selected date in the calendar. The mode line
-of the new window shows the date of the diary entries and any holidays
-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.
+of the new window shows the date of the diary entries. Holidays are
+shown either in the buffer or in the mode line, depending on the display
+method you choose
+@iftex
+(@pxref{Diary Display,,, emacs-xtra, Specialized Emacs Features}).
+@end iftex
+@ifnottex
+(@pxref{Diary Display}).
+@end ifnottex
+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.
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
+@kbd{Mouse-3} on the date, and then choose @kbd{Diary entries} from
the menu that appears. If the variable
@code{calendar-view-diary-initially-flag} is non-@code{nil}, creating the
calendar lists the diary entries for the current date (provided the
@findex diary-mark-entries
@vindex calendar-mark-diary-entries-flag
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).
+the @kbd{m} command. This marks the dates that have diary entries in
+a different face.
@iftex
@inforef{Calendar Customizing, diary-entry-marker, emacs-xtra}.
@end iftex
@ifnottex
@xref{Calendar Customizing, diary-entry-marker}.
@end ifnottex
+
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
To see the full diary file, rather than just some of the entries, use
the @kbd{s} command.
- Display of selected diary entries uses invisible text 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 diary-print-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
@inforef{Diary Customizing,, emacs-xtra}.
@end iftex
@ifnottex
-@xref{Diary Customizing, number-of-diary-entries}.
+@xref{Diary Customizing, diary-number-of-entries}.
@end ifnottex
If you put @code{(diary)} in your @file{.emacs} file, this
automatically displays a window with the day's diary entries, when you
-enter Emacs. The mode line of the displayed window shows the date and
-any holidays that fall on that date.
+enter Emacs.
@findex diary-mail-entries
@vindex diary-mail-days
entry. Lines that do not begin with valid dates and do not continue a
preceding entry are ignored.
- You can inhibit the marking of certain diary entries in the calendar
-window; to do this, insert an ampersand (@samp{&}) at the beginning of
-the entry, before the date. This has no effect on display of the entry
-in the diary window; it affects only marks on dates in the calendar
-window. Nonmarking entries are especially useful for generic entries
-that would otherwise mark many different dates.
-
- If the first line of a diary entry consists only of the date or day
-name with no following blanks or punctuation, then the diary window
-display doesn't include that line; only the continuation lines appear.
-For example, this entry:
+ You can also use a format where the first line of a diary entry
+consists only of the date or day name (with no following blanks or
+punctuation). For example:
@example
02/11/1989
@end example
@noindent
-appears in the diary window without the date line at the beginning.
-This style of entry looks neater when you display just a single day's
-entries, but can cause confusion if you ask for more than one day's
-entries.
-
- You can edit the diary entries as they appear in the window, but it is
-important to remember that the buffer displayed contains the @emph{entire}
-diary file, with portions of it concealed from view. This means, for
-instance, that the @kbd{C-f} (@code{forward-char}) command can put point
-at what appears to be the end of the line, but what is in reality the
-middle of some concealed line.
+This entry will have a different appearance if you use the simple diary
+display
+@iftex
+(@pxref{Diary Display,,, emacs-xtra, Specialized Emacs Features}).
+@end iftex
+@ifnottex
+(@pxref{Diary Display}).
+@end ifnottex
+The simple diary display omits the date line at the beginning; only the
+continuation lines appear. This style of entry looks neater when you
+display just a single day's entries, but can cause confusion if you ask
+for more than one day's entries.
- @emph{Be careful when editing the diary entries!} Inserting
-additional lines or adding/deleting characters in the middle of a
-visible line cannot cause problems, but editing at the end of a line may
-not do what you expect. Deleting a line may delete other invisible
-entries that follow it. Before editing the diary, it is best to display
-the entire file with @kbd{s} (@code{diary-show-all-entries}).
+@vindex diary-nonmarking-symbol
+ You can inhibit the marking of certain diary entries in the calendar
+window; to do this, insert an ampersand @code{diary-nonmarking-symbol}
+(default @samp{&}) at the beginning of the entry, before the date. This
+has no effect on display of the entry in the diary window; it affects
+only marks on dates in the calendar window. Nonmarking entries are
+especially useful for generic entries that would otherwise mark many
+different dates.
@node Date Formats
@subsection Date Formats
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 (with or without a period). The
-preferred abbreviations can be controlled using the variables
-@code{calendar-abbrev-length}, @code{calendar-month-abbrev-array}, and
+preferred abbreviations for month and day names can be set 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.
You can use the name of a day of the week as a generic date which
applies to any date falling on that day of the week. You can abbreviate
-the day of the week to three letters (with or without a period) or spell
-it in full; case is not significant.
+the day of the week as described above, or spell it in full; case is not
+significant.
@node Adding to Diary
@subsection Commands to Add to the Diary
While in the calendar, there are several commands to create diary
-entries:
+entries. The basic commands are listed here; more sophisticated
+commands are in the next section (@pxref{Special Diary Entries}).
+Entries can also be based on non-Gregorian calendars.
+@iftex
+@inforef{Non-Gregorian Diary,, emacs-xtra}.
+@end iftex
+@ifnottex
+@xref{Non-Gregorian Diary}.
+@end ifnottex
@table @kbd
@item i d
@inforef{Sexp Diary Entries,, emacs-xtra}.
@end iftex
@ifnottex
-@inforef{Sexp Diary Entries}.
+@xref{Sexp Diary Entries}.
@end ifnottex
@node Appointments
respectively.
@findex appt-activate
- 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.
+ To enable appointment notification, type @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:
@end example
@vindex appt-message-warning-time
+@vindex appt-warning-time-regexp
@noindent
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).
+@code{appt-message-warning-time} specifies how many minutes (default 12)
+in advance to warn you. This is a default warning time. Each
+appointment can specify a different warning time by adding a piece
+matching @code{appt-warning-time-regexp} (see that variable's
+documentation for details).
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. Times must be at the beginning
-of lines if they are to be recognized.
+can have a mixture of the two styles. Times must be at the beginning of
+diary entries if they are to be recognized.
@vindex appt-display-diary
Emacs updates the appointments list from the diary file
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.
+also updated whenever the diary file (or a file it includes; see
+@iftex
+@inforef{Fancy Diary Display,, emacs-xtra})
+@end iftex
+@ifnottex
+@ref{Fancy Diary Display})
+@end ifnottex
+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. This feature is a work in progress, so the
-commands may evolve in future.
+@c Importing works for ``ordinary'' (i.e. non-recurring) events, but
+@c (at present) may not work correctly (if at all) for recurring events.
+@c Exporting of diary files into iCalendar files should work correctly
+@c for most diary entries. This feature is a work in progress, so the
+@c commands may evolve in future.
@findex icalendar-import-buffer
The command @code{icalendar-import-buffer} extracts
@cindex summing time intervals
@cindex timeclock
- The timeclock feature adds up time intervals, so you can (for
+ The timeclock package adds up time intervals, so you can (for
instance) keep track of how much time you spend working on particular
projects.
@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 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 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.
+you. You can, however, set customize the value of the variable
+@code{timeclock-ask-before-exiting} to @code{nil} 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.
@cindex @file{.timelog} file
@vindex timeclock-file
@ifnottex
@include cal-xtra.texi
@end ifnottex
-
-@ignore
- arch-tag: 4531ef09-9df3-449d-9c52-2b5a4a337f92
-@end ignore
HCoop / bpt / emacs.git / blobdiff