X-Git-Url: https://code.delx.au/gnu-emacs/blobdiff_plain/38d50547c2a8195bed0aaeafbbc4c0f277d4e416..4695c85095e55ca7d919d788ede0149fc1f56a59:/doc/emacs/cal-xtra.texi diff --git a/doc/emacs/cal-xtra.texi b/doc/emacs/cal-xtra.texi index de36ccc4f5..b29a852662 100644 --- a/doc/emacs/cal-xtra.texi +++ b/doc/emacs/cal-xtra.texi @@ -1,6 +1,5 @@ -@c This is part of the Emacs manual. -@c Copyright (C) 2004, 2005, 2006, 2007, 2008, 2009, 2010 -@c Free Software Foundation, Inc. +@c This is part of the Emacs manual. -*- coding: iso-latin-1 -*- +@c Copyright (C) 2004-2012 Free Software Foundation, Inc. @c See file emacs.texi for copying conditions. @c @c This file is included either in emacs-xtra.texi (when producing the @@ -8,10 +7,12 @@ @c Moved here from the Emacs Lisp Reference Manual, 2005-03-26. @node Advanced Calendar/Diary Usage -@section Customizing the Calendar and Diary +@section More advanced features of the Calendar and Diary - There are many customizations that you can use to make the calendar and -diary suit your personal tastes. + This section describes some of the more advanced/specialized +features of the calendar and diary. It starts with some of the +many ways in which you can customize the calendar and diary to suit +your personal tastes. @menu * Calendar Customizing:: Calendar layout and hooks. @@ -42,14 +43,14 @@ customize the variables @code{calendar-intermonth-header} and @vindex calendar-holiday-marker @vindex diary-entry-marker -@vindex calenday-today-marker +@vindex calendar-today-marker The variable @code{calendar-holiday-marker} specifies how to mark a -date as being a holiday. Its value may be a single-character string to +date that is a holiday. Its value may be a single-character string to insert next to the date, or a face name to use for displaying the date. Likewise, the variable @code{diary-entry-marker} specifies how to mark a -date that has diary entries, and @code{calenday-today-marker} is used by -the function @code{calendar-mark-today} to mark today's date. By -default, the calendar uses faces named @code{holiday}, @code{diary}, and +date that has diary entries. The function @code{calendar-mark-today} +uses @code{calendar-today-marker} to mark today's date. By default, +the calendar uses faces named @code{holiday}, @code{diary}, and @code{calendar-today} for these purposes. @vindex calendar-load-hook @@ -66,7 +67,7 @@ display does not run this hook. But if you leave the calendar with the @vindex calendar-today-visible-hook @findex calendar-star-date The variable @code{calendar-today-visible-hook} is a normal hook run -after the calendar buffer has been prepared with the calendar when the +after the calendar buffer has been prepared with the calendar, when the current date is visible in the window. One use of this hook is to mark today's date; to do that use either of the functions @code{calendar-mark-today} or @code{calendar-star-date}: @@ -91,28 +92,27 @@ the current date is @emph{not} visible in the window. @vindex calendar-holidays @vindex holiday-oriental-holidays @vindex holiday-solar-holidays - Emacs knows about holidays defined by entries on one of several lists. -The lists of holidays that Emacs uses are for -general holidays (@code{holiday-general-holidays}), -local holidays (@code{holiday-local-holidays}), -sun- and moon-related holidays (@code{holiday-solar-holidays}), -Baha'i holidays (@code{holiday-bahai-holidays}), -Christian holidays (@code{holiday-christian-holidays}), -Hebrew (Jewish) holidays (@code{holiday-hebrew-holidays}), -Islamic (Muslim) holidays (@code{holiday-islamic-holidays}), -Oriental holidays (@code{holiday-oriental-holidays}), -and other holidays (@code{holiday-other-holidays}). + There are several variables listing the default holidays that Emacs +knows about. These are: @code{holiday-general-holidays}, +@code{holiday-local-holidays}, @code{holiday-solar-holidays}, +@code{holiday-bahai-holidays}, @code{holiday-christian-holidays}, +@code{holiday-hebrew-holidays}, @code{holiday-islamic-holidays}, +@code{holiday-oriental-holidays}, and @code{holiday-other-holidays}. +The names should be self-explanatory; e.g.@: @code{holiday-solar-holidays} +lists sun- and moon-related holidays. You can customize these lists of holidays to your own needs, deleting or adding holidays as described below. Set any of them to @code{nil} to -eliminate the associated holidays. +not show the associated holidays. @vindex holiday-general-holidays - The general holidays are, by default, holidays common throughout the -United States. - @vindex holiday-local-holidays - There are no default local holidays, but your site may supply some. +@vindex holiday-other-holidays + The general holidays are, by default, holidays common throughout the +United States. In contrast, @code{holiday-local-holidays} and +@code{holiday-other-holidays} are both empty by default. These are +intended for system-wide settings and your individual use, +respectively. @vindex holiday-bahai-holidays @vindex holiday-christian-holidays @@ -130,18 +130,13 @@ all) of the variables @code{calendar-bahai-all-holidays-flag}, @code{calendar-hebrew-all-holidays-flag}, or @code{calendar-islamic-all-holidays-flag} to @code{t}. -@vindex holiday-other-holidays - You can set the variable @code{holiday-other-holidays} to any list of -holidays. This list, normally empty, is intended for individual use. - @cindex holiday forms Each of the holiday variables is a list of @dfn{holiday forms}, each -form describing a holiday (or sometimes a list of holidays). - - Here is a table of the possible kinds of holiday form. Day numbers -and month numbers count starting from 1, but ``dayname'' numbers -count Sunday as 0. The element @var{string} is always the -description of the holiday, as a string. +form describing a holiday (or sometimes a list of holidays). Here is +a table of the possible kinds of holiday form. Day numbers and month +numbers count starting from 1, but ``dayname'' numbers count Sunday as +0. The argument @var{string} is always the description of the +holiday, as a string. @table @code @item (holiday-fixed @var{month} @var{day} @var{string}) @@ -203,7 +198,7 @@ the month (1 specifies the first occurrence, 2 the second occurrence, @minus{}1 the last occurrence, @minus{}2 the second-to-last occurrence, and so on). - You can specify holidays that occur on fixed days of the Baha'i, + You can specify holidays that occur on fixed days of the Bahá'í, Chinese, Hebrew, Islamic, and Julian calendars too. For example, @smallexample @@ -257,15 +252,15 @@ and write an Emacs Lisp function @code{eclipses} that returns a visible in the calendar window, with descriptive strings, like this: @smallexample -(((6 27 1991) "Lunar Eclipse") ((7 11 1991) "Solar Eclipse") ... ) +(((6 4 2012) "Lunar Eclipse") ((11 13 2012) "Solar Eclipse") ... ) @end smallexample @node Date Display Format @subsection Date Display Format @vindex calendar-date-display-form - You can customize the manner of displaying dates in the diary, in mode -lines, and in messages by setting @code{calendar-date-display-form}. + You can customize the way dates are displayed in the diary, mode +lines, and messages by setting @code{calendar-date-display-form}. This variable holds a list of expressions that can involve the variables @code{month}, @code{day}, and @code{year}, which are all numbers in string form, and @code{monthname} and @code{dayname}, which are both @@ -292,7 +287,7 @@ The default ISO date representation is: @end smallexample @noindent -This specifies a typical American format: +Another typical American format is: @smallexample (month "/" day "/" (substring year -2)) @@ -359,7 +354,7 @@ be regular expressions (@pxref{Regular Expressions,,, elisp, the Emacs Lisp Reference Manual}) or the symbols @code{month}, @code{day}, @code{year}, @code{monthname}, and @code{dayname}. All these elements serve as patterns that match certain kinds of text in the diary file. -In order for the date pattern, as a whole, to match, all of its elements +In order for the date pattern as a whole to match, all of its elements must match consecutively. A regular expression in a date pattern matches in its usual fashion, @@ -388,8 +383,8 @@ provided by @code{diary-american-date-forms}: @end example @noindent -Other default styles are provided by @code{diary-european-date-forms} -and @code{diary-iso-date-forms}. +The variables @code{diary-european-date-forms} and +@code{diary-iso-date-forms} provide other default styles. The date patterns in the list must be @emph{mutually exclusive} and must not match any portion of the diary entry itself, just the date and @@ -420,7 +415,7 @@ the fourth pattern. @subsection Diary Entries Using non-Gregorian Calendars As well as entries based on the standard Gregorian calendar, your -diary can have entries based on Baha'i, Hebrew, or Islamic dates. +diary can have entries based on Bahá'í, Hebrew, or Islamic dates. Recognition of such entries can be time-consuming, however, and since most people don't use them, you must explicitly enable their use. If you want the diary to recognize Hebrew-date diary entries, for example, @@ -440,7 +435,7 @@ you must do this: @end smallexample @noindent -Similarly, for Islamic and Baha'i entries, add +Similarly, for Islamic and Bahá'í entries, add @code{diary-islamic-list-entries} and @code{diary-islamic-mark-entries}, or @code{diary-bahai-list-entries} and @code{diary-bahai-mark-entries}. @@ -449,7 +444,7 @@ Similarly, for Islamic and Baha'i entries, add @vindex diary-islamic-entry-symbol These diary entries have the same formats as Gregorian-date diary entries; except that @code{diary-bahai-entry-symbol} (default @samp{B}) -must precede a Baha'i date, @code{diary-hebrew-entry-symbol} (default +must precede a Bahá'í date, @code{diary-hebrew-entry-symbol} (default @samp{H}) a Hebrew date, and @code{diary-islamic-entry-symbol} (default @samp{I}) an Islamic date. Moreover, non-Gregorian month names may not be abbreviated (because the first three letters are often not unique). @@ -476,7 +471,7 @@ nonmarking if preceded by @code{diary-nonmarking-symbol} (default Here is a table of commands used in the calendar to create diary entries that match the selected date and other dates that are similar in -the Baha'i, Hebrew, or Islamic calendars: +the Bahá'í, Hebrew, or Islamic calendars: @table @kbd @item i h d @@ -539,13 +534,13 @@ are no diary entries, even if that day is a holiday. If you want such days to be shown in the fancy diary buffer, set the variable @code{diary-list-include-blanks} to @code{t}.@refill -@c View mode does not seem to be described in the manual. -@c buffers.texi has a brief mention. - The fancy diary buffer enables View mode, a minor mode that provides -commands for scrolling and searching the text. For example, @key{SPC} -and @key{DEL} scroll forward and backward, and @key{s} starts an -incremental search. See the documentation of the function -@code{view-mode} for more information. + The fancy diary buffer enables View mode +@iftex +(@pxref{View Mode,,, emacs, the Emacs Manual}). +@end iftex +@ifnottex +(@pxref{View Mode}). +@end ifnottex The alternative display method @code{diary-simple-display} shows the actual diary buffer, and uses invisible text to hide entries that don't @@ -576,7 +571,13 @@ display, the other irrelevant entries are really absent, not just hidden. After preparing the buffer, it runs the hook @code{diary-print-entries-hook}. The default value of this hook sends the data directly to the printer with the command @code{lpr-buffer} -(@pxref{Printing}). If you want to use a different command to do the +@iftex +(@pxref{Printing,,, emacs, the Emacs Manual}). +@end iftex +@ifnottex +(@pxref{Printing}). +@end ifnottex +If you want to use a different command to do the printing, just change the value of this hook. Other uses might include, for example, rearranging the lines into order by day and time. @@ -617,6 +618,20 @@ first within each day. Note how the sort command is placed at the end of the hook list, in case earlier members of the list change the order of the diary entries, or add items. +@vindex diary-comment-start + You can write @samp{comments} in diary entries, by setting the +variables @code{diary-comment-start} and @code{diary-comment-end} to +strings that delimit comments. The fancy display does not print +comments. You might want to put meta-data for the use of other packages +(e.g.@: the appointment package, +@iftex +@pxref{Appointments,,,emacs, the Emacs Manual}) +@end iftex +@ifnottex +@pxref{Appointments}) +@end ifnottex +inside comments. + @vindex diary-include-string Your main diary file can include other files. This permits a group of people to share a diary file for events that apply to all of them. @@ -692,7 +707,7 @@ that have occurred: @findex diary-cyclic @smallexample -%%(diary-cyclic 50 1 1 1990) Renew medication (%d%s time) +%%(diary-cyclic 50 1 1 2012) Renew medication (%d%s time) @end smallexample @noindent @@ -703,9 +718,9 @@ Renew medication (5th time) @end smallexample @noindent -in the fancy diary display on September 8, 1990. +in the fancy diary display on September 7, 2012. - There is an early reminder diary sexp that includes its entry in the + There is an ``early reminder'' diary sexp that includes its entry in the diary not only on the date of occurrence, but also on earlier dates. For example, if you want a reminder a week before your anniversary, you can use @@ -831,7 +846,7 @@ Make a diary entry with today's equivalent Julian calendar date. @item %%(diary-astro-day-number) Make a diary entry with today's equivalent astronomical (Julian) day number. @item %%(diary-bahai-date) -Make a diary entry with today's equivalent Baha'i calendar date. +Make a diary entry with today's equivalent Bahá'í calendar date. @item %%(diary-chinese-date) Make a diary entry with today's equivalent Chinese calendar date. @item %%(diary-coptic-date) @@ -877,6 +892,7 @@ diary entries: @findex diary-hebrew-omer @cindex yahrzeits @findex diary-hebrew-yahrzeit +@findex diary-hebrew-birthday @table @code @item %%(diary-hebrew-rosh-hodesh) Make a diary entry that tells the occurrence and ritual announcement of each @@ -894,13 +910,11 @@ is the @emph{Gregorian} (civil) date of death. The diary entry appears on the proper Hebrew calendar anniversary and on the day before. (The order of the parameters changes according to the calendar date style; for example in the European style to @var{day}, @var{month}, @var{year}.) +@item %%(diary-hebrew-birthday @var{month} @var{day} @var{year}) +Make a diary entry for a birthday on the Hebrew calendar. @end table All the functions documented above take an optional argument @var{mark} which specifies how to mark the date in the calendar display. If one of these functions decides that it applies to a certain date, it returns a value that contains @var{mark}, as described above. - -@ignore - arch-tag: 52cb299f-fd1f-4616-bfe6-91b988669431 -@end ignore