Hyphen and dash fixes in texinfo files.

[bpt/emacs.git] / doc / emacs / calendar.texi

@c This is part of the Emacs manual.  -*- coding: iso-latin-1 -*-
@c Copyright (C) 1985-1987, 1993-1995, 1997, 2000-2012
@c   Free Software Foundation, Inc.
@c See file emacs.texi for copying conditions.
@node Calendar/Diary
@chapter The Calendar and the Diary
@cindex calendar
@findex calendar

  Emacs provides the functions of a desk calendar, with a diary of
planned or past events.  It also has facilities for managing your
appointments, and keeping track of how much time you spend working on
certain projects.

  To enter the calendar, type @kbd{M-x calendar}; this displays a
three-month calendar centered on the current month, with point on the
current date.  With a numeric argument, as in @kbd{C-u M-x calendar}, it
prompts you for the month and year to be the center of the three-month
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
calendar features that are independent of any particular date.  To exit
the calendar, type @kbd{q}.

@iftex
  This chapter describes the basic calendar features.
For more advanced topics,
@pxref{Advanced Calendar/Diary Usage,,, emacs-xtra, Specialized Emacs Features}.
@end iftex

@menu
* Calendar Motion::     Moving through the calendar; selecting a date.
* Scroll Calendar::     Bringing earlier or later months onto the screen.
* Counting Days::       How many days are there between two dates?
* General Calendar::    Exiting or recomputing the calendar.
* Writing Calendar Files:: Writing calendars to files of various formats.
* Holidays::            Displaying dates of holidays.
* Sunrise/Sunset::      Displaying local times of sunrise and sunset.
* Lunar Phases::        Displaying phases of the moon.
* Other Calendars::     Converting dates to other calendar systems.
* Diary::               Displaying events from your diary.
* Appointments::        Reminders when it's time to do something.
* Importing Diary::     Converting diary events to/from other formats.
* Daylight Saving::     How to specify when daylight saving time is active.
* Time Intervals::      Keeping track of time intervals.
@ifnottex
* Advanced Calendar/Diary Usage:: Advanced Calendar/Diary customization.
@end ifnottex
@end menu

@node Calendar Motion
@section Movement in the Calendar

@cindex moving inside the calendar
  Calendar mode provides commands to move through the calendar in
logical units of time such as days, weeks, months, and years.  If you
move outside the three months originally displayed, the calendar
display ``scrolls'' automatically through time to make the selected
date visible.  Moving to a date lets you view its holidays or diary
entries, or convert it to other calendars; moving by long time periods
is also useful simply to scroll the calendar.

@menu
* Calendar Unit Motion::      Moving by days, weeks, months, and years.
* Move to Beginning or End::  Moving to start/end of weeks, months, and years.
* Specified Dates::           Moving to the current date or another
                                specific date.
@end menu

@node Calendar Unit Motion
@subsection Motion by Standard Lengths of Time

  The commands for movement in the calendar buffer parallel the
commands for movement in text.  You can move forward and backward by
days, weeks, months, and years.

@table @kbd
@item C-f
Move point one day forward (@code{calendar-forward-day}).
@item C-b
Move point one day backward (@code{calendar-backward-day}).
@item C-n
Move point one week forward (@code{calendar-forward-week}).
@item C-p
Move point one week backward (@code{calendar-backward-week}).
@item M-@}
Move point one month forward (@code{calendar-forward-month}).
@item M-@{
Move point one month backward (@code{calendar-backward-month}).
@item C-x ]
Move point one year forward (@code{calendar-forward-year}).
@item C-x [
Move point one year backward (@code{calendar-backward-year}).
@end table

@kindex C-f @r{(Calendar mode)}
@findex calendar-forward-day
@kindex C-b @r{(Calendar mode)}
@findex calendar-backward-day
@kindex C-n @r{(Calendar mode)}
@findex calendar-forward-week
@kindex C-p @r{(Calendar mode)}
@findex calendar-backward-week
  The day and week commands are natural analogues of the usual Emacs
commands for moving by characters and by lines.  Just as @kbd{C-n}
usually moves to the same column in the following line, in Calendar
mode it moves to the same day in the following week.  And @kbd{C-p}
moves to the same day in the previous week.

  The arrow keys are equivalent to @kbd{C-f}, @kbd{C-b}, @kbd{C-n} and
@kbd{C-p}, just as they normally are in other modes.

@kindex M-@} @r{(Calendar mode)}
@findex calendar-forward-month
@kindex M-@{ @r{(Calendar mode)}
@findex calendar-backward-month
@kindex C-x ] @r{(Calendar mode)}
@findex calendar-forward-year
@kindex C-x [ @r{(Calendar mode)}
@findex calendar-forward-year
  The commands for motion by months and years work like those for
weeks, but move a larger distance.  The month commands @kbd{M-@}} and
@kbd{M-@{} move forward or backward by an entire month.  The year
commands @kbd{C-x ]} and @w{@kbd{C-x [}} move forward or backward a
whole year.

  The easiest way to remember these commands is to consider months and
years analogous to paragraphs and pages of text, respectively.  But
the commands themselves are not quite analogous.  The ordinary Emacs
paragraph commands move to the beginning or end of a paragraph,
whereas these month and year commands move by an entire month or an
entire year, keeping the same date within the month or year.

  All these commands accept a numeric argument as a repeat count.
For convenience, the digit keys and the minus sign specify numeric
arguments in Calendar mode even without the Meta modifier.  For example,
@kbd{100 C-f} moves point 100 days forward from its present location.

@node Move to Beginning or End
@subsection Beginning or End of Week, Month or Year

  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 start or end of a week, month or year:

@table @kbd
@kindex C-a @r{(Calendar mode)}
@findex calendar-beginning-of-week
@item C-a
Move point to start of week (@code{calendar-beginning-of-week}).
@kindex C-e @r{(Calendar mode)}
@findex calendar-end-of-week
@item C-e
Move point to end of week (@code{calendar-end-of-week}).
@kindex M-a @r{(Calendar mode)}
@findex calendar-beginning-of-month
@item M-a
Move point to start of month (@code{calendar-beginning-of-month}).
@kindex M-e @r{(Calendar mode)}
@findex calendar-end-of-month
@item M-e
Move point to end of month (@code{calendar-end-of-month}).
@kindex M-< @r{(Calendar mode)}
@findex calendar-beginning-of-year
@item M-<
Move point to start of year (@code{calendar-beginning-of-year}).
@kindex M-> @r{(Calendar mode)}
@findex calendar-end-of-year
@item M->
Move point to end of year (@code{calendar-end-of-year}).
@end table

  These commands also take numeric arguments as repeat counts, with the
repeat count indicating how many weeks, months, or years to move
backward or forward.

@vindex calendar-week-start-day
@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.

@node Specified Dates
@subsection Specified Dates

  Calendar mode provides commands for moving to a particular date
specified in various ways.

@table @kbd
@item g d
Move point to specified date (@code{calendar-goto-date}).
@item g D
Move point to specified day of year (@code{calendar-goto-day-of-year}).
@item g w
Move point to specified week of year (@code{calendar-iso-goto-week}).
@item o
Center calendar around specified month (@code{calendar-other-month}).
@item .
Move point to today's date (@code{calendar-goto-today}).
@end table

@kindex g d @r{(Calendar mode)}
@findex calendar-goto-date
  @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}.

@kindex g D @r{(Calendar mode)}
@findex calendar-goto-day-of-year
@kindex g w @r{(Calendar mode)}
@findex calendar-iso-goto-week
  @kbd{g D} (@code{calendar-goto-day-of-year}) prompts for a year and
day number, and moves to that date.  Negative day numbers count
backward from the end of the year.  @kbd{g w}
(@code{calendar-iso-goto-week}) prompts for a year and week number,
and moves to that week.

@kindex o @r{(Calendar mode)}
@findex calendar-other-month
  @kbd{o} (@code{calendar-other-month}) prompts for a month and year,
then centers the three-month calendar around that month.

@kindex . @r{(Calendar mode)}
@findex calendar-goto-today
  You can return to today's date with @kbd{.}@:
(@code{calendar-goto-today}).

@node Scroll Calendar
@section Scrolling in the Calendar

@cindex scrolling in the calendar
  The calendar display scrolls automatically through time when you
move out of the visible portion.  You can also scroll it manually.
Imagine that the calendar window contains a long strip of paper with
the months on it.  Scrolling the calendar means moving the strip
horizontally, so that new months become visible in the window.

@table @kbd
@item >
Scroll calendar one month forward (@code{calendar-scroll-left}).
@item <
Scroll calendar one month backward (@code{calendar-scroll-right}).
@item C-v
@itemx @key{next}
Scroll forward by three months (@code{calendar-scroll-left-three-months}).
@item M-v
@itemx @key{prior}
Scroll backward by three months (@code{calendar-scroll-right-three-months}).
@end table

@kindex > @r{(Calendar mode)}
@findex calendar-scroll-left
@kindex < @r{(Calendar mode)}
@findex calendar-scroll-right
  The most basic calendar scroll commands scroll by one month at a
time.  This means that there are two months of overlap between the
display before the command and the display after.  @kbd{>} scrolls the
calendar contents one month forward in time.  @kbd{<} scrolls the
contents one month backwards in time.

@kindex C-v @r{(Calendar mode)}
@findex calendar-scroll-left-three-months
@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
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
by four, typing @kbd{C-u C-v} scrolls the calendar forward by a year and
typing @kbd{C-u M-v} scrolls the calendar backward by a year.

  The function keys @key{next} and @key{prior} are equivalent to
@kbd{C-v} and @kbd{M-v}, just as they are in other modes.

@node Counting Days
@section Counting Days

@table @kbd
@item M-=
Display the number of days in the current region
(@code{calendar-count-days-region}).
@end table

@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-=}
(@code{calendar-count-days-region}).  The numbers of days shown is
@emph{inclusive}; that is, it includes the days specified by mark and
point.

@node General Calendar
@section Miscellaneous Calendar Commands

@table @kbd
@item p d
Display day-in-year (@code{calendar-print-day-of-year}).
@item C-c C-l
Regenerate the calendar window (@code{calendar-redraw}).
@item SPC
Scroll the next window up (@code{scroll-other-window}).
@item DEL
Scroll the next window down (@code{scroll-other-window-down}).
@item q
Exit from calendar (@code{calendar-exit}).
@end table

@kindex p d @r{(Calendar mode)}
@cindex day of year
@findex calendar-print-day-of-year
  To display the number of days elapsed since the start of the year, or
the number of days remaining in the year, type the @kbd{p d} command
(@code{calendar-print-day-of-year}).  This displays both of those
numbers in the echo area.  The count of days elapsed includes the
selected date.  The count of days remaining does not include that
date.

@kindex C-c C-l @r{(Calendar mode)}
@findex calendar-redraw
  If the calendar window text gets corrupted, type @kbd{C-c C-l}
(@code{calendar-redraw}) to redraw it.  (This can only happen if you use
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
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.

@kindex q @r{(Calendar mode)}
@findex exit-calendar
@vindex calendar-remove-frame-by-deleting
  To exit from the calendar, type @kbd{q} (@code{calendar-exit}).  This
buries all buffers related to the calendar, selecting other buffers.
(If a frame contains a dedicated calendar window, exiting from the
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 @LaTeX{} files.

@cindex calendar and HTML
  The Calendar HTML commands produce files of HTML code that contain
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
HTML tags (for example: this is a diary entry with <font
color=''red''>some red text</font>).  You can change the overall
appearance of the displayed HTML pages (for example, the color of
various page elements, header styles) via a stylesheet @file{cal.css} in
the directory containing the HTML files (see the value of the variable
@code{cal-html-css-default} for relevant style settings).

@kindex t @r{(Calendar mode)}
@table @kbd
@item H m
Generate a one-month calendar (@code{cal-html-cursor-month}).
@item H y
Generate a calendar file for each month of a year, as well as an index
page (@code{cal-html-cursor-year}).  By default, this command writes
files to a @var{yyyy} subdirectory---if this is altered some hyperlinks
between years will not work.
@end table

  If the variable @code{cal-html-print-day-number-flag} is
non-@code{nil}, then the monthly calendars show the day-of-the-year
number. The variable @code{cal-html-year-index-cols} specifies the
number of columns in the yearly index page.

@cindex calendar and @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.

@kindex t @r{(Calendar mode)}
@table @kbd
@item t m
Generate a one-month calendar (@code{cal-tex-cursor-month}).
@item t M
Generate a sideways-printing one-month calendar
(@code{cal-tex-cursor-month-landscape}).
@item t d
Generate a one-day calendar
(@code{cal-tex-cursor-day}).
@item t w 1
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, with hours
(@code{cal-tex-cursor-week2}).
@item t w 3
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, 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}).
@item t f W
Generate a Filofax-style one-week-at-a-glance calendar
(@code{cal-tex-cursor-filofax-week}).
@item t y
Generate a calendar for one year
(@code{cal-tex-cursor-year}).
@item t Y
Generate a sideways-printing calendar for one year
(@code{cal-tex-cursor-year-landscape}).
@item t f y
Generate a Filofax-style calendar for one year
(@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
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).

  If the variable @code{cal-tex-holidays} is non-@code{nil} (the default),
then the printed calendars show the holidays in @code{calendar-holidays}.
If the variable @code{cal-tex-diary} is non-@code{nil} (the default is
@code{nil}), diary entries are included also (in monthly, filofax, and
iso-week calendars only).  If the variable @code{cal-tex-rules} is
non-@code{nil} (the default is @code{nil}), the calendar displays ruled
pages in styles that have sufficient room.  Consult the documentation of
the individual cal-tex functions to see which calendars support which
features.

  You can use the variable @code{cal-tex-preamble-extra} to insert extra
@LaTeX{} commands in the preamble of the generated document if you need
to.

@node Holidays
@section Holidays
@cindex holidays

  The Emacs calendar knows about many major and minor holidays,
and can display them.  You can add your own holidays to the default list.

@table @kbd
@item Mouse-3 Holidays
@itemx h
Display holidays for the selected date
(@code{calendar-cursor-holidays}).
@item x
Mark holidays in the calendar window (@code{calendar-mark-holidays}).
@item u
Unmark calendar window (@code{calendar-unmark}).
@item a
List all holidays for the displayed three months in another window
(@code{calendar-list-holidays}).
@item M-x holidays
List all holidays for three months around today's date in another
window.
@item M-x list-holidays
List holidays in another window for a specified range of years.
@end table

@kindex h @r{(Calendar mode)}
@findex 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}
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.

@kindex x @r{(Calendar mode)}
@findex calendar-mark-holidays
@kindex u @r{(Calendar mode)}
@findex calendar-unmark
@vindex calendar-mark-holidays-flag
  To view the distribution of holidays for all the dates shown in the
calendar, use the @kbd{x} command.  This displays the dates that are
holidays in a different face.
@iftex
@xref{Calendar Customizing,,, emacs-xtra, Specialized Emacs Features}.
@end iftex
@ifnottex
@xref{Calendar Customizing, calendar-holiday-marker}.
@end ifnottex
  The command applies both to the currently visible months and to
other months that subsequently become visible by scrolling.  To turn
marking off and erase the current marks, type @kbd{u}, which also
erases any diary marks (@pxref{Diary}).  If the variable
@code{calendar-mark-holidays-flag} is non-@code{nil}, creating or
updating the calendar marks holidays automatically.

@kindex a @r{(Calendar mode)}
@findex calendar-list-holidays
  To get even more detailed information, use the @kbd{a} command, which
displays a separate buffer containing a list of all holidays in the
current three-month range.  You can use @key{SPC} and @key{DEL} in the
calendar window to scroll that list up and down, respectively.

@findex holidays
  The command @kbd{M-x holidays} displays the list of holidays for the
current month and the preceding and succeeding months; this works even
if you don't have a calendar window.  If the variable
@code{calendar-view-holidays-initially-flag} is non-@code{nil}, creating
the calendar displays holidays in this way.  If you want the list of
holidays centered around a different month, use @kbd{C-u M-x
holidays}, which prompts for the month and year.

  The holidays known to Emacs include United States holidays and the