[Top][All Lists]
[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[Emacs-diffs] Changes to calendar.texi
|
From: |
Glenn Morris |
|
Subject: |
[Emacs-diffs] Changes to calendar.texi |
|
Date: |
Thu, 06 Sep 2007 04:44:36 +0000 |
CVSROOT: /sources/emacs
Module name: emacs
Changes by: Glenn Morris <gm> 07/09/06 04:44:36
Index: calendar.texi
===================================================================
RCS file: calendar.texi
diff -N calendar.texi
--- /dev/null 1 Jan 1970 00:00:00 -0000
+++ calendar.texi 6 Sep 2007 04:44:36 -0000 1.1
@@ -0,0 +1,1687 @@
address@hidden This is part of the Emacs manual.
address@hidden Copyright (C) 1985, 1986, 1987, 1993, 1994, 1995, 1997, 2000,
2001,
address@hidden 2002, 2003, 2004, 2005, 2006, 2007 Free Software Foundation,
Inc.
address@hidden See file emacs.texi for copying conditions.
address@hidden Calendar/Diary, Gnus, Dired, Top
address@hidden The Calendar and the Diary
address@hidden calendar
address@hidden 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-2} in the calendar brings up a menu of operations on a
+particular date; @kbd{Mouse-3} brings up a menu of commonly used
+calendar features that are independent of any particular date. To exit
+the calendar, type @kbd{q}.
+
address@hidden
+ This chapter describes the basic calendar features.
address@hidden Calendar/Diary Usage,, emacs-xtra}, for information
+about more specialized features.
address@hidden iftex
+
address@hidden
+* 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.
address@hidden
+* Advanced Calendar/Diary Usage:: Advanced Calendar/Diary customization.
address@hidden ifnottex
address@hidden menu
+
address@hidden Calendar Motion
address@hidden Movement in the Calendar
+
address@hidden 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.
+
address@hidden
+* 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.
address@hidden menu
+
address@hidden Calendar Unit Motion
address@hidden 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.
+
address@hidden @kbd
address@hidden C-f
+Move point one day forward (@code{calendar-forward-day}).
address@hidden C-b
+Move point one day backward (@code{calendar-backward-day}).
address@hidden C-n
+Move point one week forward (@code{calendar-forward-week}).
address@hidden C-p
+Move point one week backward (@code{calendar-backward-week}).
address@hidden address@hidden
+Move point one month forward (@code{calendar-forward-month}).
address@hidden address@hidden
+Move point one month backward (@code{calendar-backward-month}).
address@hidden C-x ]
+Move point one year forward (@code{calendar-forward-year}).
address@hidden C-x [
+Move point one year backward (@code{calendar-backward-year}).
address@hidden table
+
address@hidden C-f @r{(Calendar mode)}
address@hidden calendar-forward-day
address@hidden C-b @r{(Calendar mode)}
address@hidden calendar-backward-day
address@hidden C-n @r{(Calendar mode)}
address@hidden calendar-forward-week
address@hidden C-p @r{(Calendar mode)}
address@hidden 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
address@hidden, just as they normally are in other modes.
+
address@hidden address@hidden @r{(Calendar mode)}
address@hidden calendar-forward-month
address@hidden address@hidden @r{(Calendar mode)}
address@hidden calendar-backward-month
address@hidden C-x ] @r{(Calendar mode)}
address@hidden calendar-forward-year
address@hidden C-x [ @r{(Calendar mode)}
address@hidden calendar-forward-year
+ The commands for motion by months and years work like those for
+weeks, but move a larger distance. The month commands @address@hidden and
address@hidden@{} move forward or backward by an entire month. The year
+commands @kbd{C-x ]} and @address@hidden [}} 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,
address@hidden C-f} moves point 100 days forward from its present location.
+
address@hidden Move to Beginning or End
address@hidden 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 beginning or end of a week, month or
+year:
+
address@hidden @kbd
address@hidden C-a @r{(Calendar mode)}
address@hidden calendar-beginning-of-week
address@hidden C-a
+Move point to start of week (@code{calendar-beginning-of-week}).
address@hidden C-e @r{(Calendar mode)}
address@hidden calendar-end-of-week
address@hidden C-e
+Move point to end of week (@code{calendar-end-of-week}).
address@hidden M-a @r{(Calendar mode)}
address@hidden calendar-beginning-of-month
address@hidden M-a
+Move point to start of month (@code{calendar-beginning-of-month}).
address@hidden M-e @r{(Calendar mode)}
address@hidden calendar-end-of-month
address@hidden M-e
+Move point to end of month (@code{calendar-end-of-month}).
address@hidden M-< @r{(Calendar mode)}
address@hidden calendar-beginning-of-year
address@hidden M-<
+Move point to start of year (@code{calendar-beginning-of-year}).
address@hidden M-> @r{(Calendar mode)}
address@hidden calendar-end-of-year
address@hidden M->
+Move point to end of year (@code{calendar-end-of-year}).
address@hidden 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.
+
address@hidden calendar-week-start-day
address@hidden weeks, which day they start on
address@hidden 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.
+
address@hidden Specified Dates
address@hidden Specified Dates
+
+ Calendar mode provides commands for moving to a particular date
+specified in various ways.
+
address@hidden @kbd
address@hidden g d
+Move point to specified date (@code{calendar-goto-date}).
address@hidden g D
+Move point to specified day of year (@code{calendar-goto-day-of-year}).
address@hidden g w
+Move point to specified week of year (@code{calendar-goto-iso-week}).
address@hidden o
+Center calendar around specified month (@code{calendar-other-month}).
address@hidden .
+Move point to today's date (@code{calendar-goto-today}).
address@hidden table
+
address@hidden g d @r{(Calendar mode)}
address@hidden 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}.
+
address@hidden g D @r{(Calendar mode)}
address@hidden calendar-goto-day-of-year
address@hidden g w @r{(Calendar mode)}
address@hidden calendar-goto-iso-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-goto-iso-week}) prompts for a year and week number,
+and moves to that week.
+
address@hidden o @r{(Calendar mode)}
address@hidden calendar-other-month
+ @kbd{o} (@code{calendar-other-month}) prompts for a month and year,
+then centers the three-month calendar around that month.
+
address@hidden . @r{(Calendar mode)}
address@hidden calendar-goto-today
+ You can return to today's date with @kbd{.}@:
+(@code{calendar-goto-today}).
+
address@hidden Scroll Calendar
address@hidden Scrolling in the Calendar
+
address@hidden 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.
+
address@hidden @kbd
address@hidden >
+Scroll calendar one month forward (@code{scroll-calendar-left}).
address@hidden <
+Scroll calendar one month backward (@code{scroll-calendar-right}).
address@hidden C-v
address@hidden @key{NEXT}
+Scroll calendar three months forward
+(@code{scroll-calendar-left-three-months}).
address@hidden M-v
address@hidden @key{PRIOR}
+Scroll calendar three months backward
+(@code{scroll-calendar-right-three-months}).
address@hidden table
+
address@hidden > @r{(Calendar mode)}
address@hidden scroll-calendar-left
address@hidden < @r{(Calendar mode)}
address@hidden scroll-calendar-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.
+
address@hidden C-v @r{(Calendar mode)}
address@hidden scroll-calendar-left-three-months
address@hidden M-v @r{(Calendar mode)}
address@hidden scroll-calendar-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
address@hidden and @kbd{M-v}, just as they are in other modes.
+
address@hidden Counting Days
address@hidden Counting Days
+
address@hidden @kbd
address@hidden M-=
+Display the number of days in the current region
+(@code{calendar-count-days-region}).
address@hidden table
+
address@hidden M-= @r{(Calendar mode)}
address@hidden calendar-count-days-region
+ To determine the number of days in the region, type @kbd{M-=}
+(@code{calendar-count-days-region}). The numbers of days shown is
address@hidden; that is, it includes the days specified by mark and
+point.
+
address@hidden General Calendar
address@hidden Miscellaneous Calendar Commands
+
address@hidden @kbd
address@hidden p d
+Display day-in-year (@code{calendar-print-day-of-year}).
address@hidden C-c C-l
+Regenerate the calendar window (@code{redraw-calendar}).
address@hidden SPC
+Scroll the next window up (@code{scroll-other-window}).
address@hidden DEL
+Scroll the next window down (@code{scroll-other-window-down}).
address@hidden q
+Exit from calendar (@code{exit-calendar}).
address@hidden table
+
address@hidden p d @r{(Calendar mode)}
address@hidden day of year
address@hidden 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.
+
address@hidden C-c C-l @r{(Calendar mode)}
address@hidden redraw-calendar
+ If the calendar window text gets corrupted, type @kbd{C-c C-l}
+(@code{redraw-calendar}) to redraw it. (This can only happen if you use
+non-Calendar-mode editing commands.)
+
address@hidden 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 up or down, respectively. This is handy when you display a list
+of holidays or diary entries in another window.
+
address@hidden q @r{(Calendar mode)}
address@hidden exit-calendar
+ To exit from the calendar, type @kbd{q} (@code{exit-calendar}). This
+buries all buffers related to the calendar, selecting other buffers.
+(If a frame contains a dedicated calendar window, exiting from the
+calendar iconifies that frame.)
+
address@hidden Writing Calendar Files
address@hidden Writing Calendar Files
+
+ These packages produce files of various formats containing calendar
+and diary entries, for display purposes.
+
address@hidden 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 @address@hidden@var{mm}.html}, where @var{yyyy} and
address@hidden 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.
+
address@hidden 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
address@hidden for relevant style settings).
+
address@hidden t @r{(Calendar mode)}
address@hidden @kbd
address@hidden H m
+Generate a one-month calendar (@code{cal-html-cursor-month}).
address@hidden 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.
address@hidden table
+
+ If the variable @code{cal-html-print-day-number-flag} is
address@hidden, 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.
+
address@hidden calendar and address@hidden
+ The Calendar address@hidden commands produce a buffer of address@hidden 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.
+
address@hidden t @r{(Calendar mode)}
address@hidden @kbd
address@hidden t m
+Generate a one-month calendar (@code{cal-tex-cursor-month}).
address@hidden t M
+Generate a sideways-printing one-month calendar
+(@code{cal-tex-cursor-month-landscape}).
address@hidden t d
+Generate a one-day calendar
+(@code{cal-tex-cursor-day}).
address@hidden t w 1
+Generate a one-page calendar for one week
+(@code{cal-tex-cursor-week}).
address@hidden t w 2
+Generate a two-page calendar for one week
+(@code{cal-tex-cursor-week2}).
address@hidden t w 3
+Generate an ISO-style calendar for one week
+(@code{cal-tex-cursor-week-iso}).
address@hidden t w 4
+Generate a calendar for one Monday-starting week
+(@code{cal-tex-cursor-week-monday}).
address@hidden t f w
+Generate a Filofax-style two-weeks-at-a-glance calendar
+(@code{cal-tex-cursor-filofax-2week}).
address@hidden t f W
+Generate a Filofax-style one-week-at-a-glance calendar
+(@code{cal-tex-cursor-filofax-week}).
address@hidden t y
+Generate a calendar for one year
+(@code{cal-tex-cursor-year}).
address@hidden t Y
+Generate a sideways-printing calendar for one year
+(@code{cal-tex-cursor-year-landscape}).
address@hidden t f y
+Generate a Filofax-style calendar for one year
+(@code{cal-tex-cursor-filofax-year}).
address@hidden 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 address@hidden (the default),
+then the printed calendars show the holidays in @code{calendar-holidays}.
+If the variable @code{cal-tex-diary} is address@hidden (the default is
address@hidden), diary entries are included also (in monthly, filofax, and
+iso-week calendars only). If the variable @code{cal-tex-rules} is
address@hidden (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
address@hidden commands in the preamble of the generated document if you need
+to.
+
address@hidden Holidays
address@hidden Holidays
address@hidden holidays
+
+ The Emacs calendar knows about all major and many minor holidays,
+and can display them.
+
address@hidden @kbd
address@hidden h
+Display holidays for the selected date
+(@code{calendar-cursor-holidays}).
address@hidden Mouse-2 Holidays
+Display any holidays for the date you click on.
address@hidden x
+Mark holidays in the calendar window (@code{mark-calendar-holidays}).
address@hidden u
+Unmark calendar window (@code{calendar-unmark}).
address@hidden a
+List all holidays for the displayed three months in another window
+(@code{list-calendar-holidays}).
address@hidden M-x holidays
+List all holidays for three months around today's date in another
+window.
address@hidden M-x list-holidays
+List holidays in another window for a specified range of years.
address@hidden table
+
address@hidden h @r{(Calendar mode)}
address@hidden calendar-cursor-holidays
address@hidden view-calendar-holidays-initially
+ 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-2} 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.
+
address@hidden x @r{(Calendar mode)}
address@hidden mark-calendar-holidays
address@hidden u @r{(Calendar mode)}
address@hidden calendar-unmark
address@hidden mark-holidays-in-calendar
+ 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 (or places a @samp{*} after these dates, if
+display with multiple faces is not available).
address@hidden
address@hidden Customizing, calendar-holiday-marker, emacs-xtra}.
address@hidden iftex
address@hidden
address@hidden Customizing, calendar-holiday-marker}.
address@hidden 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
address@hidden is address@hidden, creating or
+updating the calendar marks holidays automatically.
+
address@hidden a @r{(Calendar mode)}
address@hidden list-calendar-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.
+
address@hidden 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
address@hidden is address@hidden, 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
+major Christian, Jewish, and Islamic holidays; also the solstices and
+equinoxes.
+
address@hidden list-holidays
+ The command @kbd{M-x list-holidays} displays the list of holidays for
+a range of years. This function asks you for the starting and stopping
+years, and allows you to choose all the holidays or one of several
+categories of holidays. You can use this command even if you don't have
+a calendar window.
+
+ The dates used by Emacs for holidays are based on @emph{current
+practice}, not historical fact. For example Veteran's Day began in
+1919, but is shown in earlier years.
+
address@hidden Sunrise/Sunset
address@hidden Times of Sunrise and Sunset
address@hidden sunrise and sunset
+
+ Special calendar commands can tell you, to within a minute or two, the
+times of sunrise and sunset for any date.
+
address@hidden @kbd
address@hidden S
+Display times of sunrise and sunset for the selected date
+(@code{calendar-sunrise-sunset}).
address@hidden Mouse-2 Sunrise/sunset
+Display times of sunrise and sunset for the date you click on.
address@hidden M-x sunrise-sunset
+Display times of sunrise and sunset for today's date.
address@hidden C-u M-x sunrise-sunset
+Display times of sunrise and sunset for a specified date.
address@hidden table
+
address@hidden S @r{(Calendar mode)}
address@hidden calendar-sunrise-sunset
address@hidden 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
address@hidden Alternatively, click @kbd{Mouse-2} on the date, then choose
address@hidden/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
+other than today, use @kbd{C-u M-x sunrise-sunset}, which prompts for
+the year, month, and day.
+
+ You can display the times of sunrise and sunset for any location and
+any date with @kbd{C-u C-u M-x sunrise-sunset}. This asks you for a
+longitude, latitude, number of minutes difference from Coordinated
+Universal Time, and date, and then tells you the times of sunrise and
+sunset for that location on that date.
+
+ Because the times of sunrise and sunset depend on the location on
+earth, you need to tell Emacs your latitude, longitude, and location
+name before using these commands. Here is an example of what to set:
+
address@hidden calendar-location-name
address@hidden calendar-longitude
address@hidden calendar-latitude
address@hidden
+(setq calendar-latitude 40.1)
+(setq calendar-longitude -88.2)
+(setq calendar-location-name "Urbana, IL")
address@hidden example
+
address@hidden
+Use one decimal place in the values of @code{calendar-latitude} and
address@hidden
+
+ Your time zone also affects the local time of sunrise and sunset.
+Emacs usually gets time zone information from the operating system, but
+if these values are not what you want (or if the operating system does
+not supply them), you must set them yourself. Here is an example:
+
address@hidden calendar-time-zone
address@hidden calendar-standard-time-zone-name
address@hidden calendar-daylight-time-zone-name
address@hidden
+(setq calendar-time-zone -360)
+(setq calendar-standard-time-zone-name "CST")
+(setq calendar-daylight-time-zone-name "CDT")
address@hidden example
+
address@hidden
+The value of @code{calendar-time-zone} is the number of minutes
+difference between your local standard time and Coordinated Universal
+Time (Greenwich time). The values of
address@hidden and
address@hidden are the abbreviations used in
+your time zone. Emacs displays the times of sunrise and sunset
address@hidden for daylight saving time}. @xref{Daylight Saving},
+for how daylight saving time is determined.
+
+ 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
address@hidden file which sets them properly for the typical location
+of most users of that machine. @xref{Init File}.
+
address@hidden Lunar Phases
address@hidden Phases of the Moon
address@hidden phases of the moon
address@hidden moon, phases of
+
+ 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.''
+
address@hidden @kbd
address@hidden M
+Display the dates and times for all the quarters of the moon for the
+three-month period shown (@code{calendar-phases-of-moon}).
address@hidden M-x phases-of-moon
+Display dates and times of the quarters of the moon for three months around
+today's date.
address@hidden table
+
address@hidden M @r{(Calendar mode)}
address@hidden calendar-phases-of-moon
+ Within the calendar, use the @kbd{M} command to display a separate
+buffer of the phases of the moon for the current three-month range. The
+dates and times listed are accurate to within a few minutes.
+
address@hidden phases-of-moon
+ Outside the calendar, use the command @kbd{M-x phases-of-moon} to
+display the list of the phases of the moon for the current month and the
+preceding and succeeding months. For information about a different
+month, use @kbd{C-u M-x phases-of-moon}, which prompts for the month and
+year.
+
+ The dates and times given for the phases of the moon are given in
+local time (corrected for daylight saving, when appropriate); but if
+the variable @code{calendar-time-zone} is void, Coordinated Universal
+Time (the Greenwich time zone) is used. @xref{Daylight Saving}.
+
address@hidden Other Calendars
address@hidden Conversion To and From Other Calendars
+
address@hidden Gregorian calendar
+ The Emacs calendar displayed is @emph{always} the Gregorian calendar,
+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.
+
+ While Emacs cannot display other calendars, it can convert dates to
+and from several other calendars.
+
address@hidden
+* Calendar Systems:: The calendars Emacs understands
+ (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.
address@hidden menu
+
address@hidden Calendar Systems
address@hidden Supported Calendar Systems
+
address@hidden ISO commercial calendar
+ The ISO commercial calendar is used largely in Europe.
+
address@hidden Julian calendar
+ The Julian calendar, named after Julius Caesar, was the one used in Europe
+throughout medieval times, and in many countries up until the nineteenth
+century.
+
address@hidden Julian day numbers
address@hidden astronomical day numbers
+ Astronomers use a simple counting of days elapsed since noon, Monday,
+January 1, 4713 B.C. on the Julian calendar. The number of days elapsed
+is called the @dfn{Julian day number} or the @dfn{Astronomical day number}.
+
address@hidden Hebrew calendar
+ The Hebrew calendar is used by tradition in the Jewish religion. The
+Emacs calendar program uses the Hebrew calendar to determine the dates
+of Jewish holidays. Hebrew calendar dates begin and end at sunset.
+
address@hidden Islamic calendar
+ The Islamic calendar is used in many predominantly Islamic countries.
+Emacs uses it to determine the dates of Islamic holidays. There is no
+universal agreement in the Islamic world about the calendar; Emacs uses
+a widely accepted version, but the precise dates of Islamic holidays
+often depend on proclamation by religious authorities, not on
+calculations. As a consequence, the actual dates of observance can vary
+slightly from the dates computed by Emacs. Islamic calendar dates begin
+and end at sunset.
+
address@hidden French Revolutionary calendar
+ The French Revolutionary calendar was created by the Jacobins after the 1789
+revolution, to represent a more secular and nature-based view of the annual
+cycle, and to install a 10-day week in a rationalization measure similar to
+the metric system. The French government officially abandoned this
+calendar at the end of 1805.
+
address@hidden Mayan calendar
+ The Maya of Central America used three separate, overlapping calendar
+systems, the @emph{long count}, the @emph{tzolkin}, and the @emph{haab}.
+Emacs knows about all three of these calendars. Experts dispute the
+exact correlation between the Mayan calendar and our calendar; Emacs uses the
+Goodman-Martinez-Thompson correlation in its calculations.
+
address@hidden Coptic calendar
address@hidden Ethiopic calendar
+ The Copts use a calendar based on the ancient Egyptian solar calendar.
+Their calendar consists of twelve 30-day months followed by an extra
+five-day period. Once every fourth year they add a leap day to this
+extra period to make it six days. The Ethiopic calendar is identical in
+structure, but has different year numbers and month names.
+
address@hidden Persian calendar
+ The Persians use a solar calendar based on a design of Omar Khayyam.
+Their calendar consists of twelve months of which the first six have 31
+days, the next five have 30 days, and the last has 29 in ordinary years
+and 30 in leap years. Leap years occur in a complicated pattern every
+four or five years.
+The calendar implemented here is the arithmetical Persian calendar
+championed by Birashk, based on a 2,820-year cycle. It differs from
+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.
+
address@hidden 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
+repeated in a cycle of sixty.
+
address@hidden To Other Calendar
address@hidden Converting To Other Calendars
+
+ The following commands describe the selected date (the date at point)
+in various other calendar systems:
+
address@hidden @kbd
address@hidden Mouse-2 Other calendars
+Display the date that you click on, expressed in various other calendars.
address@hidden p @r{(Calendar mode)}
address@hidden calendar-print-iso-date
address@hidden p c
+Display ISO commercial calendar equivalent for selected day
+(@code{calendar-print-iso-date}).
address@hidden calendar-print-julian-date
address@hidden p j
+Display Julian date for selected day (@code{calendar-print-julian-date}).
address@hidden calendar-print-astro-day-number
address@hidden p a
+Display astronomical (Julian) day number for selected day
+(@code{calendar-print-astro-day-number}).
address@hidden calendar-print-hebrew-date
address@hidden p h
+Display Hebrew date for selected day (@code{calendar-print-hebrew-date}).
address@hidden calendar-print-islamic-date
address@hidden p i
+Display Islamic date for selected day (@code{calendar-print-islamic-date}).
address@hidden calendar-print-french-date
address@hidden p f
+Display French Revolutionary date for selected day
+(@code{calendar-print-french-date}).
address@hidden calendar-print-chinese-date
address@hidden p C
+Display Chinese date for selected day
+(@code{calendar-print-chinese-date}).
address@hidden calendar-print-coptic-date
address@hidden p k
+Display Coptic date for selected day
+(@code{calendar-print-coptic-date}).
address@hidden calendar-print-ethiopic-date
address@hidden p e
+Display Ethiopic date for selected day
+(@code{calendar-print-ethiopic-date}).
address@hidden calendar-print-persian-date
address@hidden p p
+Display Persian date for selected day
+(@code{calendar-print-persian-date}).
address@hidden calendar-print-mayan-date
address@hidden p m
+Display Mayan date for selected day (@code{calendar-print-mayan-date}).
address@hidden table
+
+ If you are using X, the easiest way to translate a date into other
+calendars is to click on it with @kbd{Mouse-2}, 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.
+
address@hidden From Other Calendar
address@hidden Converting From Other Calendars
+
+ You can use the other supported calendars to specify a date to move
+to. This section describes the commands for doing this using calendars
+other than Mayan; for the Mayan calendar, see the following section.
+
address@hidden g @var{char} @r{(Calendar mode)}
address@hidden calendar-goto-iso-date
address@hidden calendar-goto-iso-week
address@hidden calendar-goto-julian-date
address@hidden calendar-goto-astro-day-number
address@hidden calendar-goto-hebrew-date
address@hidden calendar-goto-islamic-date
address@hidden calendar-goto-french-date
address@hidden calendar-goto-chinese-date
address@hidden calendar-goto-persian-date
address@hidden calendar-goto-coptic-date
address@hidden calendar-goto-ethiopic-date
address@hidden @kbd
address@hidden g c
+Move to a date specified in the ISO commercial calendar
+(@code{calendar-goto-iso-date}).
address@hidden g w
+Move to a week specified in the ISO commercial calendar
+(@code{calendar-goto-iso-week}).
address@hidden g j
+Move to a date specified in the Julian calendar
+(@code{calendar-goto-julian-date}).
address@hidden g a
+Move to a date specified with an astronomical (Julian) day number
+(@code{calendar-goto-astro-day-number}).
address@hidden g h
+Move to a date specified in the Hebrew calendar
+(@code{calendar-goto-hebrew-date}).
address@hidden g i
+Move to a date specified in the Islamic calendar
+(@code{calendar-goto-islamic-date}).
address@hidden g f
+Move to a date specified in the French Revolutionary calendar
+(@code{calendar-goto-french-date}).
address@hidden g C
+Move to a date specified in the Chinese calendar
+(@code{calendar-goto-chinese-date}).
address@hidden g p
+Move to a date specified in the Persian calendar
+(@code{calendar-goto-persian-date}).
address@hidden g k
+Move to a date specified in the Coptic calendar
+(@code{calendar-goto-coptic-date}).
address@hidden g e
+Move to a date specified in the Ethiopic calendar
+(@code{calendar-goto-ethiopic-date}).
address@hidden 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{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.
+
address@hidden list-yahrzeit-dates
address@hidden yahrzeits
+ One common question concerning the Hebrew calendar is the computation
+of the anniversary of a date of death, called a ``yahrzeit.'' The Emacs
+calendar includes a facility for such calculations. If you are in the
+calendar, the command @kbd{M-x list-yahrzeit-dates} asks you for a
+range of years and then displays a list of the yahrzeit dates for those
+years for the date given by point. If you are not in the calendar,
+this command first asks you for the date of death and the range of
+years, and then displays the list of yahrzeit dates.
+
address@hidden Mayan Calendar
address@hidden Converting from the Mayan Calendar
+
+ Here are the commands to select dates based on the Mayan calendar:
+
address@hidden @kbd
address@hidden g m l
+Move to a date specified by the long count calendar
+(@code{calendar-goto-mayan-long-count-date}).
address@hidden g m n t
+Move to the next occurrence of a place in the
+tzolkin calendar (@code{calendar-next-tzolkin-date}).
address@hidden g m p t
+Move to the previous occurrence of a place in the
+tzolkin calendar (@code{calendar-previous-tzolkin-date}).
address@hidden g m n h
+Move to the next occurrence of a place in the
+haab calendar (@code{calendar-next-haab-date}).
address@hidden g m p h
+Move to the previous occurrence of a place in the
+haab calendar (@code{calendar-previous-haab-date}).
address@hidden g m n c
+Move to the next occurrence of a place in the
+calendar round (@code{calendar-next-calendar-round-date}).
address@hidden g m p c
+Move to the previous occurrence of a place in the
+calendar round (@code{calendar-previous-calendar-round-date}).
address@hidden table
+
address@hidden 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:
+
address@hidden
+1 kin = 1 day@ @ @ 1 uinal = 20 kin@ @ @ 1 tun = 18 uinal
+1 katun = 20 tun@ @ @ 1 baktun = 20 katun
address@hidden display
+
address@hidden g m @r{(Calendar mode)}
address@hidden calendar-goto-mayan-long-count-date
address@hidden
+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
address@hidden m l} command, type the Mayan long count date with the baktun,
+katun, tun, uinal, and kin separated by periods.
+
address@hidden calendar-previous-tzolkin-date
address@hidden calendar-next-tzolkin-date
address@hidden 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.
+
address@hidden calendar-previous-haab-date
address@hidden calendar-next-haab-date
address@hidden 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
address@hidden 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.
+
address@hidden This is omitted because it is too long for smallbook format.
address@hidden @findex calendar-previous-calendar-round-date
address@hidden calendar-next-calendar-round-date
address@hidden 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
address@hidden 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.
+
address@hidden Diary
address@hidden The Diary
address@hidden 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
+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
address@hidden; @file{~/diary} is the default. A sample diary file
+is (note that the file format is essentially the same as that used by
+the external shell utility @samp{calendar}):
+
address@hidden
+12/22/1988 Twentieth wedding anniversary!!
+&1/1. Happy New Year!
+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.
+mar 16 Dad's birthday
+April 15, 1989 Income tax due.
+&* 15 time cards due.
address@hidden example
+
address@hidden
+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.
+
address@hidden
+* 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.
address@hidden menu
+
address@hidden Displaying the Diary
address@hidden Displaying the Diary
+
+ Once you have created a diary file, you can use the calendar to view
+it. You can also view today's events outside of Calendar mode.
+
address@hidden @kbd
address@hidden d
+Display all diary entries for the selected date
+(@code{diary-view-entries}).
address@hidden Mouse-2 Diary
+Display all diary entries for the date you click on.
address@hidden s
+Display the entire diary file (@code{diary-show-all-entries}).
address@hidden m
+Mark all visible dates that have diary entries
+(@code{mark-diary-entries}).
address@hidden u
+Unmark the calendar window (@code{calendar-unmark}).
address@hidden M-x print-diary-entries
+Print hard copy of the diary display as it appears.
address@hidden M-x diary
+Display all diary entries for today's date.
address@hidden M-x diary-mail-entries
+Mail yourself email reminders about upcoming diary entries.
address@hidden table
+
address@hidden d @r{(Calendar mode)}
address@hidden diary-view-entries
address@hidden view-diary-entries-initially
+ Displaying the diary entries with @kbd{d} shows in a separate window
+the diary entries for the selected date in the calendar. The mode line
+of the new window shows the date of the diary entries and any holidays
+that fall on that date. If you specify a numeric argument with @kbd{d},
+it shows all the diary entries for that many successive days. Thus,
address@hidden d} displays all the entries for the selected date and for the
+following day.
+
+ Another way to display the diary entries for a date is to click
address@hidden on the date, and then choose @kbd{Diary entries} from
+the menu that appears. If the variable
address@hidden is address@hidden, creating the
+calendar lists the diary entries for the current date (provided the
+current date is visible).
+
address@hidden m @r{(Calendar mode)}
address@hidden mark-diary-entries
address@hidden mark-diary-entries-in-calendar
+ To get a broader view of which days are mentioned in the diary, use
+the @kbd{m} command. This displays the dates that have diary entries in
+a different face (or places a @samp{+} after these dates, if display
+with multiple faces is not available).
address@hidden
address@hidden Customizing, diary-entry-marker, emacs-xtra}.
address@hidden iftex
address@hidden
address@hidden Customizing, diary-entry-marker}.
address@hidden 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
+turns off holiday marks (@pxref{Holidays}). If the variable
address@hidden is address@hidden, creating or
+updating the calendar marks diary dates automatically.
+
address@hidden s @r{(Calendar mode)}
address@hidden diary-show-all-entries
+ To see the full diary file, rather than just some of the entries, use
+the @kbd{s} command.
+
+ Display of selected diary entries uses the selective display feature
+to hide entries that don't apply. The diary buffer as you see it is
+an illusion, so simply printing the buffer does not print what you see
+on your screen. There is a special command to print hard copy of the
+diary buffer @emph{as it appears}; this command is @kbd{M-x
+print-diary-entries}. It sends the data directly to the printer. You
+can customize it like @code{lpr-region} (@pxref{Printing}).
+
address@hidden diary
+ The command @kbd{M-x diary} displays the diary entries for the current
+date, independently of the calendar display, and optionally for the next
+few days as well; the variable @code{number-of-diary-entries} specifies
+how many days to include.
address@hidden
address@hidden Customizing,, emacs-xtra}.
address@hidden iftex
address@hidden
address@hidden Customizing, number-of-diary-entries}.
address@hidden 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. The mode line of the displayed window shows the date and
+any holidays that fall on that date.
+
address@hidden diary-mail-entries
address@hidden 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
+diary-mail-entries}. A prefix argument specifies how many days
+(starting with today) to check; otherwise, the variable
address@hidden says how many days.
+
address@hidden Format of Diary File
address@hidden The Diary File
address@hidden diary file
+
address@hidden 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
address@hidden 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 inhibit the marking of certain diary entries in the calendar
+window; to do this, insert an ampersand (@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.
+
+ If the first line of a diary entry consists only of the date or day
+name with no following blanks or punctuation, then the diary window
+display doesn't include that line; only the continuation lines appear.
+For example, this entry:
+
address@hidden
+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
address@hidden example
+
address@hidden
+appears in the diary window without the date line at the beginning.
+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.
+
+ You can edit the diary entries as they appear in the window, but it is
+important to remember that the buffer displayed contains the @emph{entire}
+diary file, with portions of it concealed from view. This means, for
+instance, that the @kbd{C-f} (@code{forward-char}) command can put point
+at what appears to be the end of the line, but what is in reality the
+middle of some concealed line.
+
+ @emph{Be careful when editing the diary entries!} Inserting
+additional lines or adding/deleting characters in the middle of a
+visible line cannot cause problems, but editing at the end of a line may
+not do what you expect. Deleting a line may delete other invisible
+entries that follow it. Before editing the diary, it is best to display
+the entire file with @kbd{s} (@code{diary-show-all-entries}).
+
address@hidden Date Formats
address@hidden Date Formats
+
+ Here are some sample diary entries, illustrating different ways of
+formatting a date. The examples all show dates in American order
+(month, day, year), but Calendar mode supports European order (day,
+month, year) as an option.
+
address@hidden
+4/20/93 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
address@hidden example
+
+ The first entry appears only once, on April 20, 1993. 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.
+
+ You can use just numbers to express a date, as in
address@hidden@var{month}/@var{day}} or @address@hidden/@var{day}/@var{year}}.
+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}.
+
+ Dates can also have the form @address@hidden @var{day}} or
address@hidden@var{monthname} @var{day}, @var{year}}, where the month's name can
+be spelled in full or abbreviated (with or without a period). The
+preferred abbreviations can be controlled using the variables
address@hidden, @code{calendar-month-abbrev-array}, and
address@hidden The default is to use the first three
+letters of a name as its abbreviation. Case is not significant.
+
+ 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{*};
+this matches any month, day, or year, respectively. Thus, a diary entry
address@hidden/*/*} matches any day in March of any year; so does @samp{march
+*}.
+
address@hidden european-calendar-style
address@hidden european-calendar
address@hidden american-calendar
+ If you prefer the European style of writing dates---in which the day
+comes before the month---type @kbd{M-x european-calendar} while in the
+calendar, or set the variable @code{european-calendar-style} to @code{t}
+with @kbd{M-x customize}, or @emph{before} using any calendar or diary
+command. This mode interprets all dates in the diary in the European
+manner, and also uses European style for displaying diary dates. (Note
+that there is no comma after the @var{monthname} in the European style.)
+To go back to the (default) American style of writing dates, type
address@hidden american-calendar}.
+
+ You can use the name of a day of the week as a generic date which
+applies to any date falling on that day of the week. You can abbreviate
+the day of the week to three letters (with or without a period) or spell
+it in full; case is not significant.
+
address@hidden Adding to Diary
address@hidden Commands to Add to the Diary
+
+ While in the calendar, there are several commands to create diary
+entries:
+
address@hidden @kbd
address@hidden i d
+Add a diary entry for the selected date (@code{insert-diary-entry}).
address@hidden i w
+Add a diary entry for the selected day of the week
(@code{insert-weekly-diary-entry}).
address@hidden i m
+Add a diary entry for the selected day of the month
(@code{insert-monthly-diary-entry}).
address@hidden i y
+Add a diary entry for the selected day of the year
(@code{insert-yearly-diary-entry}).
address@hidden table
+
address@hidden i d @r{(Calendar mode)}
address@hidden insert-diary-entry
+ You can make a diary entry for a specific date by selecting that date
+in the calendar window and typing the @kbd{i d} command. This command
+displays the end of your diary file in another window and inserts the
+date; you can then type the rest of the diary entry.
+
address@hidden i w @r{(Calendar mode)}
address@hidden insert-weekly-diary-entry
address@hidden i m @r{(Calendar mode)}
address@hidden insert-monthly-diary-entry
address@hidden i y @r{(Calendar mode)}
address@hidden insert-yearly-diary-entry
+ If you want to make a diary entry that applies to a specific day of
+the week, select that day of the week (any occurrence will do) and type
address@hidden w}. This inserts the day-of-week as a generic date; you can then
+type the rest of the diary entry. You can make a monthly diary entry in
+the same fashion: select the day of the month, use the @kbd{i m}
+command, and type the rest of the entry. Similarly, you can insert a
+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.
+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
+exiting Emacs. Saving the diary file after using any of the above
+insertion commands will automatically update the diary marks in the
+calendar window, if appropriate. You can use the command
address@hidden to force an update at any time.
+
address@hidden Special Diary Entries
address@hidden Special Diary Entries
+
+ In addition to entries based on calendar dates, the diary file can
+contain @dfn{sexp entries} for regular events such as anniversaries.
+These entries are based on Lisp expressions (sexps) that Emacs evaluates
+as it scans the diary file. Instead of a date, a sexp entry contains
address@hidden followed by a Lisp expression which must begin and end with
+parentheses. The Lisp expression determines which dates the entry
+applies to.
+
+ Calendar mode provides commands to insert certain commonly used
+sexp entries:
+
address@hidden @kbd
address@hidden i a
+Add an anniversary diary entry for the selected date
+(@code{insert-anniversary-diary-entry}).
address@hidden i b
+Add a block diary entry for the current region
+(@code{insert-block-diary-entry}).
address@hidden i c
+Add a cyclic diary entry starting at the date
+(@code{insert-cyclic-diary-entry}).
address@hidden table
+
address@hidden i a @r{(Calendar mode)}
address@hidden insert-anniversary-diary-entry
+ If you want to make a diary entry that applies to the anniversary of a
+specific date, move point to that date and use the @kbd{i a} command.
+This displays the end of your diary file in another window and inserts
+the anniversary description; you can then type the rest of the diary
+entry. The entry looks like this:
+
address@hidden diary-anniversary
address@hidden
+%%(diary-anniversary 10 31 1948) Arthur's birthday
address@hidden example
+
address@hidden
+This entry applies to October 31 in any year after 1948; @samp{10 31
+1948} specifies the date. (If you are using the European calendar
+style, the month and day are interchanged.) 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:
+
address@hidden diary-block
address@hidden
+%%(diary-block 6 24 1990 7 10 1990) Vacation
address@hidden example
+
address@hidden
+The @samp{6 24 1990} indicates the starting date and the @samp{7 10 1990}
+indicates the stopping date. (Again, if you are using the European calendar
+style, the month and day are interchanged.)
+
address@hidden i b @r{(Calendar mode)}
address@hidden insert-block-diary-entry
+ To insert a block entry, place point and the mark on the two
+dates that begin and end the range, and type @kbd{i b}. This command
+displays the end of your diary file in another window and inserts the
+block description; you can then type the diary entry.
+
address@hidden i c @r{(Calendar mode)}
address@hidden insert-cyclic-diary-entry
+ @dfn{Cyclic} diary entries repeat after a fixed interval of days. To
+create one, select the starting date and use the @kbd{i c} command. The
+command prompts for the length of interval, then inserts the entry,
+which looks like this:
+
address@hidden diary-cyclic
address@hidden
+%%(diary-cyclic 50 3 1 1990) Renew medication
address@hidden example
+
address@hidden
+This entry applies to March 1, 1990 and every 50th day following;
address@hidden 1 1990} specifies the starting date. (If you are using the
+European calendar style, the month and day are interchanged.)
+
+ All three of these commands make marking diary entries. To insert a
+nonmarking entry, give a numeric argument to the command. For example,
address@hidden 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.
+
+ Another sophisticated kind of sexp entry, a @dfn{floating} diary entry,
+specifies a regularly occurring event by offsets specified in days,
+weeks, and months. It is comparable to a crontab entry interpreted by
+the @code{cron} utility. Here is a nonmarking, floating diary entry
+that applies to the last Thursday in November:
+
address@hidden diary-float
address@hidden
+&%%(diary-float 11 4 -1) American Thanksgiving
address@hidden example
+
address@hidden
+The 11 specifies November (the eleventh month), the 4 specifies Thursday
+(the fourth day of the week, where Sunday is numbered zero), and the
address@hidden specifies ``last'' (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 address@hidden
+
+ 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.
address@hidden
address@hidden Diary Entries,, emacs-xtra}.
address@hidden iftex
address@hidden
address@hidden Diary Entries}.
address@hidden ifnottex
+
address@hidden Appointments
address@hidden Appointments
address@hidden appointment notification
+
address@hidden appt-display-format
address@hidden appt-audible
address@hidden 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
+to the appointment by displaying a message in your chosen format, as
+specified by the variable @code{appt-display-format}. If the value of
address@hidden is address@hidden, the warning includes an audible
+reminder. In addition, if @code{appt-display-mode-line} is
address@hidden, Emacs displays the number of minutes to the
+appointment on the mode line.
+
address@hidden appt-display-duration
address@hidden appt-disp-window-function
address@hidden appt-delete-window-function
+ If @code{appt-display-format} has the value @code{window}, then the
+variable @code{appt-display-duration} controls how long the reminder
+window is visible for; and the variables
address@hidden and @code{appt-delete-window-function}
+give the names of functions used to create and destroy the window,
+respectively.
+
address@hidden 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.
+
+ For example, suppose the diary file contains these lines:
+
address@hidden
+Monday
+ 9:30am Coffee break
+ 12:00pm Lunch
address@hidden example
+
address@hidden appt-message-warning-time
address@hidden
+Then on Mondays, you will be reminded at around 9:20am about your
+coffee break and at around 11:50am about lunch. The variable
address@hidden specifies how many minutes in advance
+to warn you; its default value is 12 (12 minutes).
+
+ 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
+European/military style. You need not be consistent; your diary file
+can have a mixture of the two styles. Times must be at the beginning
+of lines if they are to be recognized.
+
address@hidden appt-display-diary
+ Emacs updates the appointments list from the diary file
+automatically just after midnight. You can force an update at any
+time by re-enabling appointment notification. Both these actions also
+display the day's diary buffer, unless you set
address@hidden to @code{nil}. The appointments list is
+also updated whenever the diary file is saved.
+
address@hidden appt-add
address@hidden appt-delete
address@hidden alarm clock
+ You can also use the appointment notification facility like an alarm
+clock. The command @kbd{M-x appt-add} adds entries to the appointment
+list without affecting your diary file. You delete entries from the
+appointment list with @kbd{M-x appt-delete}.
+
address@hidden Importing Diary
address@hidden Importing and Exporting Diary Entries
+
+ You can transfer diary entries between Emacs diary files and a
+variety of other formats.
+
address@hidden diary-outlook-formats
+ You can import diary entries from Outlook-generated appointment
+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}.
+
address@hidden iCalendar support
+ The icalendar package allows you to transfer data between your Emacs
+diary file and iCalendar files, which are defined in ``RFC
+2445---Internet Calendaring and Scheduling Core Object Specification
+(iCalendar)'' (as well as the earlier vCalendar format).
+
+ Importing works for ``ordinary'' (i.e. non-recurring) events, but
+(at present) may not work correctly (if at all) for recurring events.
+Exporting of diary files into iCalendar files should work correctly
+for most diary entries. This feature is a work in progress, so the
+commands may evolve in future.
+
address@hidden icalendar-import-buffer
+ The command @code{icalendar-import-buffer} extracts
+iCalendar data from the current buffer and adds it to your (default)
+diary file. This function is also suitable for automatic extraction of
+iCalendar data; for example with the Rmail mail client one could use:
+
address@hidden
+(add-hook 'rmail-show-message-hook 'icalendar-import-buffer)
address@hidden example
+
address@hidden icalendar-import-file
+ The command @code{icalendar-import-file} imports an iCalendar file
+and adds the results to an Emacs diary file. For example:
+
address@hidden
+(icalendar-import-file "/here/is/calendar.ics"
+ "/there/goes/ical-diary")
address@hidden example
+
address@hidden
+You can use an @code{#include} directive to add the import file contents
+to the main diary file, if these are different files.
address@hidden
address@hidden Diary Display,, emacs-xtra}.
address@hidden iftex
address@hidden
address@hidden Diary Display}.
address@hidden ifnottex
+
+
address@hidden icalendar-export-file, icalendar-export-region
+ 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.
+
address@hidden Daylight Saving
address@hidden Daylight Saving Time
address@hidden daylight saving time
+
+ Emacs understands the difference between standard time and daylight
+saving time---the times given for sunrise, sunset, solstices,
+equinoxes, and the phases of the moon take that into account. The rules
+for daylight saving time vary from place to place and have also varied
+historically from year to year. To do the job properly, Emacs needs to
+know which rules to use.
+
address@hidden calendar-daylight-savings-starts
address@hidden calendar-daylight-savings-ends
+ Some operating systems keep track of the rules that apply to the place
+where you are; on these systems, Emacs gets the information it needs
+from the system automatically. If some or all of this information is
+missing, Emacs fills in the gaps with the rules currently used in
+Cambridge, Massachusetts. If the resulting rules are not what you want,
+you can tell Emacs the rules to use by setting certain variables:
address@hidden and
address@hidden
+
+ These values should be Lisp expressions that refer to the variable
address@hidden, and evaluate to the Gregorian date on which daylight
+saving time starts or (respectively) ends, in the form of a list
address@hidden(@var{month} @var{day} @var{year})}. The values should be
address@hidden if your area does not use daylight saving time.
+
+ Emacs uses these expressions to determine the starting date of
+daylight saving time for the holiday list and for correcting times of
+day in the solar and lunar calculations.
+
+ The values for Cambridge, Massachusetts are as follows:
+
address@hidden
+(calendar-nth-named-day 2 0 3 year)
+(calendar-nth-named-day 1 0 11 year)
address@hidden example
+
address@hidden
+That is, the second 0th day (Sunday) of the third month (March) in
+the year specified by @code{year}, and the first Sunday of the eleventh month
+(November) of that year. If daylight saving time were
+changed to start on October 1, you would set
address@hidden to this:
+
address@hidden
+(list 10 1 year)
address@hidden example
+
+ If there is no daylight saving time at your location, or if you want
+all times in standard time, set @code{calendar-daylight-savings-starts}
+and @code{calendar-daylight-savings-ends} to @code{nil}.
+
address@hidden calendar-daylight-time-offset
+ The variable @code{calendar-daylight-time-offset} specifies the
+difference between daylight saving time and standard time, measured in
+minutes. The value for Cambridge, Massachusetts is 60.
+
address@hidden @vindex calendar-daylight-savings-starts-time too long!
address@hidden calendar-daylight-savings-ends-time
+ Finally, the two variables
address@hidden and
address@hidden specify the number of
+minutes after midnight local time when the transition to and from
+daylight saving time should occur. For Cambridge, Massachusetts both
+variables' values are 120.
+
address@hidden Time Intervals
address@hidden Summing Time Intervals
address@hidden time intervals, summing
address@hidden summing time intervals
address@hidden timeclock
+
+ The timeclock feature adds up time intervals, so you can (for
+instance) keep track of how much time you spend working on particular
+projects.
+
address@hidden timeclock-in
address@hidden timeclock-out
address@hidden timeclock-change
address@hidden timeclock-workday-remaining
address@hidden timeclock-when-to-leave
+ Use the @kbd{M-x timeclock-in} command when you start working on a
+project, and @kbd{M-x timeclock-out} command when you're done. Each
+time you do this, it adds one time interval to the record of the
+project. You can change to working on a different project with @kbd{M-x
+timeclock-change}.
+
+ Once you've collected data from a number of time intervals, you can use
address@hidden 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.''
+
address@hidden timeclock-modeline-display
address@hidden timeclock-modeline-display
+ If you want Emacs to display the amount of time ``left'' of your
+workday in the mode line, either customize the
address@hidden variable and set its value to
address@hidden, or invoke the @kbd{M-x timeclock-modeline-display} command.
+
address@hidden 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 the value of the variable
address@hidden to @code{nil} (via @kbd{M-x
+customize}) 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.
+
address@hidden @file{.timelog} file
address@hidden timeclock-file
address@hidden 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
+different name for this file by customizing the variable
address@hidden If you edit the timeclock file manually, or if
+you change the value of any of timeclock's customizable variables, you
+should run the command @kbd{M-x timeclock-reread-log} to update the
+data in Emacs from the file.
+
address@hidden
address@hidden cal-xtra.texi
address@hidden ifnottex
+
address@hidden
+ arch-tag: 4531ef09-9df3-449d-9c52-2b5a4a337f92
address@hidden ignore