X-Git-Url: https://code.delx.au/gnu-emacs/blobdiff_plain/505b55e6dc514e701cfcccd87eb05ba207bd187f..937640a621a4ce2e5e56eaecca37a2a28a584318:/man/calendar.texi?ds=sidebyside diff --git a/man/calendar.texi b/man/calendar.texi index 1c1fb6d1ef..8ebe7c4b3d 100644 --- a/man/calendar.texi +++ b/man/calendar.texi @@ -1,5 +1,5 @@ @c This is part of the Emacs manual. -@c Copyright (C) 1985,86,87,93,94,95,1997,2000 Free Software Foundation, Inc. +@c Copyright (C) 1985,86,87,93,94,95,1997,2000,2001 Free Software Foundation, Inc. @c See file emacs.texi for copying conditions. @node Calendar/Diary, Gnus, Dired, Top @chapter The Calendar and the Diary @@ -37,6 +37,7 @@ information about the calendar and diary. * Other Calendars:: Converting dates to other calendar systems. * Diary:: Displaying events from your diary. * Appointments:: Reminders when it's time to do something. +* iCalendar:: Converting diary events to/from iCalendar format. * Daylight Savings:: How to specify when daylight savings time is active. * Time Intervals:: Keeping track of time intervals. @end menu @@ -183,6 +184,8 @@ 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 o Center calendar around specified month (@code{calendar-other-month}). @item . @@ -196,6 +199,12 @@ 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 + @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. + @kindex o @r{(Calendar mode)} @findex calendar-other-month @kbd{o} (@code{calendar-other-month}) prompts for a month and year, @@ -210,11 +219,11 @@ then centers the three-month calendar around that month. @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 it means moving the strip so that new months become visible in -the window. + 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 C-x < @@ -269,7 +278,7 @@ Display the number of days in the current region @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 printed is +(@code{calendar-count-days-region}). The numbers of days shown is @emph{inclusive}; that is, it includes the days specified by mark and point. @@ -290,7 +299,7 @@ Exit from calendar (@code{exit-calendar}). @kindex p d @r{(Calendar mode)} @cindex day of year @findex calendar-print-day-of-year - To print the number of days elapsed since the start of the year, or + 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 number of days elapsed includes the @@ -746,6 +755,7 @@ 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 @@ -759,11 +769,14 @@ other than Mayan; for the Mayan calendar, see the following section. @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 in astronomical (Julian) day number +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 @@ -1116,8 +1129,11 @@ 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 to three characters (with or without a -period). Case is not significant. +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 @@ -1178,9 +1194,9 @@ date; you can then type the rest of the diary entry. 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 rest of the entry. Similarly, you can insert a yearly -diary entry with the @kbd{i y} command. +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. @@ -1303,66 +1319,62 @@ 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 - Most generally, sexp diary entries can perform arbitrary -computations to determine when they apply. @xref{Sexp Diary Entries,, -Sexp Diary Entries, elisp, The Emacs Lisp Reference Manual}. + 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. +@xref{Sexp Diary Entries,, Sexp Diary Entries, elisp, The Emacs Lisp +Reference Manual}. @node Appointments @section Appointments @cindex appointment notification +@vindex appt-display-format +@vindex appt-audible 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 the mode line. - -@vindex diary-hook -@findex appt-make-list - To enable appointment notification, you must enable the time display -feature of Emacs, @kbd{M-x display-time} (@pxref{Mode Line}). You must -also add the function @code{appt-make-list} to the -@code{diary-hook}, like this: - -@example -(add-hook 'diary-hook 'appt-make-list) -@end example - -@noindent -Adding this text to your @file{.emacs} file does the whole job: - -@example -(display-time) -(add-hook 'diary-hook 'appt-make-list) -(diary 0) -@end example - - With these preparations done, when you display the diary (either with -the @kbd{d} command in the calendar window or with the @kbd{M-x diary} -command), it sets up an appointment list of all the diary entries found -with recognizable times of day, and reminds you just before each of -them. +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}, an audible reminder is also given. + +@findex appt-activate + To enable appointment notification, call the function +@code{appt-activate} with a positive argument. This 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. Calling @code{appt-activate} with a negative argument disables +the appointment package. For example, suppose the diary file contains these lines: @example Monday 9:30am Coffee break - 12:00pm Lunch + 12:00pm Lunch @end example +@vindex appt-message-warning-time @noindent -Then on Mondays, after you have displayed the diary, you will be -reminded at 9:20am about your coffee break and at 11:50am about lunch. +Then on Mondays, you will be reminded at around 9:20am about your coffee +break and at around 11:50am about lunch. How many minutes in advance you +are first warned is determined by the value of +@code{appt-message-warning-time}. 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. +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 automatically just after -midnight. This also displays the next day's diary entries in the diary -buffer, unless you set @code{appt-display-diary} to @code{nil}. + Emacs updates the appointments list from the diary file automatically +just after midnight. An update can be forced at any time by +re-activating the appointment package. 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 @@ -1372,9 +1384,53 @@ 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}. -@vindex appt-issue-message - You can turn off the appointment notification feature at any time by -setting @code{appt-issue-message} to @code{nil}. +@node iCalendar +@section iCalendar +@cindex iCalendar support + + The icalendar package aims at providing an implementation of the +iCalendar standard, as defined in ``RFC 2445 -- Internet Calendaring and +Scheduling Core Object Specification (iCalendar)''. It provides a means +for importing iCalendar (and the earlier vCalendar format) data into +Emacs diary files and vice versa. + + 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. Please note that @file{icalendar.el} is work in +progress, so usage may evolve in future. + + To activate the package, use @code{(require 'icalendar)}. + +@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 distinct. @xref{Fancy Diary +Display,,, elisp, The Emacs Lisp Reference Manual}. + +@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 Savings @section Daylight Savings Time @@ -1492,3 +1548,7 @@ 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. + +@ignore + arch-tag: 4531ef09-9df3-449d-9c52-2b5a4a337f92 +@end ignore