-@c This is part of the Emacs manual.
-@c Copyright (C) 2004, 2005, 2006, 2007, 2008, 2009
-@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
@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.
@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
@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}:
@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
@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})
@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
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
@end smallexample
@noindent
-This specifies a typical American format:
+Another typical American format is:
@smallexample
(month "/" day "/" (substring year -2))
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,
@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
@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,
@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}.
@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).
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
days to be shown in the fancy diary buffer, set the variable
@code{diary-list-include-blanks} to @code{t}.@refill
- The alternative method @code{diary-simple-display} displays 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.
+ 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
+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
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.
@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.
+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
@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
@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
@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)
@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
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