@c This is part of the Emacs manual. -*- coding: utf-8 -*-
-@c Copyright (C) 1985-1987, 1993-1995, 1997, 2000-2014 Free Software
+@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
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}.
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.
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
@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 a range, set the mark on one
-date using @kbd{C-SPC}, move point to another date, and type @kbd{M-=}
+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
-@itemx S-SPC
+@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.
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 @LaTeX{}
(@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
(starting always with the selected one).
and can display them. You can add your own holidays to the default list.
@table @kbd
-@item Mouse-3 Holidays
+@item mouse-3 Holidays
@itemx h
Display holidays for the selected date
(@code{calendar-cursor-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-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.
times of sunrise and sunset for any date.
@table @kbd
-@item Mouse-3 Sunrise/sunset
+@item mouse-3 Sunrise/sunset
@itemx S
Display times of sunrise and sunset for the selected date
(@code{calendar-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
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
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 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
+19 days each. The four remaining intercalary days are placed
between the 18th and 19th months.
@node To Other Calendar
@table @kbd
@kindex p @r{(Calendar mode)}
@findex calendar-print-other-dates
-@item Mouse-3 Other calendars
+@item mouse-3 Other calendars
@itemx p o
Display the selected date in various other calendars.
(@code{calendar-print-other-dates}).
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. You can also use @kbd{Mouse-3} and
+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
@findex calendar-hebrew-list-yahrzeits
@cindex yahrzeits
One common issue concerning the Hebrew calendar is the computation
-of the anniversary of a date of death, called a ``yahrzeit''. The Emacs
+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
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/2012 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, 2013 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 separate
-@command{calendar} utility that is present on some Unix systems. 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 Mouse-3 Diary
+@item mouse-3 Diary
@itemx d
Display all diary entries for the selected date
(@code{diary-view-entries}).
@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
@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
(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/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.
-
-@vindex diary-nonmarking-symbol
- You can inhibit the marking of certain diary entries in the calendar
-window; to do this, insert the string that
-@code{diary-nonmarking-symbol} specifies (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 only
-affects 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
@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.
@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
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.