@c This is part of the Emacs manual. -*- coding: utf-8 -*-
-@c Copyright (C) 1985-1987, 1993-1995, 1997, 2000-2013 Free Software
+@c Copyright (C) 1985-1987, 1993-1995, 1997, 2000-2015 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
@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
+@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).
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
(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.
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
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
+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
@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
this command first asks you for the date of death and the range of
years, and then displays the list of yahrzeit dates.
-@c FIXME move to emacs-xtra.
-@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 by 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{Completion Exit}) 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/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.
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
@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.
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