X-Git-Url: https://git.hcoop.net/bpt/emacs.git/blobdiff_plain/ecae6af979abcbb5b45c33ee05ceb297678ec9a0..11fdef7d0cf3ef1ce30d1cd09ca9ca9a2b099d20:/doc/emacs/cal-xtra.texi diff --git a/doc/emacs/cal-xtra.texi b/doc/emacs/cal-xtra.texi index c0e1e62bf9..52898efc26 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, 2005, 2006, 2007, 2008 Free Software Foundation, Inc. +@c Copyright (C) 2004-2011 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 @@ -13,27 +13,43 @@ diary suit your personal tastes. @menu -* Calendar Customizing:: Defaults you can set. +* Calendar Customizing:: Calendar layout and hooks. * Holiday Customizing:: Defining your own holidays. * Date Display Format:: Changing the format. * Time Display Format:: Changing the format. * Diary Customizing:: Defaults you can set. -* Hebrew/Islamic Entries:: How to obtain them. -* Fancy Diary Display:: Enhancing the diary display, sorting entries, - using included diary files. -* Sexp Diary Entries:: Fancy things you can do. +* Non-Gregorian Diary:: Diary entries based on other calendars. +* Diary Display:: A choice of ways to display the diary. +* Fancy Diary Display:: Sorting diary entries, using included diary files. +* Sexp Diary Entries:: More flexible diary entries. @end menu @node Calendar Customizing @subsection Customizing the Calendar + +@vindex calendar-intermonth-text +@cindex calendar layout +@cindex calendar week numbers + The calendar display unfortunately cannot be changed from three +months, but you can customize the whitespace used by setting the +variables: @code{calendar-left-margin}, +@code{calendar-day-header-width}, @code{calendar-day-digit-width}, +@code{calendar-column-width}, and @code{calendar-intermonth-spacing}. +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-holiday-marker @vindex diary-entry-marker +@vindex calenday-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 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. By default, the calendar uses -faces named @code{holiday} and @code{diary} for these purposes. +date as being 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 +@code{calendar-today} for these purposes. @vindex calendar-load-hook The variable @code{calendar-load-hook} is a normal hook run when the @@ -47,33 +63,17 @@ 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 @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 current date is visible in the window. One use of this hook is to -replace today's date with asterisks; to do that, use the hook function -@code{calendar-star-date}. - -@findex calendar-star-date -@example -(add-hook 'calendar-today-visible-hook 'calendar-star-date) -@end example - -@noindent -Another standard hook function marks the current date, either by -changing its face or by adding an asterisk. Here's how to use it: +mark today's date; to do that use either of the functions +@code{calendar-mark-today} or @code{calendar-star-date}: @findex calendar-mark-today -@example +@smallexample (add-hook 'calendar-today-visible-hook 'calendar-mark-today) -@end example - -@noindent -@vindex calendar-today-marker -The variable @code{calendar-today-marker} specifies how to mark -today's date. Its value should be a single-character string to insert -next to the date or a face name to use for displaying the date. A -face named @code{calendar-today} is provided for this purpose; that -symbol is the default for this variable. +@end smallexample @vindex calendar-today-invisible-hook @noindent @@ -88,33 +88,35 @@ the current date is @emph{not} visible in the window. @subsection Customizing the Holidays @vindex calendar-holidays -@vindex holiday-bahai-holidays -@vindex holiday-christian-holidays -@vindex holiday-hebrew-holidays -@vindex holiday-islamic-holidays +@vindex holiday-oriental-holidays +@vindex holiday-solar-holidays Emacs knows about holidays defined by entries on one of several lists. -You can customize these lists of holidays to your own needs, adding or -deleting holidays. The lists of holidays that Emacs uses are for -general holidays (@code{holiday-general-holidays}), local holidays -(@code{holiday-local-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}), sun- and moon-related holidays -(@code{holiday-solar-holidays}), and other holidays -(@code{holiday-other-holidays}). +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}). + +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. @vindex holiday-general-holidays The general holidays are, by default, holidays common throughout the -United States. To eliminate these holidays, set -@code{holiday-general-holidays} to @code{nil}. +United States. @vindex holiday-local-holidays - There are no default local holidays (but sites may supply some). You -can set the variable @code{holiday-local-holidays} to any list of -holidays, as described below. + There are no default local holidays, but your site may supply some. +@vindex holiday-bahai-holidays +@vindex holiday-christian-holidays +@vindex holiday-hebrew-holidays +@vindex holiday-islamic-holidays @vindex calendar-bahai-all-holidays-flag @vindex calendar-christian-all-holidays-flag @vindex calendar-hebrew-all-holidays-flag @@ -125,38 +127,34 @@ more extensive collection of religious holidays, you can set any (or all) of the variables @code{calendar-bahai-all-holidays-flag}, @code{calendar-christian-all-holidays-flag}, @code{calendar-hebrew-all-holidays-flag}, or -@code{calendar-islamic-all-holidays-flag} to @code{t}. If you want to -eliminate the religious holidays, set any or all of the corresponding -variables @code{holiday-bahai-holidays}, @code{holiday-christian-holidays}, -@code{holiday-hebrew-holidays}, and @code{holiday-islamic-holidays} to -@code{nil}.@refill +@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 lists (@code{holiday-general-holidays}, -@code{holiday-local-holidays}, @code{holiday-bahai-holidays}, -@code{holiday-christian-holidays}, @code{holiday-hebrew-holidays}, -@code{holiday-islamic-holidays}, @code{holiday-oriental-holidays}, -@code{holiday-solar-holidays}, and @code{holiday-other-holidays}) is a -list of @dfn{holiday forms}, each holiday form describing a holiday (or -sometimes a list of holidays). + 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 -name of the holiday, as a string. +description of the holiday, as a string. @table @code @item (holiday-fixed @var{month} @var{day} @var{string}) A fixed date on the Gregorian calendar. -@item (holiday-float @var{month} @var{dayname} @var{k} @var{string}) -The @var{k}th @var{dayname} in @var{month} on the Gregorian calendar -(@var{dayname}=0 for Sunday, and so on); negative @var{k} means count back -from the end of the month. +@item (holiday-float @var{month} @var{dayname} @var{k} @var{string} + &optional @var{day}) +The @var{k}th @var{dayname} (@var{dayname}=0 for Sunday, and so on) +after or before Gregorian date @var{month}, @var{day}. Negative @var{k} +means count back from the end of the month. Optional @var{day} defaults +to 1 if @var{k} is positive, and the last day of @var{month} otherwise. + +@item (holiday-chinese @var{month} @var{day} @var{string}) +A fixed date on the Chinese calendar. @item (holiday-hebrew @var{month} @var{day} @var{string}) A fixed date on the Hebrew calendar. @@ -170,9 +168,8 @@ A fixed date on the Julian calendar. @item (holiday-sexp @var{sexp} @var{string}) A date calculated by the Lisp expression @var{sexp}. The expression should use the variable @code{year} to compute and return the date of a -holiday, or @code{nil} if the holiday doesn't happen this year. The -value of @var{sexp} must represent the date as a list of the form -@code{(@var{month} @var{day} @var{year})}. +holiday in the form of a list @code{(@var{month} @var{day} @var{year})}, +or @code{nil} if the holiday doesn't happen this year. @item (if @var{condition} @var{holiday-form}) A holiday that happens only if @var{condition} is true. @@ -183,16 +180,13 @@ arguments @var{args}. @end table For example, suppose you want to add Bastille Day, celebrated in -France on July 14. You can do this as follows: +France on July 14 (i.e., the fourteenth day of the seventh month). You +can do this as follows: @smallexample -(setq other-holidays '((holiday-fixed 7 14 "Bastille Day"))) +(setq holiday-other-holidays '((holiday-fixed 7 14 "Bastille Day"))) @end smallexample -@noindent -The holiday form @code{(holiday-fixed 7 14 "Bastille Day")} specifies the -fourteenth day of the seventh month (July). - Many holidays occur on a specific day of the week, at a specific time of month. Here is a holiday form describing Hurricane Supplication Day, celebrated in the Virgin Islands on the fourth Monday in August: @@ -209,10 +203,10 @@ the month (1 specifies the first occurrence, 2 the second occurrence, so on). You can specify holidays that occur on fixed days of the Baha'i, -Hebrew, Islamic, and Julian calendars too. For example, +Chinese, Hebrew, Islamic, and Julian calendars too. For example, @smallexample -(setq other-holidays +(setq holiday-other-holidays '((holiday-hebrew 10 2 "Last day of Hanukkah") (holiday-islamic 3 12 "Mohammed's Birthday") (holiday-julian 4 2 "Jefferson's Birthday"))) @@ -225,13 +219,13 @@ birthday (since the Islamic months are numbered from 1 starting with Muharram), and Thomas Jefferson's birthday, which is 2 April 1743 on the Julian calendar. - To include a holiday conditionally, use either Emacs Lisp's @code{if} or the -@code{holiday-sexp} form. For example, American presidential elections -occur on the first Tuesday after the first Monday in November of years -divisible by 4: + To include a holiday conditionally, use either Emacs Lisp's @code{if} +or the @code{holiday-sexp} form. For example, American presidential +elections occur on the first Tuesday after the first Monday in November +of years divisible by 4: @smallexample -(holiday-sexp '(if (= 0 (% year 4)) +(holiday-sexp '(if (zerop (% year 4)) (calendar-gregorian-from-absolute (1+ (calendar-dayname-on-or-before 1 (+ 6 (calendar-absolute-from-gregorian @@ -243,8 +237,8 @@ divisible by 4: or @smallexample -(if (= 0 (% displayed-year 4)) - (fixed 11 +(if (zerop (% displayed-year 4)) + (holiday-fixed 11 (calendar-extract-day (calendar-gregorian-from-absolute (1+ (calendar-dayname-on-or-before @@ -289,10 +283,11 @@ while in the European style this value is the default: @end smallexample @noindent -The ISO standard date representation is this: +The default ISO date representation is: @smallexample -(year "-" month "-" day) +((format "%s-%.2d-%.2d" year (string-to-number month) + (string-to-number day))) @end smallexample @noindent @@ -314,8 +309,7 @@ you can alter the variable @code{calendar-time-display-form}. This variable is a list of expressions that can involve the variables @code{12-hours}, @code{24-hours}, and @code{minutes}, which are all numbers in string form, and @code{am-pm} and @code{time-zone}, which are -both alphabetic strings. The default value of -@code{calendar-time-display-form} is as follows: +both alphabetic strings. The default value is: @smallexample (12-hours ":" minutes am-pm @@ -330,47 +324,34 @@ Here is a value that provides European style times: (if time-zone " (") time-zone (if time-zone ")")) @end smallexample +Note that few calendar functions return a time of day (at present, only +solar functions). + @node Diary Customizing @subsection Customizing the Diary @vindex diary-show-holidays-flag - Ordinarily, the mode line of the diary buffer window indicates any -holidays that fall on the date of the diary entries. The process of -checking for holidays can take several seconds, so including holiday -information delays the display of the diary buffer noticeably. If you'd -prefer to have a faster display of the diary buffer but without the -holiday information, set the variable @code{diary-show-holidays-flag} to -@code{nil}.@refill + Ordinarily, the diary window indicates any holidays that fall on the +date of the diary entries, either in the mode line or the buffer itself. +The process of checking for holidays can be slow, depending on the +defined holidays. In that case, setting @code{diary-show-holidays-flag} +to @code{nil} will speed up the diary display. @vindex diary-number-of-entries The variable @code{diary-number-of-entries} controls the number of days of diary entries to be displayed at one time. It affects the initial display when @code{calendar-view-diary-initially-flag} is -@code{t}, as well as the command @kbd{M-x diary}. For example, the -default value is 1, which says to display only the current day's diary -entries. If the value is 2, both the current day's and the next day's -entries are displayed. The value can also be a vector of seven -elements: for example, if the value is @code{[0 2 2 2 2 4 1]} then no -diary entries appear on Sunday, the current date's and the next day's -diary entries appear Monday through Thursday, Friday through Monday's -entries appear on Friday, while on Saturday only that day's entries -appear. - -@vindex diary-print-entries-hook -@findex diary-print-entries - The variable @code{diary-print-entries-hook} is a normal hook run -after preparation of a temporary buffer containing just the diary -entries currently visible in the diary buffer. (The other, irrelevant -diary entries are really absent from the temporary buffer; in the diary -buffer, they are merely hidden.) The default value of this hook does -the printing with the command @code{lpr-buffer}. 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. +@code{t}, as well as the command @kbd{M-x diary}. For example, a value +of 1 (the default) displays only the current day's diary entries, +whereas a value of 2 will also show the next day's entries. The value +can also be a vector of seven integers: for example, if the value is +@code{[0 2 2 2 2 4 1]} then no diary entries appear on Sunday, the +current date's and the next day's diary entries appear Monday through +Thursday, Friday through Monday's entries appear on Friday, while on +Saturday only that day's entries appear. @vindex diary-date-forms - You can customize the form of dates in your diary file, if neither the -standard American nor European styles suits your needs, by setting the + You can customize the form of dates in your diary file by setting the variable @code{diary-date-forms}. This variable is a list of patterns for recognizing a date. Each date pattern is a list whose elements may be regular expressions (@pxref{Regular Expressions,,, elisp, the Emacs @@ -388,13 +369,14 @@ constituent. and @code{dayname} match the month number, day number, year number, month name, and day name of the date being considered. The symbols that match numbers allow leading zeros; those that match names allow -three-letter abbreviations and capitalization. All the symbols can -match @samp{*}; since @samp{*} in a diary entry means ``any day'', ``any -month'', and so on, it should match regardless of the date being -considered. +capitalization and abbreviation (as specified by +@code{calendar-month-abbrev-array} and +@code{calendar-day-abbrev-array}). All the symbols can match @samp{*}; +since @samp{*} in a diary entry means ``any day'', ``any month'', and so +on, it should match regardless of the date being considered. The default value of @code{diary-date-forms} in the American style is -this: +provided by @code{diary-american-date-forms}: @example ((month "/" day "[^/0-9]") @@ -404,6 +386,10 @@ this: (dayname "\\W")) @end example +@noindent +Other default styles are provided by @code{diary-european-date-forms} +and @code{diary-iso-date-forms}. + 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 one character of whitespace. If, to be mutually exclusive, the pattern @@ -413,13 +399,13 @@ that ends the date---then the first element of the date pattern up to the beginning of the current word of the diary entry, after finishing the match. Even if you use @code{backup}, the date pattern must absolutely not match more than a portion of the first word of the -diary entry. The default value of @code{diary-date-forms} in the -European style is this list: +diary entry. For example, the default value of +@code{diary-european-date-forms} is: @example ((day "/" month "[^/0-9]") (day "/" month "/" year "[^0-9]") - (backup day " *" monthname "\\W+\\<[^*0-9]") + (backup day " *" monthname "\\W+\\<\\([^*0-9]\\|\\([0-9]+[:aApP]\\)\\)") (day " *" monthname " *" year "[^0-9]") (dayname "\\W")) @end example @@ -429,42 +415,46 @@ Notice the use of @code{backup} in the third pattern, because it needs to match part of a word beyond the date itself to distinguish it from the fourth pattern. -@c FIXME Baha'i. -@node Hebrew/Islamic Entries -@subsection Hebrew- and Islamic-Date Diary Entries +@node Non-Gregorian Diary +@subsection Diary Entries Using non-Gregorian Calendars - Your diary file can have entries based on Baha'i, Hebrew, or Islamic -dates, as well as entries based on the world-standard Gregorian -calendar. However, because recognition of such entries is -time-consuming and 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, you must do this: + As well as entries based on the standard Gregorian calendar, your +diary can have entries based on Baha'i, 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, +you must do this: @vindex diary-nongregorian-listing-hook @vindex diary-nongregorian-marking-hook @findex diary-hebrew-list-entries @findex diary-hebrew-mark-entries +@findex diary-islamic-list-entries +@findex diary-islamic-mark-entries +@findex diary-bahai-list-entries +@findex diary-bahai-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 -If you want Islamic-date entries, do this: - -@findex diary-islamic-list-entries -@findex diary-islamic-mark-entries -@smallexample -(add-hook 'diary-nongregorian-listing-hook 'diary-islamic-list-entries) -(add-hook 'diary-nongregorian-marking-hook 'diary-islamic-mark-entries) -@end smallexample - - Hebrew- and Islamic-date diary entries have the same formats as -Gregorian-date diary entries, except that @samp{H} precedes a Hebrew -date and @samp{I} precedes an Islamic date. Moreover, because the -Hebrew and Islamic month names are not uniquely specified by the first -three letters, you may not abbreviate them. For example, a diary entry -for the Hebrew date Heshvan 25 could look like this: +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}. + +@vindex diary-bahai-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 +@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). +(Note also that you must use ``Adar I'' if you want Adar of a common +Hebrew year.) For example, a diary entry for the Hebrew date Heshvan 25 +could look like this: @smallexample HHeshvan 25 Happy Hebrew birthday! @@ -479,36 +469,33 @@ Dhu al-Qada 25: IDhu al-Qada 25 Happy Islamic birthday! @end smallexample - As with Gregorian-date diary entries, Hebrew- and Islamic-date entries -are nonmarking if they are preceded with an ampersand (@samp{&}). + As with Gregorian-date diary entries, non-Gregorian entries are +nonmarking if preceded by @code{diary-nonmarking-symbol} (default +@samp{&}). - 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 Hebrew -or Islamic calendar: + 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: @table @kbd @item i h d -Add a diary entry for the Hebrew date corresponding to the selected date -(@code{diary-hebrew-insert-entry}). +@code{diary-hebrew-insert-entry} @item i h m -Add a diary entry for the day of the Hebrew month corresponding to the -selected date (@code{diary-hebrew-insert-monthly-entry}). This diary -entry matches any date that has the same Hebrew day-within-month as the -selected date. +@code{diary-hebrew-insert-monthly-entry} @item i h y -Add a diary entry for the day of the Hebrew year corresponding to the -selected date (@code{diary-hebrew-insert-yearly-entry}). This diary -entry matches any date which has the same Hebrew month and day-within-month -as the selected date. +@code{diary-hebrew-insert-yearly-entry} @item i i d -Add a diary entry for the Islamic date corresponding to the selected date -(@code{diary-islamic-insert-entry}). +@code{diary-islamic-insert-entry} @item i i m -Add a diary entry for the day of the Islamic month corresponding to the -selected date (@code{diary-islamic-insert-monthly-entry}). +@code{diary-islamic-insert-monthly-entry} @item i i y -Add a diary entry for the day of the Islamic year corresponding to the -selected date (@code{diary-islamic-insert-yearly-entry}). +@code{diary-islamic-insert-yearly-entry} +@item i B d +@code{diary-bahai-insert-entry} +@item i B m +@code{diary-bahai-insert-monthly-entry} +@item i B y +@code{diary-bahai-insert-yearly-entry} @end table @findex diary-hebrew-insert-entry @@ -517,53 +504,105 @@ selected date (@code{diary-islamic-insert-yearly-entry}). @findex diary-islamic-insert-entry @findex diary-islamic-insert-monthly-entry @findex diary-islamic-insert-yearly-entry +@findex diary-bahai-insert-entry +@findex diary-bahai-insert-monthly-entry +@findex diary-bahai-insert-yearly-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 entry -at the end of your diary file. You must then insert the rest of the -diary entry. - -@node Fancy Diary Display -@subsection Fancy Diary Display -@vindex diary-display-hook +window, and what they do is insert just the date portion of a diary +entry at the end of your diary file. You must then insert the rest of +the diary entry. The basic commands add an entry for the specific +non-Gregorian date, the @samp{monthly} commands for the given +non-Gregorian day-within-month in every month, and the @samp{yearly} +commands for the given non-Gregorian day and month in every year. + +@node Diary Display +@subsection Diary Display +@vindex diary-display-function @findex diary-simple-display - - Diary display works by preparing the diary buffer and then running the -hook @code{diary-display-hook}. The default value of this hook -(@code{diary-simple-display}) hides the irrelevant diary entries and -then displays the buffer. However, if you specify the hook as follows, - -@cindex diary buffer @findex diary-fancy-display -@example -(add-hook 'diary-display-hook 'diary-fancy-display) -@end example +@cindex diary buffer -@noindent -this enables fancy diary display. It displays diary entries and -holidays by copying them into a special buffer that exists only for the -sake of display. Copying to a separate buffer provides an opportunity -to change the displayed text to make it prettier---for example, to sort -the entries by the dates they apply to. - - As with simple diary display, you can print a hard copy of the buffer -with @code{diary-print-entries}. To print a hard copy of a day-by-day -diary for a week, position point on Sunday of that week, type -@kbd{7 d}, and then do @kbd{M-x diary-print-entries}. As usual, the -inclusion of the holidays slows down the display slightly; you can speed -things up by setting the variable @code{diary-show-holidays-flag} to -@code{nil}. + Diary display works by preparing the list of diary entries and then +running the function specified by the variable +@code{diary-display-function}. The default value +@code{diary-fancy-display} displays diary entries and holidays by +copying them into a special buffer that exists only for the sake of +display. Copying diary entries to a separate buffer provides an +opportunity to change the displayed text to make it prettier---for +example, to sort the entries by the dates they apply to. @vindex diary-list-include-blanks - 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 + 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 +@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 alternative display method @code{diary-simple-display} shows the +actual diary buffer, and uses invisible text to hide entries that don't +apply. Holidays are shown in the mode line. The advantage of this +method is that you can edit the buffer and save your changes directly to +the diary file. This method is not as flexible as the fancy method, +however. For example, it cannot sort entries. Another disadvantage is +that invisible text can be confusing. For example, if you copy a region +of text in order to paste it elsewhere, invisible text may be included. +Similarly, since the diary buffer as you see it is an illusion, simply +printing the buffer may not print what you see on your screen. + +@vindex diary-print-entries-hook +@findex diary-print-entries + For this reason, there is a special command to print hard copy of the +diary buffer @emph{as it appears}; this command is @kbd{M-x +diary-print-entries}. It works with either display method, although +with the fancy display you can also print the buffer like any other. To +print a hard copy of a day-by-day diary for a week, position point on +the first day of the week, type @kbd{7 d}, and then do @kbd{M-x +diary-print-entries}. As usual, the inclusion of the holidays slows +down the display slightly; you can speed things up by setting the +variable @code{diary-show-holidays-flag} to @code{nil}. + + This command prepares a temporary buffer that contains only the diary +entries currently visible in the diary buffer. Unlike with the simple +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 +printing, just change the value of this hook. Other uses might include, +for example, rearranging the lines into order by day and time. + + You can edit the diary entries as they appear in the simple diary +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 in the simple display!} +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 simple diary +buffer, it is best to display the entire file with @kbd{s} +(@code{diary-show-all-entries}). + +@node Fancy Diary Display +@subsection Fancy Diary Display + +The following features only work with the fancy diary display. + @cindex sorting diary entries - If you use the fancy diary display, you can use the normal hook -@code{diary-list-entries-hook} to sort each day's diary entries by their -time of day. Here's how: + You can use the normal hook @code{diary-list-entries-hook} to sort +each day's diary entries by their time of day. Here's how: @findex diary-sort-entries @example @@ -573,22 +612,39 @@ time of day. Here's how: @noindent For each day, this sorts diary entries that begin with a recognizable time of day according to their times. Diary entries without times come -first within each day. - - Fancy diary display also has the ability to process included diary -files. This permits a group of people to share a diary file for events -that apply to all of them. Lines in the diary file of this form: +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. +Lines in the diary file starting with @code{diary-include-string}: @smallexample #include "@var{filename}" @end smallexample @noindent -includes the diary entries from the file @var{filename} in the fancy -diary buffer. The include mechanism is recursive, so that included files -can include other files, and so on; you must be careful not to have a -cycle of inclusions, of course. Here is how to enable the include -facility: +include the diary entries from the file @var{filename} in the fancy +diary buffer. The include mechanism is recursive, so that included +files can include other files, and so on (you must be careful not to +have a cycle of inclusions, of course). Here is how to enable the +include facility: @vindex diary-list-entries-hook @vindex diary-mark-entries-hook @@ -600,16 +656,20 @@ facility: @end smallexample The include mechanism works only with the fancy diary display, because -ordinary diary display shows the entries directly from your diary file. +simple diary display shows the entries directly from your diary file. @node Sexp Diary Entries @subsection Sexp Entries and the Fancy Diary Display @cindex sexp diary entries +@vindex diary-sexp-entry-symbol Sexp diary entries allow you to do more than just have complicated -conditions under which a diary entry applies. If you use the fancy -diary display, sexp entries can generate the text of the entry depending -on the date itself. For example, an anniversary diary entry can insert +conditions under which a diary entry applies. Sexp entries should be +preceded by @code{diary-sexp-entry-symbol} (default @samp{%%}) in the +diary file. With the fancy diary display, sexp entries can generate the +text of the entry depending on the date itself. + +For example, an anniversary diary entry can insert the number of years since the anniversary date into the text of the diary entry. Thus the @samp{%d} in this diary entry: @@ -669,18 +729,13 @@ can use @end smallexample @noindent -and the fancy diary will show -@smallexample -Ed's anniversary -@end smallexample -@noindent -both on December 15 and on December 22. +and the fancy diary will show @samp{Ed's anniversary} both on December +15 and on December 22. @findex diary-date The function @code{diary-date} applies to dates described by a month, day, year combination, each of which can be an integer, a list of -integers, or @code{t}. The value @code{t} means all values. For -example, +integers, or @code{t} (meaning all values). For example, @smallexample %%(diary-date '(10 11 12) 22 t) Rake leaves @@ -700,7 +755,7 @@ on October 22, November 22, and December 22 of every year. The function @code{diary-float} allows you to describe diary entries that apply to dates like the third Friday of November, or the last Tuesday in April. The parameters are the @var{month}, @var{dayname}, -and an index @var{n}. The entry appears on the @var{n}th @var{dayname} +and an index @var{n}. The entry appears on the @var{n}th @var{dayname} after the first day of @var{month}, where @var{dayname}=0 means Sunday, 1 means Monday, and so on. If @var{n} is negative it counts backward from the end of @var{month}. The value of @var{month} can be a list of @@ -750,7 +805,7 @@ a sexp diary entry that matches those dates: @smallexample &%%(let ((dayname (calendar-day-of-week date)) - (day (car (cdr date)))) + (day (cadr date))) (or (and (= day 21) (memq dayname '(1 2 3 4 5))) (and (memq day '(19 20)) (= dayname 5))) ) Pay check deposited @@ -760,20 +815,24 @@ a sexp diary entry that matches those dates: diary display) to concoct diary entries whose text varies based on the date: @findex diary-sunrise-sunset -@findex diary-phases-of-moon +@findex diary-lunar-phases @findex diary-day-of-year @findex diary-iso-date @findex diary-julian-date @findex diary-astro-day-number @findex diary-bahai-date +@findex diary-chinese-date +@findex diary-coptic-date +@findex diary-ethiopic-date @findex diary-hebrew-date @findex diary-islamic-date @findex diary-french-date @findex diary-mayan-date +@findex diary-persian-date @table @code @item %%(diary-sunrise-sunset) -Make a diary entry for the local times of today's sunrise and sunset. -@item %%(diary-phases-of-moon) +Make a diary entry for today's local times of sunrise and sunset. +@item %%(diary-lunar-phases) Make a diary entry for the phases (quarters) of the moon. @item %%(diary-day-of-year) Make a diary entry with today's day number in the current year and the number @@ -781,37 +840,45 @@ of days remaining in the current year. @item %%(diary-iso-date) Make a diary entry with today's equivalent ISO commercial date. @item %%(diary-julian-date) -Make a diary entry with today's equivalent date on the Julian calendar. +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 date on the Baha'i calendar. -@item %%(diary-hebrew-date) -Make a diary entry with today's equivalent date on the Hebrew calendar. -@item %%(diary-islamic-date) -Make a diary entry with today's equivalent date on the Islamic calendar. +Make a diary entry with today's equivalent Baha'i calendar date. +@item %%(diary-chinese-date) +Make a diary entry with today's equivalent Chinese calendar date. +@item %%(diary-coptic-date) +Make a diary entry with today's equivalent Coptic calendar date. +@item %%(diary-ethiopic-date) +Make a diary entry with today's equivalent Ethiopic calendar date. @item %%(diary-french-date) Make a diary entry with today's equivalent date on the French Revolutionary calendar. +@item %%(diary-hebrew-date) +Make a diary entry with today's equivalent Hebrew calendar date. +@item %%(diary-islamic-date) +Make a diary entry with today's equivalent Islamic calendar date. @item %%(diary-mayan-date) -Make a diary entry with today's equivalent date on the Mayan calendar. +Make a diary entry with today's equivalent Mayan calendar date. +@item %%(diary-persian-date) +Make a diary entry with today's equivalent Persian calendar date. @end table @noindent -Thus including the diary entry +For example, including the diary entry -@example +@smallexample &%%(diary-hebrew-date) -@end example +@end smallexample @noindent causes every day's diary display to contain the equivalent date on the Hebrew calendar, if you are using the fancy diary display. (With simple -diary display, the line @samp{&%%(diary-hebrew-date)} appears in the -diary for any date, but does nothing particularly useful.) +diary display, the literal line @samp{&%%(diary-hebrew-date)} appears in +the diary for any date.) - These functions can be used to construct sexp diary entries based on -the Hebrew calendar in certain standard ways: + This function has been used to construct certain standard Hebrew sexp +diary entries: @cindex rosh hodesh @findex diary-hebrew-rosh-hodesh @@ -823,6 +890,7 @@ the Hebrew calendar in certain standard ways: @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 @@ -837,16 +905,14 @@ Make a diary entry that gives the omer count, when appropriate. @item %%(diary-hebrew-yahrzeit @var{month} @var{day} @var{year}) @var{name} Make a diary entry marking the anniversary of a date of death. The date is the @emph{Gregorian} (civil) date of death. The diary entry appears -on the proper Hebrew calendar anniversary and on the day before. (In -the European style, the order of the parameters is changed to @var{day}, -@var{month}, @var{year}.) +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}. - -@ignore - arch-tag: 52cb299f-fd1f-4616-bfe6-91b988669431 -@end ignore +it returns a value that contains @var{mark}, as described above.