Commit | Line | Data |
---|---|---|
102f1b54 GM |
1 | @c This is part of the Emacs manual. -*- coding: iso-latin-1 -*- |
2 | @c Copyright (C) 2004-2012 Free Software Foundation, Inc. | |
6f585e44 EZ |
3 | @c See file emacs.texi for copying conditions. |
4 | @c | |
c5184807 EZ |
5 | @c This file is included either in emacs-xtra.texi (when producing the |
6 | @c printed version) or in the main Emacs manual (for the on-line version). | |
7 | ||
8 | @c Moved here from the Emacs Lisp Reference Manual, 2005-03-26. | |
9 | @node Advanced Calendar/Diary Usage | |
10 | @section Customizing the Calendar and Diary | |
11 | ||
a5987767 GM |
12 | There are many ways in which you can customize the calendar and |
13 | diary to suit your personal tastes. | |
c5184807 EZ |
14 | |
15 | @menu | |
f9b4c05d | 16 | * Calendar Customizing:: Calendar layout and hooks. |
c5184807 EZ |
17 | * Holiday Customizing:: Defining your own holidays. |
18 | * Date Display Format:: Changing the format. | |
19 | * Time Display Format:: Changing the format. | |
20 | * Diary Customizing:: Defaults you can set. | |
f9b4c05d | 21 | * Non-Gregorian Diary:: Diary entries based on other calendars. |
cad04c66 GM |
22 | * Diary Display:: A choice of ways to display the diary. |
23 | * Fancy Diary Display:: Sorting diary entries, using included diary files. | |
24 | * Sexp Diary Entries:: More flexible diary entries. | |
c5184807 EZ |
25 | @end menu |
26 | ||
27 | @node Calendar Customizing | |
28 | @subsection Customizing the Calendar | |
a43a8a2e GM |
29 | |
30 | @vindex calendar-intermonth-text | |
31 | @cindex calendar layout | |
f9b4c05d GM |
32 | @cindex calendar week numbers |
33 | The calendar display unfortunately cannot be changed from three | |
34 | months, but you can customize the whitespace used by setting the | |
35 | variables: @code{calendar-left-margin}, | |
c1e67aad GM |
36 | @code{calendar-day-header-width}, @code{calendar-day-digit-width}, |
37 | @code{calendar-column-width}, and @code{calendar-intermonth-spacing}. | |
f9b4c05d GM |
38 | To display text @emph{between} the months, for example week numbers, |
39 | customize the variables @code{calendar-intermonth-header} and | |
40 | @code{calendar-intermonth-text} as described in their documentation. | |
a43a8a2e | 41 | |
c5184807 EZ |
42 | @vindex calendar-holiday-marker |
43 | @vindex diary-entry-marker | |
301b181a | 44 | @vindex calendar-today-marker |
c5184807 | 45 | The variable @code{calendar-holiday-marker} specifies how to mark a |
a5987767 | 46 | date that is a holiday. Its value may be a single-character string to |
f9b4c05d GM |
47 | insert next to the date, or a face name to use for displaying the date. |
48 | Likewise, the variable @code{diary-entry-marker} specifies how to mark a | |
a5987767 GM |
49 | date that has diary entries. The function @code{calendar-mark-today} |
50 | uses @code{calendar-today-marker} to mark today's date. By default, | |
51 | the calendar uses faces named @code{holiday}, @code{diary}, and | |
f9b4c05d | 52 | @code{calendar-today} for these purposes. |
c5184807 EZ |
53 | |
54 | @vindex calendar-load-hook | |
55 | The variable @code{calendar-load-hook} is a normal hook run when the | |
56 | calendar package is first loaded (before actually starting to display | |
57 | the calendar). | |
58 | ||
36c0514c | 59 | @vindex calendar-initial-window-hook |
c5184807 | 60 | Starting the calendar runs the normal hook |
36c0514c | 61 | @code{calendar-initial-window-hook}. Recomputation of the calendar |
c5184807 EZ |
62 | display does not run this hook. But if you leave the calendar with the |
63 | @kbd{q} command and reenter it, the hook runs again.@refill | |
64 | ||
36c0514c | 65 | @vindex calendar-today-visible-hook |
f9b4c05d | 66 | @findex calendar-star-date |
36c0514c | 67 | The variable @code{calendar-today-visible-hook} is a normal hook run |
a5987767 | 68 | after the calendar buffer has been prepared with the calendar, when the |
c5184807 | 69 | current date is visible in the window. One use of this hook is to |
f9b4c05d GM |
70 | mark today's date; to do that use either of the functions |
71 | @code{calendar-mark-today} or @code{calendar-star-date}: | |
c5184807 EZ |
72 | |
73 | @findex calendar-mark-today | |
f9b4c05d | 74 | @smallexample |
36c0514c | 75 | (add-hook 'calendar-today-visible-hook 'calendar-mark-today) |
f9b4c05d | 76 | @end smallexample |
c5184807 | 77 | |
36c0514c | 78 | @vindex calendar-today-invisible-hook |
c5184807 | 79 | @noindent |
36c0514c | 80 | A similar normal hook, @code{calendar-today-invisible-hook} is run if |
c5184807 EZ |
81 | the current date is @emph{not} visible in the window. |
82 | ||
83 | @vindex calendar-move-hook | |
84 | Each of the calendar cursor motion commands runs the hook | |
85 | @code{calendar-move-hook} after it moves the cursor. | |
86 | ||
87 | @node Holiday Customizing | |
88 | @subsection Customizing the Holidays | |
89 | ||
90 | @vindex calendar-holidays | |
f9b4c05d GM |
91 | @vindex holiday-oriental-holidays |
92 | @vindex holiday-solar-holidays | |
a5987767 GM |
93 | There are several variables listing the default holidays that Emacs |
94 | knows about. These are: @code{holiday-general-holidays}, | |
95 | @code{holiday-local-holidays}, @code{holiday-solar-holidays}, | |
96 | @code{holiday-bahai-holidays}, @code{holiday-christian-holidays}, | |
97 | @code{holiday-hebrew-holidays}, @code{holiday-islamic-holidays}, | |
98 | @code{holiday-oriental-holidays}, and @code{holiday-other-holidays}. | |
99 | The names should be self-explanatory; e.g.@: @code{holiday-solar-holidays} | |
100 | lists sun- and moon-related holidays. | |
36c0514c | 101 | |
f9b4c05d GM |
102 | You can customize these lists of holidays to your own needs, deleting or |
103 | adding holidays as described below. Set any of them to @code{nil} to | |
a5987767 | 104 | not show the associated holidays. |
f9b4c05d | 105 | |
36c0514c | 106 | @vindex holiday-general-holidays |
36c0514c | 107 | @vindex holiday-local-holidays |
a5987767 GM |
108 | @vindex holiday-other-holidays |
109 | The general holidays are, by default, holidays common throughout the | |
110 | United States. In contrast, @code{holiday-local-holidays} and | |
111 | @code{holiday-other-holidays} are both empty by default. These are | |
112 | intended for system-wide settings and your individual use, | |
113 | respectively. | |
c5184807 | 114 | |
f9b4c05d GM |
115 | @vindex holiday-bahai-holidays |
116 | @vindex holiday-christian-holidays | |
117 | @vindex holiday-hebrew-holidays | |
118 | @vindex holiday-islamic-holidays | |
36c0514c GM |
119 | @vindex calendar-bahai-all-holidays-flag |
120 | @vindex calendar-christian-all-holidays-flag | |
121 | @vindex calendar-hebrew-all-holidays-flag | |
122 | @vindex calendar-islamic-all-holidays-flag | |
c5184807 EZ |
123 | By default, Emacs does not include all the holidays of the religions |
124 | that it knows, only those commonly found in secular calendars. For a | |
125 | more extensive collection of religious holidays, you can set any (or | |
36c0514c GM |
126 | all) of the variables @code{calendar-bahai-all-holidays-flag}, |
127 | @code{calendar-christian-all-holidays-flag}, | |
128 | @code{calendar-hebrew-all-holidays-flag}, or | |
f9b4c05d | 129 | @code{calendar-islamic-all-holidays-flag} to @code{t}. |
c5184807 | 130 | |
c5184807 | 131 | @cindex holiday forms |
f9b4c05d | 132 | Each of the holiday variables is a list of @dfn{holiday forms}, each |
a5987767 GM |
133 | form describing a holiday (or sometimes a list of holidays). Here is |
134 | a table of the possible kinds of holiday form. Day numbers and month | |
135 | numbers count starting from 1, but ``dayname'' numbers count Sunday as | |
136 | 0. The argument @var{string} is always the description of the | |
137 | holiday, as a string. | |
c5184807 EZ |
138 | |
139 | @table @code | |
140 | @item (holiday-fixed @var{month} @var{day} @var{string}) | |
141 | A fixed date on the Gregorian calendar. | |
142 | ||
f9b4c05d GM |
143 | @item (holiday-float @var{month} @var{dayname} @var{k} @var{string} |
144 | &optional @var{day}) | |
145 | The @var{k}th @var{dayname} (@var{dayname}=0 for Sunday, and so on) | |
146 | after or before Gregorian date @var{month}, @var{day}. Negative @var{k} | |
147 | means count back from the end of the month. Optional @var{day} defaults | |
148 | to 1 if @var{k} is positive, and the last day of @var{month} otherwise. | |
c5184807 | 149 | |
a43a8a2e GM |
150 | @item (holiday-chinese @var{month} @var{day} @var{string}) |
151 | A fixed date on the Chinese calendar. | |
152 | ||
c5184807 EZ |
153 | @item (holiday-hebrew @var{month} @var{day} @var{string}) |
154 | A fixed date on the Hebrew calendar. | |
155 | ||
156 | @item (holiday-islamic @var{month} @var{day} @var{string}) | |
157 | A fixed date on the Islamic calendar. | |
158 | ||
159 | @item (holiday-julian @var{month} @var{day} @var{string}) | |
160 | A fixed date on the Julian calendar. | |
161 | ||
162 | @item (holiday-sexp @var{sexp} @var{string}) | |
163 | A date calculated by the Lisp expression @var{sexp}. The expression | |
164 | should use the variable @code{year} to compute and return the date of a | |
f9b4c05d GM |
165 | holiday in the form of a list @code{(@var{month} @var{day} @var{year})}, |
166 | or @code{nil} if the holiday doesn't happen this year. | |
c5184807 EZ |
167 | |
168 | @item (if @var{condition} @var{holiday-form}) | |
169 | A holiday that happens only if @var{condition} is true. | |
170 | ||
171 | @item (@var{function} @r{[}@var{args}@r{]}) | |
172 | A list of dates calculated by the function @var{function}, called with | |
173 | arguments @var{args}. | |
174 | @end table | |
175 | ||
176 | For example, suppose you want to add Bastille Day, celebrated in | |
f9b4c05d GM |
177 | France on July 14 (i.e., the fourteenth day of the seventh month). You |
178 | can do this as follows: | |
c5184807 EZ |
179 | |
180 | @smallexample | |
98ad1bae | 181 | (setq holiday-other-holidays '((holiday-fixed 7 14 "Bastille Day"))) |
c5184807 EZ |
182 | @end smallexample |
183 | ||
c5184807 EZ |
184 | Many holidays occur on a specific day of the week, at a specific time |
185 | of month. Here is a holiday form describing Hurricane Supplication Day, | |
186 | celebrated in the Virgin Islands on the fourth Monday in August: | |
187 | ||
188 | @smallexample | |
189 | (holiday-float 8 1 4 "Hurricane Supplication Day") | |
190 | @end smallexample | |
191 | ||
192 | @noindent | |
193 | Here the 8 specifies August, the 1 specifies Monday (Sunday is 0, | |
194 | Tuesday is 2, and so on), and the 4 specifies the fourth occurrence in | |
195 | the month (1 specifies the first occurrence, 2 the second occurrence, | |
196 | @minus{}1 the last occurrence, @minus{}2 the second-to-last occurrence, and | |
197 | so on). | |
198 | ||
102f1b54 | 199 |