X-Git-Url: https://code.delx.au/gnu-emacs/blobdiff_plain/678fb7066698ebfe3aecba722294025ed26da01b..d7f413b893012eb5c9c93cd724008c2c1faae56f:/doc/emacs/cal-xtra.texi diff --git a/doc/emacs/cal-xtra.texi b/doc/emacs/cal-xtra.texi index 4d37672b6c..cf1eba17de 100644 --- a/doc/emacs/cal-xtra.texi +++ b/doc/emacs/cal-xtra.texi @@ -1,5 +1,5 @@ -@c This is part of the Emacs manual. -@c Copyright (C) 2004-2012 Free Software Foundation, Inc. +@c This is part of the Emacs manual. -*- coding: utf-8 -*- +@c Copyright (C) 2004-2014 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 @@ -7,14 +7,17 @@ @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. * Holiday Customizing:: Defining your own holidays. +* Mayan Calendar:: Moving to a date specified in a Mayan calendar. * Date Display Format:: Changing the format. * Time Display Format:: Changing the format. * Diary Customizing:: Defaults you can set. @@ -39,16 +42,24 @@ To display text @emph{between} the months, for example week numbers, customize the variables @code{calendar-intermonth-header} and @code{calendar-intermonth-text} as described in their documentation. +@vindex calendar-month-header +@vindex calendar-day-header-array + The variable @code{calendar-month-header} controls the text that +appears above each month in the calendar. By default, it shows the +month and year. The variable @code{calendar-day-header-array} +controls the text that appears above each day's column in every month. +By default, it shows the first two letters of each day's name. + @vindex calendar-holiday-marker @vindex diary-entry-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{calendar-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 @@ -60,12 +71,12 @@ the calendar). Starting the calendar runs the normal hook @code{calendar-initial-window-hook}. Recomputation of the calendar display does not run this hook. But if you leave the calendar with the -@kbd{q} command and reenter it, the hook runs again.@refill +@kbd{q} command and reenter it, the hook runs again. @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}: @@ -90,28 +101,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 @@ -129,18 +139,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}) @@ -202,7 +207,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 @@ -256,15 +261,108 @@ 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 Mayan Calendar +@subsection Converting from the Mayan Calendar +@cindex 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-mayan-goto-long-count-date}). +@item g m n t +Move to the next occurrence of a place in the +tzolkin calendar (@code{calendar-mayan-next-tzolkin-date}). +@item g m p t +Move to the previous occurrence of a place in the +tzolkin calendar (@code{calendar-mayan-previous-tzolkin-date}). +@item g m n h +Move to the next occurrence of a place in the +haab calendar (@code{calendar-mayan-next-haab-date}). +@item g m p h +Move to the previous occurrence of a place in the +haab calendar (@code{calendar-mayan-previous-haab-date}). +@item g m n c +Move to the next occurrence of a place in the +calendar round (@code{calendar-mayan-next-calendar-round-date}). +@item g m p c +Move to the previous occurrence of a place in the +calendar round (@code{calendar-mayan-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-mayan-goto-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-mayan-previous-tzolkin-date +@findex calendar-mayan-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-mayan-previous-haab-date +@findex calendar-mayan-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 by 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-mayan-previous-calendar-round-date +@findex calendar-mayan-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 +@iftex +(@pxref{Completion Exit,,, emacs, the Emacs Manual}) +@end iftex +@ifnottex +(@pxref{Completion Exit}) +@end ifnottex +whenever it asks you to type a Mayan name, so you don't have to worry +about spelling. + @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 @@ -291,7 +389,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)) @@ -358,7 +456,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, @@ -387,8 +485,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 @@ -419,7 +517,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á'í, Chinese, 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, @@ -433,22 +531,27 @@ you must do this: @findex diary-islamic-mark-entries @findex diary-bahai-list-entries @findex diary-bahai-mark-entries +@findex diary-chinese-list-entries +@findex diary-chinese-mark-entries @smallexample (add-hook 'diary-nongregorian-listing-hook 'diary-hebrew-list-entries) (add-hook 'diary-nongregorian-marking-hook 'diary-hebrew-mark-entries) @end smallexample @noindent -Similarly, for Islamic and Baha'i 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}. +Similarly, for Islamic, Bahá'í and Chinese entries, add +@code{diary-islamic-list-entries} and @code{diary-islamic-mark-entries}, +@code{diary-bahai-list-entries} and @code{diary-bahai-mark-entries}, +or @code{diary-chinese-list-entries} and @code{diary-chinese-mark-entries}. @vindex diary-bahai-entry-symbol +@vindex diary-chinese-entry-symbol @vindex diary-hebrew-entry-symbol @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-chinese-entry-symbol} (default +@samp{C}) a Chinese 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). @@ -475,7 +578,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á'í, Chinese, Hebrew, or Islamic calendars: @table @kbd @item i h d @@ -496,6 +599,14 @@ the Baha'i, Hebrew, or Islamic calendars: @code{diary-bahai-insert-monthly-entry} @item i B y @code{diary-bahai-insert-yearly-entry} +@item i C d +@code{diary-chinese-insert-entry} +@item i C m +@code{diary-chinese-insert-monthly-entry} +@item i C y +@code{diary-chinese-insert-yearly-entry} +@item i C a +@code{diary-chinese-insert-anniversary-entry} @end table @findex diary-hebrew-insert-entry @@ -507,6 +618,11 @@ the Baha'i, Hebrew, or Islamic calendars: @findex diary-bahai-insert-entry @findex diary-bahai-insert-monthly-entry @findex diary-bahai-insert-yearly-entry +@findex diary-chinese-insert-entry +@findex diary-chinese-insert-monthly-entry +@findex diary-chinese-insert-yearly-entry +@findex diary-chinese-insert-anniversary-entry + These commands work much like the corresponding commands for ordinary diary entries: they apply to the date that point is on in the calendar window, and what they do is insert just the date portion of a diary @@ -536,9 +652,15 @@ example, to sort the entries by the dates they apply to. Ordinarily, the fancy diary buffer does not show days for which there 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 +@code{diary-list-include-blanks} to @code{t}. - The fancy diary buffer enables View mode (@pxref{View Mode}). + 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 @@ -569,7 +691,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. @@ -615,7 +743,7 @@ of the diary entries, or add items. 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, +(e.g., the appointment package, @iftex @pxref{Appointments,,,emacs, the Emacs Manual}) @end iftex @@ -699,7 +827,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 @@ -710,9 +838,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 @@ -838,7 +966,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)