Mercurial > emacs
changeset 84131:690b13c10f8e
Move to ../doc/emacs/, misc/
| author | Glenn Morris <rgm@gnu.org> |
|---|---|
| date | Thu, 06 Sep 2007 04:34:18 +0000 |
| parents | c34c42ee7597 |
| children | add806db14ca |
| files | man/calendar.texi |
| diffstat | 1 files changed, 0 insertions(+), 1687 deletions(-) [+] |
line wrap: on
line diff
--- a/man/calendar.texi Thu Sep 06 04:34:11 2007 +0000 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,1687 +0,0 @@ -@c This is part of the Emacs manual. -@c Copyright (C) 1985, 1986, 1987, 1993, 1994, 1995, 1997, 2000, 2001, -@c 2002, 2003, 2004, 2005, 2006, 2007 Free Software Foundation, Inc. -@c See file emacs.texi for copying conditions. -@node Calendar/Diary, Gnus, Dired, Top -@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-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}. - -@iftex - This chapter describes the basic calendar features. -@inforef{Advanced Calendar/Diary Usage,, emacs-xtra}, for information -about more specialized 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 beginning 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-goto-iso-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-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. - -@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{scroll-calendar-left}). -@item < -Scroll calendar one month backward (@code{scroll-calendar-right}). -@item C-v -@itemx @key{NEXT} -Scroll calendar three months forward -(@code{scroll-calendar-left-three-months}). -@item M-v -@itemx @key{PRIOR} -Scroll calendar three months backward -(@code{scroll-calendar-right-three-months}). -@end table - -@kindex > @r{(Calendar mode)} -@findex scroll-calendar-left -@kindex < @r{(Calendar mode)} -@findex 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. - -@kindex C-v @r{(Calendar mode)} -@findex scroll-calendar-left-three-months -@kindex M-v @r{(Calendar mode)} -@findex 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 -@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 the region, 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{redraw-calendar}). -@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{exit-calendar}). -@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 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.) - -@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 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 - 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.) - -@node Writing Calendar Files -@section Writing Calendar Files - - These packages produce files of various formats containing calendar -and diary entries, for display purposes. - -@cindex 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 @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. - -@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 La@TeX{} - The Calendar La@TeX{} commands produce a buffer of La@TeX{} 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 -(@code{cal-tex-cursor-week}). -@item t w 2 -Generate a two-page calendar for one week -(@code{cal-tex-cursor-week2}). -@item t w 3 -Generate an ISO-style calendar for one week -(@code{cal-tex-cursor-week-iso}). -@item t w 4 -Generate a calendar for one Monday-starting week -(@code{cal-tex-cursor-week-monday}). -@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 -La@TeX{} commands in the preamble of the generated document if you need -to. - -@node Holidays -@section Holidays -@cindex holidays - - The Emacs calendar knows about all major and many minor holidays, -and can display them. - -@table @kbd -@item h -Display holidays for the selected date -(@code{calendar-cursor-holidays}). -@item Mouse-2 Holidays -Display any holidays for the date you click on. -@item x -Mark holidays in the calendar window (@code{mark-calendar-holidays}). -@item u -Unmark calendar window (@code{calendar-unmark}). -@item a -List all holidays for the displayed three months in another window -(@code{list-calendar-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 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. - -@kindex x @r{(Calendar mode)} -@findex mark-calendar-holidays -@kindex u @r{(Calendar mode)} -@findex calendar-unmark -@vindex 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). -@iftex -@inforef{Calendar Customizing, calendar-holiday-marker, emacs-xtra}. -@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{mark-holidays-in-calendar} is non-@code{nil}, creating or -updating the calendar marks holidays automatically. - -@kindex a @r{(Calendar mode)} -@findex 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. - -@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{view-calendar-holidays-initially} 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 -major Christian, Jewish, and Islamic holidays; also the solstices and -equinoxes. - -@findex 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. - -@node Sunrise/Sunset -@section Times of Sunrise and Sunset -@cindex sunrise and sunset - - Special calendar commands can tell you, to within a minute or two, the -times of sunrise and sunset for any date. - -@table @kbd -@item S -Display times of sunrise and sunset for the selected date -(@code{calendar-sunrise-sunset}). -@item Mouse-2 Sunrise/sunset -Display times of sunrise and sunset for the date you click on. -@item M-x sunrise-sunset -Display times of sunrise and sunset for today's date. -@item C-u M-x sunrise-sunset -Display times of sunrise and sunset for a specified date. -@end table - -@kindex S @r{(Calendar mode)} -@findex calendar-sunrise-sunset -@findex sunrise-sunset - Within the calendar, to display the @emph{local times} of sunrise and -sunset in the echo area, move point to the date you want, and type -@kbd{S}. Alternatively, click @kbd{Mouse-2} on the date, then choose -@samp{Sunrise/sunset} from the menu that appears. The command @kbd{M-x -sunrise-sunset} is available outside the calendar to display this -information for today's date or a specified date. To specify a date -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: - -@vindex calendar-location-name -@vindex calendar-longitude -@vindex calendar-latitude -@example -(setq calendar-latitude 40.1) -(setq calendar-longitude -88.2) -(setq calendar-location-name "Urbana, IL") -@end example - -@noindent -Use one decimal place in the values of @code{calendar-latitude} and -@code{calendar-longitude}. - - 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: - -@vindex calendar-time-zone -@vindex calendar-standard-time-zone-name -@vindex calendar-daylight-time-zone-name -@example -(setq calendar-time-zone -360) -(setq calendar-standard-time-zone-name "CST") -(setq calendar-daylight-time-zone-name "CDT") -@end example - -@noindent -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 -@code{calendar-standard-time-zone-name} and -@code{calendar-daylight-time-zone-name} are the abbreviations used in -your time zone. Emacs displays the times of sunrise and sunset -@emph{corrected 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 -@file{default.el} file which sets them properly for the typical location -of most users of that machine. @xref{Init File}. - -@node Lunar Phases -@section Phases of the Moon -@cindex phases of the moon -@cindex 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.'' - -@table @kbd -@item M -Display the dates and times for all the quarters of the moon for the -three-month period shown (@code{calendar-phases-of-moon}). -@item M-x phases-of-moon -Display dates and times of the quarters of the moon for three months around -today's date. -@end table - -@kindex M @r{(Calendar mode)} -@findex 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. - -@findex 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}. - -@node Other Calendars -@section Conversion To and From Other Calendars - -@cindex Gregorian calendar - The Emacs calendar displayed is @emph{always} the Gregorian calendar, -sometimes called the ``new style'' calendar, which is used in most of -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. - -@menu -* 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. -@end menu - -@node Calendar Systems -@subsection Supported Calendar Systems - -@cindex ISO commercial calendar - The ISO commercial calendar is used largely in Europe. - -@cindex 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. - -@cindex Julian day numbers -@cindex 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}. - -@cindex 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. - -@cindex 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. - -@cindex 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. - -@cindex 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. - -@cindex Coptic calendar -@cindex 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. - -@cindex 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. - -@cindex 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. - -@node To Other Calendar -@subsection Converting To Other Calendars - - The following commands describe the selected date (the date at point) -in various other calendar systems: - -@table @kbd -@item Mouse-2 Other calendars -Display the date that you click on, expressed in various other calendars. -@kindex p @r{(Calendar mode)} -@findex calendar-print-iso-date -@item p c -Display ISO commercial calendar equivalent for selected day -(@code{calendar-print-iso-date}). -@findex calendar-print-julian-date -@item p j -Display Julian date for selected day (@code{calendar-print-julian-date}). -@findex calendar-print-astro-day-number -@item p a -Display astronomical (Julian) day number for selected day -(@code{calendar-print-astro-day-number}). -@findex calendar-print-hebrew-date -@item p h -Display Hebrew date for selected day (@code{calendar-print-hebrew-date}). -@findex calendar-print-islamic-date -@item p i -Display Islamic date for selected day (@code{calendar-print-islamic-date}). -@findex calendar-print-french-date -@item p f -Display French Revolutionary date for selected day -(@code{calendar-print-french-date}). -@findex calendar-print-chinese-date -@item p C -Display Chinese date for selected day -(@code{calendar-print-chinese-date}). -@findex calendar-print-coptic-date -@item p k -Display Coptic date for selected day -(@code{calendar-print-coptic-date}). -@findex calendar-print-ethiopic-date -@item p e -Display Ethiopic date for selected day -(@code{calendar-print-ethiopic-date}). -@findex calendar-print-persian-date -@item p p -Display Persian date for selected day -(@code{calendar-print-persian-date}). -@findex calendar-print-mayan-date -@item p m -Display Mayan date for selected day (@code{calendar-print-mayan-date}). -@end 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. - -@node From Other Calendar -@subsection 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. - -@kindex g @var{char} @r{(Calendar mode)} -@findex calendar-goto-iso-date -@findex calendar-goto-iso-week -@findex calendar-goto-julian-date -@findex calendar-goto-astro-day-number -@findex calendar-goto-hebrew-date -@findex calendar-goto-islamic-date -@findex calendar-goto-french-date -@findex calendar-goto-chinese-date -@findex calendar-goto-persian-date -@findex calendar-goto-coptic-date -@findex calendar-goto-ethiopic-date -@table @kbd -@item g c -Move to a date specified in the ISO commercial calendar -(@code{calendar-goto-iso-date}). -@item g w -Move to a week specified in the ISO commercial calendar -(@code{calendar-goto-iso-week}). -@item g j -Move to a date specified in the Julian calendar -(@code{calendar-goto-julian-date}). -@item g a -Move to a date specified with an astronomical (Julian) day number -(@code{calendar-goto-astro-day-number}). -@item g h -Move to a date specified in the Hebrew calendar -(@code{calendar-goto-hebrew-date}). -@item g i -Move to a date specified in the Islamic calendar -(@code{calendar-goto-islamic-date}). -@item g f -Move to a date specified in the French Revolutionary calendar -(@code{calendar-goto-french-date}). -@item g C -Move to a date specified in the Chinese calendar -(@code{calendar-goto-chinese-date}). -@item g p -Move to a date specified in the Persian calendar -(@code{calendar-goto-persian-date}). -@item g k -Move to a date specified in the Coptic calendar -(@code{calendar-goto-coptic-date}). -@item g e -Move to a date specified in the Ethiopic calendar -(@code{calendar-goto-ethiopic-date}). -@end 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. - -@findex list-yahrzeit-dates -@cindex 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. - -@node Mayan Calendar -@subsection Converting from the Mayan Calendar - - Here are the commands to select dates based on the Mayan calendar: - -@table @kbd -@item g m l -Move to a date specified by the long count calendar -(@code{calendar-goto-mayan-long-count-date}). -@item g m n t -Move to the next occurrence of a place in the -tzolkin calendar (@code{calendar-next-tzolkin-date}). -@item g m p t -Move to the previous occurrence of a place in the -tzolkin calendar (@code{calendar-previous-tzolkin-date}). -@item g m n h -Move to the next occurrence of a place in the -haab calendar (@code{calendar-next-haab-date}). -@item g m p h -Move to the previous occurrence of a place in the -haab calendar (@code{calendar-previous-haab-date}). -@item g m n c -Move to the next occurrence of a place in the -calendar round (@code{calendar-next-calendar-round-date}). -@item g m p c -Move to the previous occurrence of a place in the -calendar round (@code{calendar-previous-calendar-round-date}). -@end table - -@cindex Mayan long count - To understand these commands, you need to understand the Mayan calendars. -The @dfn{long count} is a counting of days with these units: - -@display -1 kin = 1 day@ @ @ 1 uinal = 20 kin@ @ @ 1 tun = 18 uinal -1 katun = 20 tun@ @ @ 1 baktun = 20 katun -@end display - -@kindex g m @r{(Calendar mode)} -@findex calendar-goto-mayan-long-count-date -@noindent -Thus, the long count date 12.16.11.16.6 means 12 baktun, 16 katun, 11 -tun, 16 uinal, and 6 kin. The Emacs calendar can handle Mayan long -count dates as early as 7.17.18.13.3, but no earlier. When you use the -@kbd{g m l} command, type the Mayan long count date with the baktun, -katun, tun, uinal, and kin separated by periods. - -@findex calendar-previous-tzolkin-date -@findex calendar-next-tzolkin-date -@cindex Mayan tzolkin calendar - The Mayan tzolkin calendar is a cycle of 260 days formed by a pair of -independent cycles of 13 and 20 days. Since this cycle repeats -endlessly, Emacs provides commands to move backward and forward to the -previous or next point in the cycle. Type @kbd{g m p t} to go to the -previous tzolkin date; Emacs asks you for a tzolkin date and moves point -to the previous occurrence of that date. Similarly, type @kbd{g m n t} -to go to the next occurrence of a tzolkin date. - -@findex calendar-previous-haab-date -@findex calendar-next-haab-date -@cindex Mayan haab calendar - The Mayan haab calendar is a cycle of 365 days arranged as 18 months -of 20 days each, followed a 5-day monthless period. Like the tzolkin -cycle, this cycle repeats endlessly, and there are commands to move -backward and forward to the previous or next point in the cycle. Type -@kbd{g m p h} to go to the previous haab date; Emacs asks you for a haab -date and moves point to the previous occurrence of that date. -Similarly, type @kbd{g m n h} to go to the next occurrence of a haab -date. - -@c This is omitted because it is too long for smallbook format. -@c @findex calendar-previous-calendar-round-date -@findex calendar-next-calendar-round-date -@cindex Mayan calendar round - The Maya also used the combination of the tzolkin date and the haab -date. This combination is a cycle of about 52 years called a -@emph{calendar round}. If you type @kbd{g m p c}, Emacs asks you for -both a haab and a tzolkin date and then moves point to the previous -occurrence of that combination. Use @kbd{g m n c} to move point to the -next occurrence of a combination. These commands signal an error if the -haab/tzolkin date combination you have typed is impossible. - - Emacs uses strict completion (@pxref{Strict Completion}) whenever it -asks you to type a Mayan name, so you don't have to worry about -spelling. - -@node Diary -@section The Diary -@cindex diary - - The Emacs diary keeps track of appointments or other events on a daily -basis, in conjunction with the calendar. To use the diary feature, you -must first create a @dfn{diary file} containing a list of events and -their dates. Then Emacs can automatically pick out and display the -events for today, for the immediate future, or for any specified -date. - - The name of the diary file is specified by the variable -@code{diary-file}; @file{~/diary} is the default. A sample diary file -is (note that the file format is essentially the same as that used by -the external shell utility @samp{calendar}): - -@example -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. -@end example - -@noindent -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. - -@menu -* Displaying the Diary:: Viewing diary entries and associated calendar dates. -* Format of Diary File:: Entering events in your diary. -* Date Formats:: Various ways you can specify dates. -* Adding to Diary:: Commands to create diary entries. -* Special Diary Entries:: Anniversaries, blocks of dates, cyclic entries, etc. -@end menu - -@node Displaying the Diary -@subsection 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. - -@table @kbd -@item d -Display all diary entries for the selected date -(@code{diary-view-entries}). -@item Mouse-2 Diary -Display all diary entries for the date you click on. -@item s -Display the entire diary file (@code{diary-show-all-entries}). -@item m -Mark all visible dates that have diary entries -(@code{mark-diary-entries}). -@item u -Unmark the calendar window (@code{calendar-unmark}). -@item M-x print-diary-entries -Print hard copy of the diary display as it appears. -@item M-x diary -Display all diary entries for today's date. -@item M-x diary-mail-entries -Mail yourself email reminders about upcoming diary entries. -@end table - -@kindex d @r{(Calendar mode)} -@findex diary-view-entries -@vindex 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, -@kbd{2 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 -@kbd{Mouse-2} on the date, and then choose @kbd{Diary entries} from -the menu that appears. If the variable -@code{view-diary-entries-initially} is non-@code{nil}, creating the -calendar lists the diary entries for the current date (provided the -current date is visible). - -@kindex m @r{(Calendar mode)} -@findex mark-diary-entries -@vindex 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). -@iftex -@inforef{Calendar Customizing, diary-entry-marker, emacs-xtra}. -@end iftex -@ifnottex -@xref{Calendar Customizing, diary-entry-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 -turns off holiday marks (@pxref{Holidays}). If the variable -@code{mark-diary-entries-in-calendar} is non-@code{nil}, creating or -updating the calendar marks diary dates automatically. - -@kindex s @r{(Calendar mode)} -@findex 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}). - -@findex 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. -@iftex -@inforef{Diary Customizing,, emacs-xtra}. -@end iftex -@ifnottex -@xref{Diary Customizing, number-of-diary-entries}. -@end 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. - -@findex diary-mail-entries -@vindex 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 -@code{diary-mail-days} says how many days. - -@node Format of Diary File -@subsection The Diary File -@cindex diary file - -@vindex diary-file - Your @dfn{diary file} is a file that records events associated with -particular dates. The name of the diary file is specified by the -variable @code{diary-file}; @file{~/diary} is the default. The -@code{calendar} utility program supports a subset of the format allowed -by the Emacs diary facilities, so you can use that utility to view the -diary file, with reasonable results aside from the entries it cannot -understand. - - Each entry in the diary file describes one event and consists of one -or more lines. An entry always begins with a date specification at the -left margin. The rest of the entry is simply text to describe the -event. If the entry has more than one line, then the lines after the -first must begin with whitespace to indicate they continue a previous -entry. Lines that do not begin with valid dates and do not continue a -preceding entry are ignored. - - You can 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: - -@example -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 -@end example - -@noindent -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}). - -@node Date Formats -@subsection 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. - -@example -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 -@end 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 -@samp{@var{month}/@var{day}} or @samp{@var{month}/@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 @samp{@var{monthname} @var{day}} or -@samp{@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 -@code{calendar-abbrev-length}, @code{calendar-month-abbrev-array}, and -@code{calendar-day-abbrev-array}. 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 -@samp{3/*/*} matches any day in March of any year; so does @samp{march -*}. - -@vindex european-calendar-style -@findex european-calendar -@findex 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 -@kbd{M-x 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. - -@node Adding to Diary -@subsection Commands to Add to the Diary - - While in the calendar, there are several commands to create diary -entries: - -@table @kbd -@item i d -Add a diary entry for the selected date (@code{insert-diary-entry}). -@item i w -Add a diary entry for the selected day of the week (@code{insert-weekly-diary-entry}). -@item i m -Add a diary entry for the selected day of the month (@code{insert-monthly-diary-entry}). -@item i y -Add a diary entry for the selected day of the year (@code{insert-yearly-diary-entry}). -@end table - -@kindex i d @r{(Calendar mode)} -@findex 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. - -@kindex i w @r{(Calendar mode)} -@findex insert-weekly-diary-entry -@kindex i m @r{(Calendar mode)} -@findex insert-monthly-diary-entry -@kindex i y @r{(Calendar mode)} -@findex 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 -@kbd{i 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 -@code{redraw-calendar} to force an update at any time. - -@node Special Diary Entries -@subsection 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 -@samp{%%} 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: - -@table @kbd -@item i a -Add an anniversary diary entry for the selected date -(@code{insert-anniversary-diary-entry}). -@item i b -Add a block diary entry for the current region -(@code{insert-block-diary-entry}). -@item i c -Add a cyclic diary entry starting at the date -(@code{insert-cyclic-diary-entry}). -@end table - -@kindex i a @r{(Calendar mode)} -@findex 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: - -@findex diary-anniversary -@example -%%(diary-anniversary 10 31 1948) Arthur's birthday -@end example - -@noindent -This entry applies to October 31 in any year after 1948; @samp{10 31 -1948} specifies the date. (If you are using the European 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: - -@findex diary-block -@example -%%(diary-block 6 24 1990 7 10 1990) Vacation -@end example - -@noindent -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.) - -@kindex i b @r{(Calendar mode)} -@findex 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. - -@kindex i c @r{(Calendar mode)} -@findex 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: - -@findex diary-cyclic -@example -%%(diary-cyclic 50 3 1 1990) Renew medication -@end example - -@noindent -This entry applies to March 1, 1990 and every 50th day following; -@samp{3 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, -@kbd{C-u 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: - -@findex diary-float -@example -&%%(diary-float 11 4 -1) American Thanksgiving -@end example - -@noindent -The 11 specifies November (the eleventh month), the 4 specifies Thursday -(the fourth day of the week, where Sunday is numbered zero), and the -@minus{}1 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 year.@refill - - 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. -@iftex -@inforef{Sexp Diary Entries,, emacs-xtra}. -@end iftex -@ifnottex -@inforef{Sexp Diary Entries}. -@end ifnottex - -@node Appointments -@section Appointments -@cindex appointment notification - -@vindex appt-display-format -@vindex appt-audible -@vindex 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 -@code{appt-audible} is non-@code{nil}, the warning includes an audible -reminder. In addition, if @code{appt-display-mode-line} is -non-@code{nil}, Emacs displays the number of minutes to the -appointment on the mode line. - -@vindex appt-display-duration -@vindex appt-disp-window-function -@vindex 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 -@code{appt-disp-window-function} and @code{appt-delete-window-function} -give the names of functions used to create and destroy the window, -respectively. - -@findex 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: - -@example -Monday - 9:30am Coffee break - 12:00pm Lunch -@end example - -@vindex appt-message-warning-time -@noindent -Then on Mondays, you will be reminded at around 9:20am about your -coffee break and at around 11:50am about lunch. The variable -@code{appt-message-warning-time} 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. - -@vindex 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 -@code{appt-display-diary} to @code{nil}. The appointments list is -also updated whenever the diary file is saved. - -@findex appt-add -@findex appt-delete -@cindex 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}. - -@node Importing Diary -@section Importing and Exporting Diary Entries - - You can transfer diary entries between Emacs diary files and a -variety of other formats. - -@vindex 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}. - -@cindex 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. - -@findex 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: - -@example -(add-hook 'rmail-show-message-hook 'icalendar-import-buffer) -@end example - -@findex icalendar-import-file - The command @code{icalendar-import-file} imports an iCalendar file -and adds the results to an Emacs diary file. For example: - -@example -(icalendar-import-file "/here/is/calendar.ics" - "/there/goes/ical-diary") -@end example - -@noindent -You can use an @code{#include} directive to add the import file contents -to the main diary file, if these are different files. -@iftex -@inforef{Fancy Diary Display,, emacs-xtra}. -@end iftex -@ifnottex -@xref{Fancy Diary Display}. -@end ifnottex - - -@findex 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. - -@node Daylight Saving -@section Daylight Saving Time -@cindex 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. - -@vindex calendar-daylight-savings-starts -@vindex 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: -@code{calendar-daylight-savings-starts} and -@code{calendar-daylight-savings-ends}. - - These values should be Lisp expressions that refer to the variable -@code{year}, and evaluate to the Gregorian date on which daylight -saving time starts or (respectively) ends, in the form of a list -@code{(@var{month} @var{day} @var{year})}. The values should be -@code{nil} 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: - -@example -(calendar-nth-named-day 2 0 3 year) -(calendar-nth-named-day 1 0 11 year) -@end example - -@noindent -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 -@code{calendar-daylight-savings-starts} to this: - -@example -(list 10 1 year) -@end 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}. - -@vindex 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. - -@c @vindex calendar-daylight-savings-starts-time too long! -@vindex calendar-daylight-savings-ends-time - Finally, the two variables -@code{calendar-daylight-savings-starts-time} and -@code{calendar-daylight-savings-ends-time} 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. - -@node Time Intervals -@section Summing Time Intervals -@cindex time intervals, summing -@cindex summing time intervals -@cindex 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. - -@findex timeclock-in -@findex timeclock-out -@findex timeclock-change -@findex timeclock-workday-remaining -@findex 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 -@kbd{M-x timeclock-workday-remaining} to see how much time is left to -work today (assuming a typical average of 8 hours a day), and @kbd{M-x -timeclock-when-to-leave} which will calculate when you're ``done.'' - -@vindex timeclock-modeline-display -@findex timeclock-modeline-display - If you want Emacs to display the amount of time ``left'' of your -workday in the mode line, either customize the -@code{timeclock-modeline-display} variable and set its value to -@code{t}, or invoke the @kbd{M-x timeclock-modeline-display} command. - -@vindex 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 -@code{timeclock-ask-before-exiting} 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. - -@cindex @file{.timelog} file -@vindex timeclock-file -@findex timeclock-reread-log - The timeclock functions work by accumulating the data in a file -called @file{.timelog} in your home directory. You can specify a -different name for this file by customizing the variable -@code{timeclock-file}. If you edit the timeclock file manually, or if -you change the value of any of timeclock's customizable variables, you -should run the command @kbd{M-x timeclock-reread-log} to update the -data in Emacs from the file. - -@ifnottex -@include cal-xtra.texi -@end ifnottex - -@ignore - arch-tag: 4531ef09-9df3-449d-9c52-2b5a4a337f92 -@end ignore