-@c This is part of the Emacs manual.
-@c Copyright (C) 1985-1987, 1993-1995, 1997, 2000-2011
-@c Free Software Foundation, Inc.
+@c This is part of the Emacs manual. -*- coding: utf-8 -*-
+@c Copyright (C) 1985-1987, 1993-1995, 1997, 2000-2016 Free Software
+@c Foundation, Inc.
@c See file emacs.texi for copying conditions.
-@node Calendar/Diary, Document View, Dired, Top
+@node Calendar/Diary
@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-3} in the calendar brings up a menu of operations on a
-particular date; @kbd{Mouse-2} 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}.
@iftex
This chapter describes the basic calendar features.
-@inforef{Advanced Calendar/Diary Usage,, emacs-xtra}, for information
-about more specialized features.
+For more advanced topics,
+@pxref{Advanced Calendar/Diary Usage,,, emacs-xtra, Specialized Emacs Features}.
@end iftex
@menu
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
+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.
A week (or month, or year) is not just a quantity of days; we think of
weeks (months, years) as starting on particular dates. So Calendar mode
-provides commands to move to the beginning or end of a week, month or
-year:
+provides commands to move to the start or end of a week, month or year:
@table @kbd
@kindex C-a @r{(Calendar mode)}
backward or forward.
@vindex calendar-week-start-day
+@vindex calendar-weekend-days
@cindex weeks, which day they start on
@cindex calendar, first day of week
By default, weeks begin on Sunday. To make them begin on Monday
-instead, set the variable @code{calendar-week-start-day} to 1.
+instead, set the variable @code{calendar-week-start-day} to 1. To
+change which day headers are highlighted as weekend days, set the
+variable @code{calendar-weekend-days}.
@node Specified Dates
@subsection Specified Dates
@kbd{g d} (@code{calendar-goto-date}) prompts for a year, a month, and a day
of the month, and then moves to that date. Because the calendar includes all
dates from the beginning of the current era, you must type the year in its
-entirety; that is, type @samp{1990}, not @samp{90}.
+entirety; that is, type @samp{2010}, not @samp{10}.
@kindex g D @r{(Calendar mode)}
@findex calendar-goto-day-of-year
Scroll calendar one month backward (@code{calendar-scroll-right}).
@item C-v
@itemx @key{next}
-Scroll calendar three months forward
-(@code{calendar-scroll-left-three-months}).
+Scroll forward by three months (@code{calendar-scroll-left-three-months}).
@item M-v
@itemx @key{prior}
-Scroll calendar three months backward
-(@code{calendar-scroll-right-three-months}).
+Scroll backward by three months (@code{calendar-scroll-right-three-months}).
@end table
@kindex > @r{(Calendar mode)}
@kindex M-v @r{(Calendar mode)}
@findex calendar-scroll-right-three-months
The commands @kbd{C-v} and @kbd{M-v} scroll the calendar by an entire
-``screenful''---three months---in analogy with the usual meaning of
+screenful---three months---in analogy with the usual meaning of
these commands. @kbd{C-v} makes later dates visible and @kbd{M-v} makes
earlier dates visible. These commands take a numeric argument as a
repeat count; in particular, since @kbd{C-u} multiplies the next command
@kindex M-= @r{(Calendar mode)}
@findex calendar-count-days-region
- To determine the number of days in the region, type @kbd{M-=}
+ To determine the number of days in a range, set the mark on one
+date using @kbd{C-@key{SPC}}, move point to another date, and type @kbd{M-=}
(@code{calendar-count-days-region}). The numbers of days shown is
@emph{inclusive}; that is, it includes the days specified by mark and
point.
Display day-in-year (@code{calendar-print-day-of-year}).
@item C-c C-l
Regenerate the calendar window (@code{calendar-redraw}).
-@item SPC
+@item @key{SPC}
Scroll the next window up (@code{scroll-other-window}).
-@item DEL
+@item @key{DEL}
+@itemx S-@key{SPC}
Scroll the next window down (@code{scroll-other-window-down}).
@item q
Exit from calendar (@code{calendar-exit}).
non-Calendar-mode editing commands.)
@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
+ In Calendar mode, you can use @key{SPC} (@code{scroll-other-window})
+and @key{DEL} (@code{scroll-other-window-down}) to scroll the other
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.
calendar deletes or iconifies that frame depending on the value of
@code{calendar-remove-frame-by-deleting}.)
+@c FIXME this mentions holidays and diary entries, albeit briefly, so
+@c should it be moved after those sections? Or at least xref them.
@node Writing Calendar Files
@section Writing Calendar Files
- You can write calendars and diary entries to HTML and La@TeX{} files.
+ You can write calendars and diary entries to HTML and @LaTeX{} files.
@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.
+calendar, holiday, 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. To prevent holidays
+from being shown, customize @code{cal-html-holidays}.
@vindex cal-html-css-default
Diary entries enclosed by @code{<} and @code{>} are interpreted as
@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
+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. 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
+@cindex calendar and @LaTeX{}
+ The Calendar @LaTeX{} commands produce a buffer of @LaTeX{} 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.
Generate a one-day calendar
(@code{cal-tex-cursor-day}).
@item t w 1
-Generate a one-page calendar for one week
+Generate a one-page calendar for one week, with hours
(@code{cal-tex-cursor-week}).
@item t w 2
-Generate a two-page calendar for one week
+Generate a two-page calendar for one week, with hours
(@code{cal-tex-cursor-week2}).
@item t w 3
-Generate an ISO-style calendar for one week
+Generate an ISO-style calendar for one week, without hours
(@code{cal-tex-cursor-week-iso}).
@item t w 4
-Generate a calendar for one Monday-starting week
+Generate a calendar for one Monday-starting week, with hours
(@code{cal-tex-cursor-week-monday}).
+@item t w W
+Generate a two-page calendar for one week, without hours
+(@code{cal-tex-cursor-week2-summary}).
@item t f w
Generate a Filofax-style two-weeks-at-a-glance calendar
(@code{cal-tex-cursor-filofax-2week}).
(@code{cal-tex-cursor-filofax-year}).
@end table
- Some of these commands print the calendar sideways (in ``landscape
-mode''), so it can be wider than it is long. Some of them use Filofax
+ Some of these commands print the calendar sideways (in landscape
+mode), so it can be wider than it is long. Some of them use Filofax
paper size (3.75in x 6.75in). All of these commands accept a prefix
-argument which specifies how many days, weeks, months or years to print
+argument, which specifies how many days, weeks, months or years to print
(starting always with the selected one).
If the variable @code{cal-tex-holidays} is non-@code{nil} (the default),
features.
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
+@LaTeX{} commands in the preamble of the generated document if you need
to.
@node Holidays
and can display them. You can add your own holidays to the default list.
@table @kbd
-@item h
+@item mouse-3 Holidays
+@itemx h
Display holidays for the selected date
(@code{calendar-cursor-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}).
@item u
@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-3} 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.
calendar, use the @kbd{x} command. This displays the dates that are
holidays in a different face.
@iftex
-@inforef{Calendar Customizing, calendar-holiday-marker, emacs-xtra}.
+@xref{Calendar Customizing,,, emacs-xtra, Specialized Emacs Features}.
@end iftex
@ifnottex
@xref{Calendar Customizing, calendar-holiday-marker}.
holidays}, which prompts for the month and year.
The holidays known to Emacs include United States holidays and the
-major Baha'i, Chinese, Christian, Islamic, and Jewish holidays; also the
+major Bahá'í, Chinese, Christian, Islamic, and Jewish holidays; also the
solstices and equinoxes.
@findex list-holidays
times of sunrise and sunset for any date.
@table @kbd
-@item S
+@item mouse-3 Sunrise/sunset
+@itemx S
Display times of sunrise and sunset for the selected date
(@code{calendar-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
@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-3} 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
As a user, you might find it convenient to set the calendar location
variables for your usual physical location in your @file{.emacs} file.
-And when you install Emacs on a machine, you can create a
-@file{default.el} file which sets them properly for the typical location
-of most users of that machine. @xref{Init File}.
+If you are a system administrator, you may want to set these variables
+for all users in a @file{default.el} file. @xref{Init File}.
@node Lunar Phases
@section Phases of the Moon
These calendar commands display the dates and times of the phases of
the moon (new moon, first quarter, full moon, last quarter). This
-feature is useful for debugging problems that ``depend on the phase of
-the moon.''
+feature is useful for debugging problems that depend on the phase of
+the moon.
@table @kbd
@item M
@cindex Gregorian calendar
The Emacs calendar displayed is @emph{always} the Gregorian calendar,
-sometimes called the ``new style'' calendar, which is used in most of
+sometimes called the New Style calendar, which is used in most of
the world today. However, this calendar did not exist before the
sixteenth century and was not widely used before the eighteenth century;
it did not fully displace the Julian calendar and gain universal
acceptance until the early twentieth century. The Emacs calendar can
display any month since January, year 1 of the current era, but the
-calendar displayed is the Gregorian, even for a date at which the
-Gregorian calendar did not exist.
+calendar displayed is always the Gregorian, even for a date at which
+the Gregorian calendar did not exist.
While Emacs cannot display other calendars, it can convert dates to
and from several other calendars.
(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
+@c FIXME perhaps most of the details should be moved to cal-xtra.
+@c Just list the major supported systems here?
@node Calendar Systems
@subsection Supported Calendar Systems
@cindex ISO commercial calendar
- The ISO commercial calendar is used largely in Europe.
+ The ISO commercial calendar is often used in business.
@cindex Julian calendar
The Julian calendar, named after Julius Caesar, was the one used in Europe
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.
+official calendar of Iran will be at that time.
+@c FIXME not so far in the future now.
@cindex Chinese calendar
The Chinese calendar is a complicated system of lunar months arranged
into solar years. The years go in cycles of sixty, each year containing
either twelve months in an ordinary year or thirteen months in a leap
year; each month has either 29 or 30 days. Years, ordinary months, and
-days are named by combining one of ten ``celestial stems'' with one of
-twelve ``terrestrial branches'' for a total of sixty names that are
+days are named by combining one of ten @dfn{celestial stems} with one of
+twelve @dfn{terrestrial branches} for a total of sixty names that are
repeated in a cycle of sixty.
-@cindex Baha'i calendar
- The Baha'i calendar system is based on a solar cycle of 19 months with
-19 days each. The four remaining ``intercalary'' days are placed
+@cindex Bahá'í calendar
+ The Bahá'í calendar system is based on a solar cycle of 19 months with
+19 days each. The four remaining intercalary days are placed
between the 18th and 19th months.
@node To Other Calendar
in various other calendar systems:
@table @kbd
-@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
+@item mouse-3 Other calendars
+@itemx p o
Display the selected date in various other calendars.
(@code{calendar-print-other-dates}).
@findex calendar-iso-print-date
(@code{calendar-french-print-date}).
@findex calendar-bahai-print-date
@item p b
-Display Baha'i date for selected day
+Display Bahá'í date for selected day
(@code{calendar-bahai-print-date}).
@findex calendar-chinese-print-date
@item p C
Display Mayan date for selected day (@code{calendar-mayan-print-date}).
@end table
- 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. @kbd{p o} displays the
-date in all forms known to Emacs.
+prefix @kbd{p} is a mnemonic for ``print'', since Emacs ``prints'' the
+equivalent date in the echo area. @kbd{p o} displays the
+date in all forms known to Emacs. You can also use @kbd{mouse-3} and
+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.)
@node From Other Calendar
@subsection Converting From Other Calendars
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
+Move to a date specified in the Bahá'í calendar
(@code{calendar-bahai-goto-date}).
@item g h
Move to a date specified in the Hebrew calendar
(@code{calendar-ethiopic-goto-date}).
@end table
- 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{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.
+ 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 Exit}) 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
-of the anniversary of a date of death, called a ``yahrzeit.'' The Emacs
+ One common issue concerning the Hebrew calendar is the computation
+of the anniversary of a date of death, called a @dfn{yahrzeit}. The Emacs
calendar includes a facility for such calculations. If you are in the
calendar, the command @kbd{M-x calendar-hebrew-list-yahrzeits} asks you for
a range of years and then displays a list of the yahrzeit dates for those
this command first asks you for the date of death and the range of
years, and then displays the list of yahrzeit dates.
-@node Mayan Calendar
-@subsection Converting from the Mayan Calendar
-
- Here are the commands to select dates based on the Mayan calendar:
-
-@table @kbd
-@item g m l
-Move to a date specified by the long count calendar
-(@code{calendar-mayan-goto-long-count-date}).
-@item g m n t
-Move to the next occurrence of a place in the
-tzolkin calendar (@code{calendar-mayan-next-tzolkin-date}).
-@item g m p t
-Move to the previous occurrence of a place in the
-tzolkin calendar (@code{calendar-mayan-previous-tzolkin-date}).
-@item g m n h
-Move to the next occurrence of a place in the
-haab calendar (@code{calendar-mayan-next-haab-date}).
-@item g m p h
-Move to the previous occurrence of a place in the
-haab calendar (@code{calendar-mayan-previous-haab-date}).
-@item g m n c
-Move to the next occurrence of a place in the
-calendar round (@code{calendar-mayan-next-calendar-round-date}).
-@item g m p c
-Move to the previous occurrence of a place in the
-calendar round (@code{calendar-mayan-previous-calendar-round-date}).
-@end table
-
-@cindex Mayan long count
- To understand these commands, you need to understand the Mayan calendars.
-The @dfn{long count} is a counting of days with these units:
-
-@display
-1 kin = 1 day@ @ @ 1 uinal = 20 kin@ @ @ 1 tun = 18 uinal
-1 katun = 20 tun@ @ @ 1 baktun = 20 katun
-@end display
-
-@kindex g m @r{(Calendar mode)}
-@findex calendar-mayan-goto-long-count-date
-@noindent
-Thus, the long count date 12.16.11.16.6 means 12 baktun, 16 katun, 11
-tun, 16 uinal, and 6 kin. The Emacs calendar can handle Mayan long
-count dates as early as 7.17.18.13.3, but no earlier. When you use the
-@kbd{g m l} command, type the Mayan long count date with the baktun,
-katun, tun, uinal, and kin separated by periods.
-
-@findex calendar-mayan-previous-tzolkin-date
-@findex calendar-mayan-next-tzolkin-date
-@cindex Mayan tzolkin calendar
- The Mayan tzolkin calendar is a cycle of 260 days formed by a pair of
-independent cycles of 13 and 20 days. Since this cycle repeats
-endlessly, Emacs provides commands to move backward and forward to the
-previous or next point in the cycle. Type @kbd{g m p t} to go to the
-previous tzolkin date; Emacs asks you for a tzolkin date and moves point
-to the previous occurrence of that date. Similarly, type @kbd{g m n t}
-to go to the next occurrence of a tzolkin date.
-
-@findex calendar-mayan-previous-haab-date
-@findex calendar-mayan-next-haab-date
-@cindex Mayan haab calendar
- The Mayan haab calendar is a cycle of 365 days arranged as 18 months
-of 20 days each, followed a 5-day monthless period. Like the tzolkin
-cycle, this cycle repeats endlessly, and there are commands to move
-backward and forward to the previous or next point in the cycle. Type
-@kbd{g m p h} to go to the previous haab date; Emacs asks you for a haab
-date and moves point to the previous occurrence of that date.
-Similarly, type @kbd{g m n h} to go to the next occurrence of a haab
-date.
-
-@c This is omitted because it is too long for smallbook format.
-@c @findex calendar-mayan-previous-calendar-round-date
-@findex calendar-mayan-next-calendar-round-date
-@cindex Mayan calendar round
- The Maya also used the combination of the tzolkin date and the haab
-date. This combination is a cycle of about 52 years called a
-@emph{calendar round}. If you type @kbd{g m p c}, Emacs asks you for
-both a haab and a tzolkin date and then moves point to the previous
-occurrence of that combination. Use @kbd{g m n c} to move point to the
-next occurrence of a combination. These commands signal an error if the
-haab/tzolkin date combination you have typed is impossible.
-
- Emacs uses strict completion (@pxref{Strict Completion}) whenever it
-asks you to type a Mayan name, so you don't have to worry about
-spelling.
-
@node Diary
@section The Diary
@cindex diary
The Emacs diary keeps track of appointments or other events on a daily
basis, in conjunction with the calendar. To use the diary feature, you
-must first create a @dfn{diary file} containing a list of events and
+must first create a diary file containing a list of events and
their dates. Then Emacs can automatically pick out and display the
events for today, for the immediate future, or for any specified
date.
- The name of the diary file is specified by the variable
-@code{diary-file}; @file{~/diary} is the default. Here's an example
-showing what that file looks like:
+ Although you probably will start by creating a diary manually, Emacs
+provides a number of commands to let you view, add, and change diary
+entries.
+
+@menu
+* Format of Diary File:: Entering events in your diary.
+* Displaying the Diary:: Viewing diary entries and associated calendar dates.
+* 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
+
+@node Format of Diary File
+@subsection The Diary File
+@cindex diary file
+
+@vindex diary-file
+ Your @dfn{diary file} is a file that records events associated with
+particular dates. The name of the diary file is specified by the
+variable @code{diary-file}. The default is @file{~/.emacs.d/diary},
+though for compatibility with older versions Emacs will use
+@file{~/diary} if it exists.
+@ignore
+@c I don't think this is relevant any more. The utility doesn't seem
+@c to be part of the default install on GNU/Linux machines these days.
+@c When I tried it with my basic diary file, it just died with an error.
+The @code{calendar} utility program supports a subset of the format
+allowed by the Emacs diary facilities, so you can use that utility to
+view the diary file, with reasonable results aside from the entries it
+cannot understand.
+@end ignore
+
+ Each entry in the diary file describes one event and consists of one
+or more lines. An entry always begins with a date specification at the
+left margin. The rest of the entry is simply text to describe the
+event. If the entry has more than one line, then the lines after the
+first must begin with whitespace to indicate they continue a previous
+entry. Lines that do not begin with valid dates and do not continue a
+preceding entry are ignored. Here's an example:
@example
-12/22/1988 Twentieth wedding anniversary!!
-&1/1. Happy New Year!
+12/22/2015 Twentieth wedding anniversary!
10/22 Ruth's birthday.
* 21, *: Payday
Tuesday--weekly meeting with grad students at 10am
Supowit, Shen, Bitner, and Kapoor to attend.
1/13/89 Friday the thirteenth!!
-&thu 4pm squash game with Lloyd.
+thu 4pm squash game with Lloyd.
mar 16 Dad's birthday
-April 15, 1989 Income tax due.
-&* 15 time cards due.
+April 15, 2016 Income tax due.
+* 15 time cards due.
@end example
@noindent
-This format is essentially the same as the one used by the system's
-@command{calendar} utility. This example uses extra spaces to align
-the event descriptions of most of the entries. Such formatting is
-purely a matter of taste.
+This example uses extra spaces to align the event descriptions of most
+of the entries. Such formatting is purely a matter of taste.
- Although you probably will start by creating a diary manually, Emacs
-provides a number of commands to let you view, add, and change diary
-entries.
+ 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:
-@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.
-* Special Diary Entries:: Anniversaries, blocks of dates, cyclic entries, etc.
-@end menu
+@example
+02/11/2012
+ Bill B. visits Princeton today
+ 2pm Cognitive Studies Committee meeting
+ 2:30-5:30 Liz at Lawrenceville
+ 4:00pm Dentist appt
+ 7:30pm Dinner at George's
+ 8:00-10:00pm concert
+@end example
+
+@noindent
+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.
@node Displaying the Diary
@subsection Displaying the Diary
following, key bindings refer to the Calendar buffer.
@table @kbd
-@item d
+@item mouse-3 Diary
+@itemx d
Display all diary entries for the selected date
(@code{diary-view-entries}).
-@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}).
@item m
@kindex d @r{(Calendar mode)}
@findex diary-view-entries
@vindex calendar-view-diary-initially-flag
- Displaying the diary entries with @kbd{d} shows in a separate window
+ Displaying the diary entries with @kbd{d} shows in a separate buffer
the diary entries for the selected date in the calendar. The mode line
-of the new window shows the date of the diary entries. Holidays are
+of the new buffer 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
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-3} 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
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}.
+@xref{Calendar Customizing,,, emacs-xtra, Specialized Emacs Features}.
@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
+ This command applies both to the months that are currently visible
+and to those that subsequently become visible after 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{calendar-mark-diary-entries-flag} is non-@code{nil}, creating or
updating the calendar marks diary dates automatically.
+@vindex diary-nonmarking-symbol
+ To prevent an individual diary entry from being marked in the
+calendar, insert the string that @code{diary-nonmarking-symbol}
+specifies (the default is @samp{&}) at the beginning of the entry,
+before the date. This has no effect on display of the entry in the
+diary buffer; it only affects marks on dates in the calendar.
+Nonmarking entries can be useful for generic entries that would
+otherwise mark many different dates.
+
@kindex s @r{(Calendar mode)}
@findex diary-show-all-entries
To see the full diary file, rather than just some of the entries, use
few days as well; the variable @code{diary-number-of-entries} specifies
how many days to include.
@iftex
-@inforef{Diary Customizing,, emacs-xtra}.
+@xref{Diary Customizing,,, emacs-xtra, Specialized Emacs Features}.
@end iftex
@ifnottex
@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.
+automatically displays a window with the day's diary entries when you
+start Emacs.
@findex diary-mail-entries
@vindex diary-mail-days
- Many users like to receive notice of events in their diary as email.
-To send such mail to yourself, use the command @kbd{M-x
+ Some people like to receive email notifications of events in their
+diary. To send such mail to yourself, use the command @kbd{M-x
diary-mail-entries}. A prefix argument specifies how many days
(starting with today) to check; otherwise, the variable
@code{diary-mail-days} says how many days.
-@node Format of Diary File
-@subsection The Diary File
-@cindex diary file
-
-@vindex diary-file
- Your @dfn{diary file} is a file that records events associated with
-particular dates. The name of the diary file is specified by the
-variable @code{diary-file}; @file{~/diary} is the default. The
-@code{calendar} utility program supports a subset of the format allowed
-by the Emacs diary facilities, so you can use that utility to view the
-diary file, with reasonable results aside from the entries it cannot
-understand.
-
- Each entry in the diary file describes one event and consists of one
-or more lines. An entry always begins with a date specification at the
-left margin. The rest of the entry is simply text to describe the
-event. If the entry has more than one line, then the lines after the
-first must begin with whitespace to indicate they continue a previous
-entry. Lines that do not begin with valid dates and do not continue a
-preceding entry are ignored.
-
- 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
- Bill B. visits Princeton today
- 2pm Cognitive Studies Committee meeting
- 2:30-5:30 Liz at Lawrenceville
- 4:00pm Dentist appt
- 7:30pm Dinner at George's
- 8:00-10:00pm concert
-@end example
-
-@noindent
-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.
-
-@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
month, year) and ISO order (year, month, day) as options.
@example
-4/20/93 Switch-over to new tabulation system
+4/20/12 Switch-over to new tabulation system
apr. 25 Start tabulating annual results
4/30 Results for April are due
*/25 Monthly cycle finishes
Friday Don't leave without backing up files
@end example
- The first entry appears only once, on April 20, 1993. The second and
+ The first entry appears only once, on April 20, 2012. The second and
third appear every year on the specified dates, and the fourth uses a
wildcard (asterisk) for the month, so it appears on the 25th of every
month. The final entry appears every week on Friday.
This must be followed by a nondigit. In the date itself, @var{month}
and @var{day} are numbers of one or two digits. The optional @var{year}
is also a number, and may be abbreviated to the last two digits; that
-is, you can use @samp{11/12/1989} or @samp{11/12/89}.
+is, you can use @samp{11/12/2012} or @samp{11/12/12}.
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
A date may be @dfn{generic}; that is, partially unspecified. Then the
entry applies to all dates that match the specification. If the date
does not contain a year, it is generic and applies to any year.
-Alternatively, @var{month}, @var{day}, or @var{year} can be a @samp{*};
+Alternatively, @var{month}, @var{day}, or @var{year} can be @samp{*};
this matches any month, day, or year, respectively. Thus, a diary entry
@samp{3/*/*} matches any day in March of any year; so does @samp{march
*}.
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}.
+@xref{Non-Gregorian Diary,,, emacs-xtra, Specialized Emacs Features}.
@end iftex
@ifnottex
@xref{Non-Gregorian Diary}.
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.
+make a nonmarking diary entry, give a prefix argument to the command.
For example, @kbd{C-u i w} makes a nonmarking weekly diary entry.
When you modify the diary file, be sure to save the file before
@findex diary-anniversary
@example
-%%(diary-anniversary 10 31 1948) Arthur's birthday
+%%(diary-anniversary 10 31 1988) Arthur's birthday
@end example
@noindent
-This entry applies to October 31 in any year after 1948; @samp{10 31
-1948} specifies the date. (If you are using the European or ISO
+This entry applies to October 31 in any year after 1988; @samp{10 31
+1988} specifies the date. (If you are using the European or ISO
calendar style, the input order of month, day and year is different.)
The reason this expression requires a beginning year is that advanced
diary functions can use it to calculate the number of elapsed years.
A @dfn{block} diary entry applies to a specified range of consecutive
dates. Here is a block diary entry that applies to all dates from June
-24, 1990 through July 10, 1990:
+24, 2012 through July 10, 2012:
@findex diary-block
@example
-%%(diary-block 6 24 1990 7 10 1990) Vacation
+%%(diary-block 6 24 2012 7 10 2012) Vacation
@end example
@noindent
-The @samp{6 24 1990} indicates the starting date and the @samp{7 10 1990}
+The @samp{6 24 2012} indicates the starting date and the @samp{7 10 2012}
indicates the stopping date. (Again, if you are using the European or ISO
calendar style, the input order of month, day and year is different.)
@findex diary-cyclic
@example
-%%(diary-cyclic 50 3 1 1990) Renew medication
+%%(diary-cyclic 50 3 1 2012) Renew medication
@end example
@noindent
-This entry applies to March 1, 1990 and every 50th day following;
-@samp{3 1 1990} specifies the starting date. (If you are using the
+This entry applies to March 1, 2012 and every 50th day following;
+@samp{3 1 2012} specifies the starting date. (If you are using the
European or ISO calendar style, the input order of month, day and year
is different.)
All three of these commands make marking diary entries. To insert a
-nonmarking entry, give a numeric argument to the command. For example,
+nonmarking entry, give a prefix argument to the command. For example,
@kbd{C-u i a} makes a nonmarking anniversary diary entry.
- Marking sexp diary entries in the calendar is @emph{extremely}
-time-consuming, since every date visible in the calendar window must be
-individually checked. So it's a good idea to make sexp diary entries
-nonmarking (with @samp{&}) when possible.
+ Marking sexp diary entries in the calendar can be time-consuming,
+since every date visible in the calendar window must be individually
+checked. So it's a good idea to make sexp diary entries nonmarking
+(with @samp{&}) when possible.
Another sophisticated kind of sexp entry, a @dfn{floating} diary entry,
specifies a regularly occurring event by offsets specified in days,
@noindent
The 11 specifies November (the eleventh month), the 4 specifies Thursday
(the fourth day of the week, where Sunday is numbered zero), and the
-second 4 specifies the fourth Thursday (1 would mean ``first,'' 2 would
-mean ``second,'' @minus{}2 would mean ``second-to-last,'' and so on).
+second 4 specifies the fourth Thursday (1 would mean ``first'', 2 would
+mean ``second'', @minus{}2 would mean ``second-to-last'', and so on).
The month can be a single month or a list of months. Thus you could change
the 11 above to @samp{'(1 2 3)} and have the entry apply to the last
Thursday of January, February, and March. If the month is @code{t}, the
-entry applies to all months of the year.@refill
+entry applies to all months of the year.
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.
@iftex
-@inforef{Sexp Diary Entries,, emacs-xtra}.
+@xref{Sexp Diary Entries,,, emacs-xtra, Specialized Emacs Features}.
@end iftex
@ifnottex
@xref{Sexp Diary Entries}.
@vindex appt-audible
@vindex appt-display-mode-line
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 in advance
+that an 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}, the warning includes an audible
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 (default 12)
-in advance to warn you.
+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
@code{appt-display-diary} to @code{nil}. The appointments list is
also updated whenever the diary file (or a file it includes; see
@iftex
-@inforef{Fancy Diary Display,, emacs-xtra})
+@ref{Fancy Diary Display,,, emacs-xtra, Specialized Emacs Features})
@end iftex
@ifnottex
@ref{Fancy Diary Display})
messages. While viewing such a message in Rmail or Gnus, do @kbd{M-x
diary-from-outlook} to import the entry. You can make this command
recognize additional appointment message formats by customizing the
-variable @code{diary-outlook-formats}.
+variable @code{diary-outlook-formats}. Other mail clients can set
+@code{diary-from-outlook-function} to an appropriate value.
+@c FIXME the name of the RFC is hardly very relevant.
@cindex iCalendar support
The icalendar package allows you to transfer data between your Emacs
-diary file and iCalendar files, which are defined in ``RFC
+diary file and iCalendar files, which are defined in @cite{RFC
2445---Internet Calendaring and Scheduling Core Object Specification
-(iCalendar)'' (as well as the earlier vCalendar format).
+(iCalendar)} (as well as the earlier vCalendar format).
-@c Importing works for ``ordinary'' (i.e. non-recurring) events, but
+@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
@findex icalendar-import-buffer
The command @code{icalendar-import-buffer} extracts
-iCalendar data from the current buffer and adds it to your (default)
+iCalendar data from the current buffer and adds it to your
diary file. This function is also suitable for automatic extraction of
iCalendar data; for example with the Rmail mail client one could use:
You can use an @code{#include} directive to add the import file contents
to the main diary file, if these are different files.
@iftex
-@inforef{Fancy Diary Display,, emacs-xtra}.
+@xref{Fancy Diary Display,,, emacs-xtra, Specialized Emacs Features}.
@end iftex
@ifnottex
@xref{Fancy Diary Display}.
Use @code{icalendar-export-file} to interactively export an entire
Emacs diary file to iCalendar format. To export only a part of a diary
file, mark the relevant area, and call @code{icalendar-export-region}.
-In both cases the result is appended to the target file.
+In both cases, Emacs appends the result to the target file.
@node Daylight Saving
@section Daylight Saving Time
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.''
+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
+ 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 and, by default, Emacs asks
-you. You can, however, set customize the value of the variable
+you. You can, however, 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
+@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. You can specify a
+called @file{~/.emacs.d/timelog}. 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