@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.
+@iftex
+ This chapter describes the basic calendar features.
@inforef{Advanced Calendar/Diary Usage,, emacs-xtra}, for information
about more specialized features.
+@end iftex
@menu
* Calendar Motion:: Moving through the calendar; selecting a date.
* Scroll Calendar:: Bringing earlier or later months onto the screen.
* Counting Days:: How many days are there between two dates?
* General Calendar:: Exiting or recomputing the calendar.
-* LaTeX Calendar:: Print a calendar using LaTeX.
+* Writing Calendar Files:: Writing calendars to files of various formats.
* Holidays:: Displaying dates of holidays.
* Sunrise/Sunset:: Displaying local times of sunrise and sunset.
* Lunar Phases:: Displaying phases of the moon.
* Importing Diary:: Converting diary events to/from other formats.
* Daylight Savings:: How to specify when daylight savings time is active.
* Time Intervals:: Keeping track of time intervals.
+@ifnottex
+* Advanced Calendar/Diary Usage:: Advanced Calendar/Diary customization.
+@end ifnottex
@end menu
@node Calendar Motion
@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)}
(If a frame contains a dedicated calendar window, exiting from the
calendar iconifies that frame.)
-@node LaTeX Calendar
-@section LaTeX Calendar
-@cindex calendar and La@TeX{}
+@node Writing Calendar Files
+@section Writing Calendar Files
+
+ These packages produce files of various formats containing calendar
+and diary entries, for display purposes.
+
+@cindex calendar and HTML
+ The Calendar HTML commands produce files of HTML code that contain
+calendar and diary entries. Each file applies to one month, and has a
+name of the format @file{@var{yyyy}-@var{mm}.html}, where @var{yyyy} and
+@var{mm} are the four-digit year and two-digit month, respectively. The
+variable @code{cal-html-directory} specifies the default output
+directory for the HTML files.
+
+@vindex cal-html-css-default
+ Diary entries enclosed by @code{<} and @code{>} are interpreted as
+HTML tags (for example: this is a diary entry with <font
+color=''red''>some red text</font>). You can change the overall
+appearance of the displayed HTML pages (for example, the color of
+various page elements, header styles) via a stylesheet @file{cal.css} in
+the directory containing the HTML files (see the value of the variable
+@code{cal-html-css-default} for relevant style settings).
- The Calendar La@TeX{} commands produce a buffer of La@TeX{} code that
+@kindex t @r{(Calendar mode)}
+@table @kbd
+@item H m
+Generate a one-month calendar (@code{cal-html-cursor-month}).
+@item H y
+Generate a calendar file for each month of a year, as well as an index
+page (@code{cal-html-cursor-year}). By default, this command writes
+files to a @var{yyyy} subdirectory - if this is altered some hyperlinks
+between years will not work.
+@end table
+
+ If the variable @code{cal-html-print-day-number-flag} is
+non-@code{nil}, then the monthly calendars show the day-of-the-year
+number. The variable @code{cal-html-year-index-cols} specifies the
+number of columns in the yearly index page.
+
+@cindex calendar and La@TeX{}
+ The Calendar La@TeX{} commands produce a buffer of La@TeX{} code that
prints as a calendar. Depending on the command you use, the printed
calendar covers the day, week, month or year that point is in.
@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 displays ruled pages
-in styles that have sufficient room.
+in styles that have sufficient room. You can use the variable
+@code{cal-tex-preamble-extra} to insert extra La@TeX{} commands in the
+preamble of the generated document if you need to.
@node Holidays
@section Holidays
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). @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}, holidays are marked in the calendar when it is created
-(or recomputed).
-
+display with multiple faces is not available).
+@iftex
+@inforef{Calendar Customizing, calendar-holiday-marker, emacs-xtra}.
+@end iftex
+@ifnottex
+@xref{Calendar Customizing, calendar-holiday-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
+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!!
@table @kbd
@item d
Display all diary entries for the selected date
-(@code{view-diary-entries}).
+(@code{diary-view-entries}).
@item Mouse-2 Diary
Display all diary entries for the date you click on.
@item s
-Display the entire diary file (@code{show-all-diary-entries}).
+Display the entire diary file (@code{diary-show-all-entries}).
@item m
Mark all visible dates that have diary entries
(@code{mark-diary-entries}).
@end table
@kindex d @r{(Calendar mode)}
-@findex view-diary-entries
+@findex diary-view-entries
@vindex view-diary-entries-initially
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
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). @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},
-diary dates are marked in the calendar when it is created (or
-recomputed).
+with multiple faces is not available).
+@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
+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
+@findex diary-show-all-entries
To see the full diary file, rather than just some of the entries, use
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. @inforef{Diary Customizing,, emacs-xtra}.
+how many days to include.
+@iftex
+@inforef{Diary Customizing,, emacs-xtra}.
+@end iftex
+@ifnottex
+@xref{Diary Customizing, number-of-diary-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
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{show-all-diary-entries}).
+the entire file with @kbd{s} (@code{diary-show-all-entries}).
@node Date Formats
@subsection Date Formats
If you prefer the European style of writing dates---in which the day
comes before the month---type @kbd{M-x european-calendar} while in the
calendar, or set the variable @code{european-calendar-style} to @code{t}
-@emph{before} using any calendar or diary command. This mode interprets
-all dates in the diary in the European manner, and also uses European
-style for displaying diary dates. (Note that there is no comma after
-the @var{monthname} in the European style.) To go back to the (default)
-American style of writing dates, type @kbd{M-x american-calendar}.
+with @kbd{M-x customize}, or @emph{before} using any calendar or diary
+command. This mode interprets all dates in the diary in the European
+manner, and also uses European style for displaying diary dates. (Note
+that there is no comma after the @var{monthname} in the European style.)
+To go back to the (default) American style of writing dates, type
+@kbd{M-x american-calendar}.
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
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.
+@iftex
@inforef{Sexp Diary Entries,, emacs-xtra}.
+@end iftex
+@ifnottex
+@inforef{Sexp Diary Entries}.
+@end ifnottex
@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
and adds the results to an Emacs diary file. For example:
@example
-(icalendar-import-file "/here/is/calendar.ics" "/there/goes/ical-diary")
+(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. @inforef{Fancy Diary
-Display,, emacs-xtra}.
+to the main diary file, if these are different files.
+@iftex
+@inforef{Fancy Diary Display,, emacs-xtra}.
+@end iftex
+@ifnottex
+@xref{Fancy Diary Display}.
+@end ifnottex
+
@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.
should run the command @kbd{M-x timeclock-reread-log} to update the
data in Emacs from the file.
+@ifnottex
+@include cal-xtra.texi
+@end ifnottex
+
@ignore
arch-tag: 4531ef09-9df3-449d-9c52-2b5a4a337f92
@end ignore