@c This is part of the Emacs manual. -*- coding: utf-8 -*-
-@c Copyright (C) 1985-1987, 1993-1995, 1997, 2000-2015 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 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
(@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).
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
@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
@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
@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.