mirror of
https://git.savannah.gnu.org/git/emacs.git
synced 2024-12-23 10:34:07 +00:00
678e7c71c4
* doclicense.texi (GNU Free Documentation License): Update to version 1.2.
1236 lines
48 KiB
Plaintext
1236 lines
48 KiB
Plaintext
\input texinfo @c -*-texinfo-*-
|
|
@comment %**start of header
|
|
@setfilename ../info/emacs-xtra
|
|
@settitle Specialized Emacs Features
|
|
@syncodeindex fn cp
|
|
@syncodeindex vr cp
|
|
@syncodeindex ky cp
|
|
@comment %**end of header
|
|
|
|
@copying
|
|
This manual describes specialized features of Emacs.
|
|
|
|
Copyright (C) 2004, 2005 Free Software Foundation, Inc.
|
|
|
|
@quotation
|
|
Permission is granted to copy, distribute and/or modify this document
|
|
under the terms of the GNU Free Documentation License, Version 1.2 or
|
|
any later version published by the Free Software Foundation; with no
|
|
Invariant Sections, with the Front-Cover texts being ``A GNU
|
|
Manual'', and with the Back-Cover Texts as in (a) below. A copy of the
|
|
license is included in the section entitled ``GNU Free Documentation
|
|
License'' in the Emacs manual.
|
|
|
|
(a) The FSF's Back-Cover Text is: ``You have freedom to copy and modify
|
|
this GNU Manual, like GNU software. Copies published by the Free
|
|
Software Foundation raise funds for GNU development.''
|
|
|
|
This document is part of a collection distributed under the GNU Free
|
|
Documentation License. If you want to distribute this document
|
|
separately from the collection, you can do so by adding a copy of the
|
|
license to the document, as described in section 6 of the license.
|
|
@end quotation
|
|
@end copying
|
|
|
|
@dircategory Emacs
|
|
@direntry
|
|
* Emacs-Xtra: (emacs-xtra). Specialized Emacs features.
|
|
@end direntry
|
|
|
|
@titlepage
|
|
@title Specialized Emacs Features
|
|
@page
|
|
@vskip 0pt plus 1filll
|
|
@insertcopying
|
|
@end titlepage
|
|
|
|
@contents
|
|
|
|
@ifnottex
|
|
@node Top
|
|
@top Specialized Emacs Features
|
|
|
|
@insertcopying
|
|
|
|
@end ifnottex
|
|
|
|
@menu
|
|
* Introduction:: What documentation belongs here?
|
|
* Autorevert:: Auto Reverting non-file buffers.
|
|
* Subdir switches:: Subdirectory switches in Dired.
|
|
* Advanced Calendar/Diary Usage:: Advanced Calendar/Diary customization.
|
|
* Index::
|
|
@end menu
|
|
|
|
@node Introduction
|
|
@unnumbered Introduction
|
|
|
|
This manual contains detailed information about various features that
|
|
are too specialized to be included in the Emacs manual. It is
|
|
intended to be readable by anyone having a basic knowledge of Emacs.
|
|
However, certain sections may be intended for a more specialized
|
|
audience, such as Elisp authors. This should be clearly pointed out
|
|
at the beginning of these sections.
|
|
|
|
This manual is intended as a complement, rather than an alternative,
|
|
to other ways to gain a more detailed knowledge of Emacs than the
|
|
Emacs manual can provide, such as browsing packages using @kbd{C-h p},
|
|
accessing mode documentation using @kbd{C-h m} and browsing user
|
|
options using Custom. Also, certain packages, or collections of
|
|
related features, have their own manuals. The present manual is
|
|
mainly intended to be a collection of smaller specialized features,
|
|
too small to get their own manual.
|
|
|
|
Sections intended specifically for Elisp programmers can follow the
|
|
style of the Elisp manual. Other sections should follow the style of
|
|
the Emacs manual.
|
|
|
|
@node Autorevert
|
|
@chapter Auto Reverting non-file Buffers
|
|
|
|
Normally Global Auto Revert Mode only reverts file buffers. There are
|
|
two ways to auto-revert certain non-file buffers: enabling Auto Revert
|
|
Mode in those buffers (using @kbd{M-x auto-revert-mode}) and setting
|
|
@code{global-auto-revert-non-file-buffers} to @code{t}. The latter
|
|
enables Auto Reverting for all types of buffers for which it is
|
|
implemented, that is, for the types of buffers listed in the menu
|
|
below.
|
|
|
|
Like file buffers, non-file buffers should normally not revert while
|
|
you are working on them, or while they contain information that might
|
|
get lost after reverting. Therefore, they do not revert if they are
|
|
``modified''. This can get tricky, because deciding when a non-file
|
|
buffer should be marked modified is usually more difficult than for
|
|
file buffers.
|
|
|
|
Another tricky detail is that, for efficiency reasons, Auto Revert
|
|
often does not try to detect all possible changes in the buffer, only
|
|
changes that are ``major'' or easy to detect. Hence, enabling
|
|
auto-reverting for a non-file buffer does not always guarantee that
|
|
all information in the buffer is up to date and does not necessarily
|
|
make manual reverts useless.
|
|
|
|
At the other extreme, certain buffers automatically auto-revert every
|
|
@code{auto-revert-interval} seconds. (This currently only applies to
|
|
the Buffer Menu.) In this case, Auto Revert does not print any
|
|
messages while reverting, even when @code{auto-revert-verbose} is
|
|
non-@code{nil}.
|
|
|
|
The details depend on the particular types of buffers and are
|
|
explained in the corresponding sections.
|
|
|
|
@menu
|
|
* Auto Reverting the Buffer Menu::
|
|
* Auto Reverting Dired::
|
|
* Supporting additional buffers::
|
|
@end menu
|
|
|
|
@node Auto Reverting the Buffer Menu
|
|
@section Auto Reverting the Buffer Menu
|
|
|
|
If auto-reverting of non-file buffers is enabled, the Buffer Menu
|
|
automatically reverts every @code{auto-revert-interval} seconds,
|
|
whether there is a need for it or not. (It would probably take longer
|
|
to check whether there is a need than to actually revert.)
|
|
|
|
If the Buffer Menu inappropriately gets marked modified, just revert
|
|
it manually using @kbd{g} and auto-reverting will resume. However, if
|
|
you marked certain buffers to get deleted or to be displayed, you have
|
|
to be careful, because reverting erases all marks. The fact that
|
|
adding marks sets the buffer's modified flag prevents Auto Revert from
|
|
automatically erasing the marks.
|
|
|
|
@node Auto Reverting Dired
|
|
@section Auto Reverting Dired buffers
|
|
|
|
Auto-reverting Dired buffers currently works on GNU or Unix style
|
|
operating systems. It may not work satisfactorily on some other
|
|
systems.
|
|
|
|
Dired buffers only auto-revert when the file list of the buffer's main
|
|
directory changes. They do not auto-revert when information about a
|
|
particular file changes or when inserted subdirectories change. To be
|
|
sure that @emph{all} listed information is up to date, you have to
|
|
manually revert using @kbd{g}, @emph{even} if auto-reverting is
|
|
enabled in the Dired buffer. Sometimes, you might get the impression
|
|
that modifying or saving files listed in the main directory actually
|
|
does cause auto-reverting. This is because making changes to a file,
|
|
or saving it, very often causes changes in the directory itself, for
|
|
instance, through backup files or auto-save files. However, this is
|
|
not guaranteed.
|
|
|
|
If the Dired buffer is marked modified and there are no changes you
|
|
want to protect, then most of the time you can make auto-reverting
|
|
resume by manually reverting the buffer using @kbd{g}. There is one
|
|
exception. If you flag or mark files, you can safely revert the
|
|
buffer. This will not erase the flags or marks (unless the marked
|
|
file has been deleted, of course). However, the buffer will stay
|
|
modified, even after reverting, and auto-reverting will not resume.
|
|
This is because, if you flag or mark files, you may be working on the
|
|
buffer and you might not want the buffer to change without warning.
|
|
If you want auto-reverting to resume in the presence of marks and
|
|
flags, mark the buffer non-modified using @kbd{M-~}. However, adding,
|
|
deleting or changing marks or flags will mark it modified again.
|
|
|
|
Remote Dired buffers are not auto-reverted. Neither are Dired buffers
|
|
for which you used shell wildcards or file arguments to list only some
|
|
of the files. @samp{*Find*} and @samp{*Locate*} buffers do not
|
|
auto-revert either.
|
|
|
|
@node Supporting additional buffers
|
|
@section Adding Support for Auto-Reverting additional Buffers.
|
|
|
|
This section is intended for Elisp programmers who would like to add
|
|
support for auto-reverting new types of buffers.
|
|
|
|
To support auto-reverting the buffer must first of all have a
|
|
@code{revert-buffer-function}. @xref{Definition of
|
|
revert-buffer-function,, Reverting, elisp, the Emacs Lisp Reference Manual}.
|
|
|
|
In addition, it @emph{must} have a @code{buffer-stale-function}.
|
|
|
|
@defvar buffer-stale-function
|
|
The value of this variable is a function to check whether a non-file
|
|
buffer needs reverting. This should be a function with one optional
|
|
argument @var{noconfirm}. The function should return non-@code{nil}
|
|
if the buffer should be reverted. The buffer is current when this
|
|
function is called.
|
|
|
|
While this function is mainly intended for use in auto-reverting, it
|
|
could be used for other purposes as well. For instance, if
|
|
auto-reverting is not enabled, it could be used to warn the user that
|
|
the buffer needs reverting. The idea behind the @var{noconfirm}
|
|
argument is that it should be @code{t} if the buffer is going to be
|
|
reverted without asking the user and @code{nil} if the function is
|
|
just going to be used to warn the user that the buffer is out of date.
|
|
In particular, for use in auto-reverting, @var{noconfirm} is @code{t}.
|
|
If the function is only going to be used for auto-reverting, you can
|
|
ignore the @var{noconfirm} argument.
|
|
|
|
If you just want to automatically auto-revert every
|
|
@code{auto-revert-interval} seconds, use:
|
|
|
|
@example
|
|
(set (make-local-variable 'buffer-stale-function)
|
|
#'(lambda (&optional noconfirm) 'fast))
|
|
@end example
|
|
|
|
@noindent
|
|
in the buffer's mode function.
|
|
|
|
The special return value @samp{fast} tells the caller that the need
|
|
for reverting was not checked, but that reverting the buffer is fast.
|
|
It also tells Auto Revert not to print any revert messages, even if
|
|
@code{auto-revert-verbose} is non-@code{nil}. This is important, as
|
|
getting revert messages every @code{auto-revert-interval} seconds can
|
|
be very annoying. The information provided by this return value could
|
|
also be useful if the function is consulted for purposes other than
|
|
auto-reverting.
|
|
@end defvar
|
|
|
|
Once the buffer has a @code{revert-buffer-function} and a
|
|
@code{buffer-stale-function}, several problems usually remain.
|
|
|
|
The buffer will only auto-revert if it is marked unmodified. Hence,
|
|
you will have to make sure that various functions mark the buffer
|
|
modified if and only if either the buffer contains information that
|
|
might be lost by reverting or there is reason to believe that the user
|
|
might be inconvenienced by auto-reverting, because he is actively
|
|
working on the buffer. The user can always override this by manually
|
|
adjusting the modified status of the buffer. To support this, calling
|
|
the @code{revert-buffer-function} on a buffer that is marked
|
|
unmodified should always keep the buffer marked unmodified.
|
|
|
|
It is important to assure that point does not continuously jump around
|
|
as a consequence of auto-reverting. Of course, moving point might be
|
|
inevitable if the buffer radically changes.
|
|
|
|
You should make sure that the @code{revert-buffer-function} does not
|
|
print messages that unnecessarily duplicate Auto Revert's own messages
|
|
if @code{auto-revert-verbose} is @code{t} and effectively override a
|
|
@code{nil} value for @code{auto-revert-verbose}. Hence, adapting a
|
|
mode for auto-reverting often involves getting rid of such messages.
|
|
This is especially important for buffers that automatically
|
|
auto-revert every @code{auto-revert-interval} seconds.
|
|
|
|
Also, you may want to update the documentation string of
|
|
@code{global-auto-revert-non-file-buffers}.
|
|
|
|
@ifinfo
|
|
Finally, you should add a node to this chapter's menu. This node
|
|
@end ifinfo
|
|
@ifnotinfo
|
|
Finally, you should add a section to this chapter. This section
|
|
@end ifnotinfo
|
|
should at the very least make clear whether enabling auto-reverting
|
|
for the buffer reliably assures that all information in the buffer is
|
|
completely up to date (or will be after @code{auto-revert-interval}
|
|
seconds).
|
|
|
|
@node Subdir switches
|
|
@chapter Subdirectory Switches in Dired
|
|
|
|
You can insert subdirectories with specified @code{ls} switches in
|
|
Dired buffers, using @kbd{C-u i}. You can change the @code{ls}
|
|
switches of an already inserted subdirectory using @kbd{C-u l}.
|
|
|
|
In Emacs versions 22.1 and later, Dired remembers the switches, so
|
|
that reverting the buffer will not change them back to the main
|
|
directory's switches. Deleting a subdirectory forgets about its
|
|
switches.
|
|
|
|
Using @code{dired-undo} (usually bound to @kbd{C-_} and @kbd{C-x u})
|
|
to reinsert or delete subdirectories, that were inserted with explicit
|
|
switches, can bypass Dired's machinery for remembering (or forgetting)
|
|
switches. Deleting a subdirectory using @code{dired-undo} does not
|
|
forget its switches. When later reinserted using @kbd{i}, it will be
|
|
reinserted using its old switches. Using @code{dired-undo} to
|
|
reinsert a subdirectory that was deleted using the regular
|
|
Dired commands (not @code{dired-undo}) will originally insert it with
|
|
its old switches. However, reverting the buffer will relist it using
|
|
the buffer's default switches. If any of this yields problems, you
|
|
can easily correct the situation using @kbd{C-u i} or @kbd{C-u l}.
|
|
|
|
Dired does not remember the @code{R} switch. Inserting a subdirectory
|
|
with switches that include the @code{R} switch is equivalent with
|
|
inserting each of its subdirectories using all remaining switches.
|
|
For instance, updating or killing a subdirectory that was inserted
|
|
with the @code{R} switch will not update or kill its subdirectories.
|
|
|
|
The buffer's default switches do not affect subdirectories that were
|
|
inserted using explicitly specified switches. In particular,
|
|
commands such as @kbd{s}, that change the buffer's switches do not
|
|
affect such subdirectories. (They do affect subdirectories without
|
|
explicitly assigned switches, however.)
|
|
|
|
You can make Dired forget about all subdirectory switches and relist
|
|
all subdirectories with the buffer's default switches using
|
|
@kbd{M-x dired-reset-subdir-switches}. This also reverts the Dired buffer.
|
|
|
|
|
|
@c Moved here from the Emacs Lisp Reference Manual, 2005-03-26.
|
|
@node Advanced Calendar/Diary Usage
|
|
@chapter Customizing the Calendar and Diary
|
|
|
|
There are many customizations that you can use to make the calendar and
|
|
diary suit your personal tastes.
|
|
|
|
@menu
|
|
* Calendar Customizing:: Defaults you can set.
|
|
* Holiday Customizing:: Defining your own holidays.
|
|
* Date Display Format:: Changing the format.
|
|
* Time Display Format:: Changing the format.
|
|
* Daylight Savings:: Changing the default.
|
|
* 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.
|
|
@end menu
|
|
|
|
@node Calendar Customizing
|
|
@section Customizing the Calendar
|
|
@vindex calendar-holiday-marker
|
|
@vindex diary-entry-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. The calendar creates faces
|
|
named @code{holiday-face} and @code{diary-face} for these purposes;
|
|
those symbols are the default values of these variables.
|
|
|
|
@vindex calendar-load-hook
|
|
The variable @code{calendar-load-hook} is a normal hook run when the
|
|
calendar package is first loaded (before actually starting to display
|
|
the calendar).
|
|
|
|
@vindex initial-calendar-window-hook
|
|
Starting the calendar runs the normal hook
|
|
@code{initial-calendar-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
|
|
|
|
@vindex today-visible-calendar-hook
|
|
The variable @code{today-visible-calendar-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 'today-visible-calendar-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:
|
|
|
|
@findex calendar-mark-today
|
|
@example
|
|
(add-hook 'today-visible-calendar-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-face} is provided for this purpose;
|
|
that symbol is the default for this variable.
|
|
|
|
@vindex today-invisible-calendar-hook
|
|
@noindent
|
|
A similar normal hook, @code{today-invisible-calendar-hook} is run if
|
|
the current date is @emph{not} visible in the window.
|
|
|
|
@vindex calendar-move-hook
|
|
Each of the calendar cursor motion commands runs the hook
|
|
@code{calendar-move-hook} after it moves the cursor.
|
|
|
|
@node Holiday Customizing
|
|
@section Customizing the Holidays
|
|
|
|
@vindex calendar-holidays
|
|
@vindex christian-holidays
|
|
@vindex hebrew-holidays
|
|
@vindex islamic-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{general-holidays}), local holidays
|
|
(@code{local-holidays}), Christian holidays (@code{christian-holidays}),
|
|
Hebrew (Jewish) holidays (@code{hebrew-holidays}), Islamic (Muslim)
|
|
holidays (@code{islamic-holidays}), and other holidays
|
|
(@code{other-holidays}).
|
|
|
|
@vindex general-holidays
|
|
The general holidays are, by default, holidays common throughout the
|
|
United States. To eliminate these holidays, set @code{general-holidays}
|
|
to @code{nil}.
|
|
|
|
@vindex local-holidays
|
|
There are no default local holidays (but sites may supply some). You
|
|
can set the variable @code{local-holidays} to any list of holidays, as
|
|
described below.
|
|
|
|
@vindex all-christian-calendar-holidays
|
|
@vindex all-hebrew-calendar-holidays
|
|
@vindex all-islamic-calendar-holidays
|
|
By default, Emacs does not include all the holidays of the religions
|
|
that it knows, only those commonly found in secular calendars. For a
|
|
more extensive collection of religious holidays, you can set any (or
|
|
all) of the variables @code{all-christian-calendar-holidays},
|
|
@code{all-hebrew-calendar-holidays}, or
|
|
@code{all-islamic-calendar-holidays} to @code{t}. If you want to
|
|
eliminate the religious holidays, set any or all of the corresponding
|
|
variables @code{christian-holidays}, @code{hebrew-holidays}, and
|
|
@code{islamic-holidays} to @code{nil}.@refill
|
|
|
|
@vindex other-holidays
|
|
You can set the variable @code{other-holidays} to any list of
|
|
holidays. This list, normally empty, is intended for individual use.
|
|
|
|
@cindex holiday forms
|
|
Each of the lists (@code{general-holidays}, @code{local-holidays},
|
|
@code{christian-holidays}, @code{hebrew-holidays},
|
|
@code{islamic-holidays}, and @code{other-holidays}) is a list of
|
|
@dfn{holiday forms}, each holiday 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.
|
|
|
|
@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-hebrew @var{month} @var{day} @var{string})
|
|
A fixed date on the Hebrew calendar.
|
|
|
|
@item (holiday-islamic @var{month} @var{day} @var{string})
|
|
A fixed date on the Islamic calendar.
|
|
|
|
@item (holiday-julian @var{month} @var{day} @var{string})
|
|
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})}.
|
|
|
|
@item (if @var{condition} @var{holiday-form})
|
|
A holiday that happens only if @var{condition} is true.
|
|
|
|
@item (@var{function} @r{[}@var{args}@r{]})
|
|
A list of dates calculated by the function @var{function}, called with
|
|
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:
|
|
|
|
@smallexample
|
|
(setq 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:
|
|
|
|
@smallexample
|
|
(holiday-float 8 1 4 "Hurricane Supplication Day")
|
|
@end smallexample
|
|
|
|
@noindent
|
|
Here the 8 specifies August, the 1 specifies Monday (Sunday is 0,
|
|
Tuesday is 2, and so on), and the 4 specifies the fourth occurrence in
|
|
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 Hebrew,
|
|
Islamic, and Julian calendars too. For example,
|
|
|
|
@smallexample
|
|
(setq other-holidays
|
|
'((holiday-hebrew 10 2 "Last day of Hanukkah")
|
|
(holiday-islamic 3 12 "Mohammed's Birthday")
|
|
(holiday-julian 4 2 "Jefferson's Birthday")))
|
|
@end smallexample
|
|
|
|
@noindent
|
|
adds the last day of Hanukkah (since the Hebrew months are numbered with
|
|
1 starting from Nisan), the Islamic feast celebrating Mohammed's
|
|
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:
|
|
|
|
@smallexample
|
|
(holiday-sexp '(if (= 0 (% year 4))
|
|
(calendar-gregorian-from-absolute
|
|
(1+ (calendar-dayname-on-or-before
|
|
1 (+ 6 (calendar-absolute-from-gregorian
|
|
(list 11 1 year)))))))
|
|
"US Presidential Election")
|
|
@end smallexample
|
|
|
|
@noindent
|
|
or
|
|
|
|
@smallexample
|
|
(if (= 0 (% displayed-year 4))
|
|
(fixed 11
|
|
(extract-calendar-day
|
|
(calendar-gregorian-from-absolute
|
|
(1+ (calendar-dayname-on-or-before
|
|
1 (+ 6 (calendar-absolute-from-gregorian
|
|
(list 11 1 displayed-year)))))))
|
|
"US Presidential Election"))
|
|
@end smallexample
|
|
|
|
Some holidays just don't fit into any of these forms because special
|
|
calculations are involved in their determination. In such cases you
|
|
must write a Lisp function to do the calculation. To include eclipses,
|
|
for example, add @code{(eclipses)} to @code{other-holidays}
|
|
and write an Emacs Lisp function @code{eclipses} that returns a
|
|
(possibly empty) list of the relevant Gregorian dates among the range
|
|
visible in the calendar window, with descriptive strings, like this:
|
|
|
|
@smallexample
|
|
(((6 27 1991) "Lunar Eclipse") ((7 11 1991) "Solar Eclipse") ... )
|
|
@end smallexample
|
|
|
|
@node Date Display Format
|
|
@section 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}.
|
|
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
|
|
alphabetic strings. In the American style, the default value of this
|
|
list is as follows:
|
|
|
|
@smallexample
|
|
((if dayname (concat dayname ", ")) monthname " " day ", " year)
|
|
@end smallexample
|
|
|
|
@noindent
|
|
while in the European style this value is the default:
|
|
|
|
@smallexample
|
|
((if dayname (concat dayname ", ")) day " " monthname " " year)
|
|
@end smallexample
|
|
|
|
@noindent
|
|
The ISO standard date representation is this:
|
|
|
|
@smallexample
|
|
(year "-" month "-" day)
|
|
@end smallexample
|
|
|
|
@noindent
|
|
This specifies a typical American format:
|
|
|
|
@smallexample
|
|
(month "/" day "/" (substring year -2))
|
|
@end smallexample
|
|
|
|
@node Time Display Format
|
|
@section Time Display Format
|
|
@vindex calendar-time-display-form
|
|
|
|
The calendar and diary by default display times of day in the
|
|
conventional American style with the hours from 1 through 12, minutes,
|
|
and either @samp{am} or @samp{pm}. If you prefer the European style,
|
|
also known in the US as military, in which the hours go from 00 to 23,
|
|
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:
|
|
|
|
@smallexample
|
|
(12-hours ":" minutes am-pm
|
|
(if time-zone " (") time-zone (if time-zone ")"))
|
|
@end smallexample
|
|
|
|
@noindent
|
|
Here is a value that provides European style times:
|
|
|
|
@smallexample
|
|
(24-hours ":" minutes
|
|
(if time-zone " (") time-zone (if time-zone ")"))
|
|
@end smallexample
|
|
|
|
@node Daylight Savings
|
|
@section Daylight Savings Time
|
|
@cindex daylight savings time
|
|
|
|
Emacs understands the difference between standard time and daylight
|
|
savings time---the times given for sunrise, sunset, solstices,
|
|
equinoxes, and the phases of the moon take that into account. The rules
|
|
for daylight savings time vary from place to place and have also varied
|
|
historically from year to year. To do the job properly, Emacs needs to
|
|
know which rules to use.
|
|
|
|
Some operating systems keep track of the rules that apply to the place
|
|
where you are; on these systems, Emacs gets the information it needs
|
|
from the system automatically. If some or all of this information is
|
|
missing, Emacs fills in the gaps with the rules currently used in
|
|
Cambridge, Massachusetts, which is the center of GNU's world.
|
|
|
|
|
|
@vindex calendar-daylight-savings-starts
|
|
@vindex calendar-daylight-savings-ends
|
|
If the default choice of rules is not appropriate for your location,
|
|
you can tell Emacs the rules to use by setting the variables
|
|
@code{calendar-daylight-savings-starts} and
|
|
@code{calendar-daylight-savings-ends}. Their values should be Lisp
|
|
expressions that refer to the variable @code{year}, and evaluate to the
|
|
Gregorian date on which daylight savings time starts or (respectively)
|
|
ends, in the form of a list @code{(@var{month} @var{day} @var{year})}.
|
|
The values should be @code{nil} if your area does not use daylight
|
|
savings time.
|
|
|
|
Emacs uses these expressions to determine the start and end dates of
|
|
daylight savings time as holidays and for correcting times of day in the
|
|
solar and lunar calculations.
|
|
|
|
The values for Cambridge, Massachusetts are as follows:
|
|
|
|
@example
|
|
@group
|
|
(calendar-nth-named-day 1 0 4 year)
|
|
(calendar-nth-named-day -1 0 10 year)
|
|
@end group
|
|
@end example
|
|
|
|
@noindent
|
|
i.e., the first 0th day (Sunday) of the fourth month (April) in
|
|
the year specified by @code{year}, and the last Sunday of the tenth month
|
|
(October) of that year. If daylight savings time were
|
|
changed to start on October 1, you would set
|
|
@code{calendar-daylight-savings-starts} to this:
|
|
|
|
@example
|
|
(list 10 1 year)
|
|
@end example
|
|
|
|
For a more complex example, suppose daylight savings time begins on
|
|
the first of Nisan on the Hebrew calendar. You should set
|
|
@code{calendar-daylight-savings-starts} to this value:
|
|
|
|
@example
|
|
(calendar-gregorian-from-absolute
|
|
(calendar-absolute-from-hebrew
|
|
(list 1 1 (+ year 3760))))
|
|
@end example
|
|
|
|
@noindent
|
|
because Nisan is the first month in the Hebrew calendar and the Hebrew
|
|
year differs from the Gregorian year by 3760 at Nisan.
|
|
|
|
If there is no daylight savings time at your location, or if you want
|
|
all times in standard time, set @code{calendar-daylight-savings-starts}
|
|
and @code{calendar-daylight-savings-ends} to @code{nil}.
|
|
|
|
@vindex calendar-daylight-time-offset
|
|
The variable @code{calendar-daylight-time-offset} specifies the
|
|
difference between daylight savings time and standard time, measured in
|
|
minutes. The value for Cambridge is 60.
|
|
|
|
@vindex calendar-daylight-savings-starts-time
|
|
@vindex calendar-daylight-savings-ends-time
|
|
The variable @code{calendar-daylight-savings-starts-time} and the
|
|
variable @code{calendar-daylight-savings-ends-time} specify the number
|
|
of minutes after midnight local time when the transition to and from
|
|
daylight savings time should occur. For Cambridge, both variables'
|
|
values are 120.
|
|
|
|
@node Diary Customizing
|
|
@section Customizing the Diary
|
|
|
|
@vindex holidays-in-diary-buffer
|
|
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{holidays-in-diary-buffer} to
|
|
@code{nil}.@refill
|
|
|
|
@vindex number-of-diary-entries
|
|
The variable @code{number-of-diary-entries} controls the number of
|
|
days of diary entries to be displayed at one time. It affects the
|
|
initial display when @code{view-diary-entries-initially} 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 print-diary-entries-hook
|
|
@findex print-diary-entries
|
|
The variable @code{print-diary-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.
|
|
|
|
@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
|
|
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
|
|
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
|
|
must match consecutively.
|
|
|
|
A regular expression in a date pattern matches in its usual fashion,
|
|
using the standard syntax table altered so that @samp{*} is a word
|
|
constituent.
|
|
|
|
The symbols @code{month}, @code{day}, @code{year}, @code{monthname},
|
|
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.
|
|
|
|
The default value of @code{diary-date-forms} in the American style is
|
|
this:
|
|
|
|
@example
|
|
((month "/" day "[^/0-9]")
|
|
(month "/" day "/" year "[^0-9]")
|
|
(monthname " *" day "[^,0-9]")
|
|
(monthname " *" day ", *" year "[^0-9]")
|
|
(dayname "\\W"))
|
|
@end example
|
|
|
|
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
|
|
must match a portion of the diary entry text---beyond the whitespace
|
|
that ends the date---then the first element of the date pattern
|
|
@emph{must} be @code{backup}. This causes the date recognizer to back
|
|
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:
|
|
|
|
@example
|
|
((day "/" month "[^/0-9]")
|
|
(day "/" month "/" year "[^0-9]")
|
|
(backup day " *" monthname "\\W+\\<[^*0-9]")
|
|
(day " *" monthname " *" year "[^0-9]")
|
|
(dayname "\\W"))
|
|
@end example
|
|
|
|
@noindent
|
|
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.
|
|
|
|
@node Hebrew/Islamic Entries
|
|
@section Hebrew- and Islamic-Date Diary Entries
|
|
|
|
Your diary file can have entries based on 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:
|
|
|
|
@vindex nongregorian-diary-listing-hook
|
|
@vindex nongregorian-diary-marking-hook
|
|
@findex list-hebrew-diary-entries
|
|
@findex mark-hebrew-diary-entries
|
|
@smallexample
|
|
(add-hook 'nongregorian-diary-listing-hook 'list-hebrew-diary-entries)
|
|
(add-hook 'nongregorian-diary-marking-hook 'mark-hebrew-diary-entries)
|
|
@end smallexample
|
|
|
|
@noindent
|
|
If you want Islamic-date entries, do this:
|
|
|
|
@findex list-islamic-diary-entries
|
|
@findex mark-islamic-diary-entries
|
|
@smallexample
|
|
(add-hook 'nongregorian-diary-listing-hook 'list-islamic-diary-entries)
|
|
(add-hook 'nongregorian-diary-marking-hook 'mark-islamic-diary-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:
|
|
|
|
@smallexample
|
|
HHeshvan 25 Happy Hebrew birthday!
|
|
@end smallexample
|
|
|
|
@noindent
|
|
and would appear in the diary for any date that corresponds to Heshvan 25
|
|
on the Hebrew calendar. And here is an Islamic-date diary entry that matches
|
|
Dhu al-Qada 25:
|
|
|
|
@smallexample
|
|
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{&}).
|
|
|
|
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:
|
|
|
|
@table @kbd
|
|
@item i h d
|
|
Add a diary entry for the Hebrew date corresponding to the selected date
|
|
(@code{insert-hebrew-diary-entry}).
|
|
@item i h m
|
|
Add a diary entry for the day of the Hebrew month corresponding to the
|
|
selected date (@code{insert-monthly-hebrew-diary-entry}). This diary
|
|
entry matches any date that has the same Hebrew day-within-month as the
|
|
selected date.
|
|
@item i h y
|
|
Add a diary entry for the day of the Hebrew year corresponding to the
|
|
selected date (@code{insert-yearly-hebrew-diary-entry}). This diary
|
|
entry matches any date which has the same Hebrew month and day-within-month
|
|
as the selected date.
|
|
@item i i d
|
|
Add a diary entry for the Islamic date corresponding to the selected date
|
|
(@code{insert-islamic-diary-entry}).
|
|
@item i i m
|
|
Add a diary entry for the day of the Islamic month corresponding to the
|
|
selected date (@code{insert-monthly-islamic-diary-entry}).
|
|
@item i i y
|
|
Add a diary entry for the day of the Islamic year corresponding to the
|
|
selected date (@code{insert-yearly-islamic-diary-entry}).
|
|
@end table
|
|
|
|
@findex insert-hebrew-diary-entry
|
|
@findex insert-monthly-hebrew-diary-entry
|
|
@findex insert-yearly-hebrew-diary-entry
|
|
@findex insert-islamic-diary-entry
|
|
@findex insert-monthly-islamic-diary-entry
|
|
@findex insert-yearly-islamic-diary-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
|
|
@section Fancy Diary Display
|
|
@vindex diary-display-hook
|
|
@findex simple-diary-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{simple-diary-display}) hides the irrelevant diary entries and
|
|
then displays the buffer. However, if you specify the hook as follows,
|
|
|
|
@cindex diary buffer
|
|
@findex fancy-diary-display
|
|
@example
|
|
(add-hook 'diary-display-hook 'fancy-diary-display)
|
|
@end example
|
|
|
|
@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{print-diary-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 print-diary-entries}. As usual, the
|
|
inclusion of the holidays slows down the display slightly; you can speed
|
|
things up by setting the variable @code{holidays-in-diary-buffer} to
|
|
@code{nil}.
|
|
|
|
@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
|
|
@code{diary-list-include-blanks} to @code{t}.@refill
|
|
|
|
@cindex sorting diary entries
|
|
If you use the fancy diary display, you can use the normal hook
|
|
@code{list-diary-entries-hook} to sort each day's diary entries by their
|
|
time of day. Here's how:
|
|
|
|
@findex sort-diary-entries
|
|
@example
|
|
(add-hook 'list-diary-entries-hook 'sort-diary-entries t)
|
|
@end example
|
|
|
|
@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:
|
|
|
|
@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:
|
|
|
|
@vindex list-diary-entries-hook
|
|
@vindex mark-diary-entries-hook
|
|
@findex include-other-diary-files
|
|
@findex mark-included-diary-files
|
|
@smallexample
|
|
(add-hook 'list-diary-entries-hook 'include-other-diary-files)
|
|
(add-hook 'mark-diary-entries-hook 'mark-included-diary-files)
|
|
@end smallexample
|
|
|
|
The include mechanism works only with the fancy diary display, because
|
|
ordinary diary display shows the entries directly from your diary file.
|
|
|
|
@node Sexp Diary Entries
|
|
@section Sexp Entries and the Fancy Diary Display
|
|
@cindex sexp diary entries
|
|
|
|
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
|
|
the number of years since the anniversary date into the text of the
|
|
diary entry. Thus the @samp{%d} in this dairy entry:
|
|
|
|
@findex diary-anniversary
|
|
@smallexample
|
|
%%(diary-anniversary 10 31 1948) Arthur's birthday (%d years old)
|
|
@end smallexample
|
|
|
|
@noindent
|
|
gets replaced by the age, so on October 31, 1990 the entry appears in
|
|
the fancy diary buffer like this:
|
|
|
|
@smallexample
|
|
Arthur's birthday (42 years old)
|
|
@end smallexample
|
|
|
|
@noindent
|
|
If the diary file instead contains this entry:
|
|
|
|
@smallexample
|
|
%%(diary-anniversary 10 31 1948) Arthur's %d%s birthday
|
|
@end smallexample
|
|
|
|
@noindent
|
|
the entry in the fancy diary buffer for October 31, 1990 appears like this:
|
|
|
|
@smallexample
|
|
Arthur's 42nd birthday
|
|
@end smallexample
|
|
|
|
Similarly, cyclic diary entries can interpolate the number of repetitions
|
|
that have occurred:
|
|
|
|
@findex diary-cyclic
|
|
@smallexample
|
|
%%(diary-cyclic 50 1 1 1990) Renew medication (%d%s time)
|
|
@end smallexample
|
|
|
|
@noindent
|
|
looks like this:
|
|
|
|
@smallexample
|
|
Renew medication (5th time)
|
|
@end smallexample
|
|
|
|
@noindent
|
|
in the fancy diary display on September 8, 1990.
|
|
|
|
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
|
|
|
|
@findex diary-remind
|
|
@smallexample
|
|
%%(diary-remind '(diary-anniversary 12 22 1968) 7) Ed's anniversary
|
|
@end smallexample
|
|
|
|
@noindent
|
|
and the fancy diary will show
|
|
@smallexample
|
|
Ed's anniversary
|
|
@end smallexample
|
|
@noindent
|
|
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,
|
|
|
|
@smallexample
|
|
%%(diary-date '(10 11 12) 22 t) Rake leaves
|
|
@end smallexample
|
|
|
|
@noindent
|
|
causes the fancy diary to show
|
|
|
|
@smallexample
|
|
Rake leaves
|
|
@end smallexample
|
|
|
|
@noindent
|
|
on October 22, November 22, and December 22 of every year.
|
|
|
|
@findex diary-float
|
|
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}
|
|
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 months, a single
|
|
month, or @code{t} to specify all months. You can also use an optional
|
|
parameter @var{day} to specify the @var{n}th @var{dayname} of
|
|
@var{month} on or after/before @var{day}; the value of @var{day} defaults
|
|
to 1 if @var{n} is positive and to the last day of @var{month} if
|
|
@var{n} is negative. For example,
|
|
|
|
@smallexample
|
|
%%(diary-float t 1 -1) Pay rent
|
|
@end smallexample
|
|
|
|
@noindent
|
|
causes the fancy diary to show
|
|
|
|
@smallexample
|
|
Pay rent
|
|
@end smallexample
|
|
|
|
@noindent
|
|
on the last Monday of every month.
|
|
|
|
The generality of sexp diary entries lets you specify any diary
|
|
entry that you can describe algorithmically. A sexp diary entry
|
|
contains an expression that computes whether the entry applies to any
|
|
given date. If its value is non-@code{nil}, the entry applies to that
|
|
date; otherwise, it does not. The expression can use the variable
|
|
@code{date} to find the date being considered; its value is a list
|
|
(@var{month} @var{day} @var{year}) that refers to the Gregorian
|
|
calendar.
|
|
|
|
The sexp diary entry applies to a date when the expression's value
|
|
is non-@code{nil}, but some values have more specific meanings. If
|
|
the value is a string, that string is a description of the event which
|
|
occurs on that date. The value can also have the form
|
|
@code{(@var{mark} . @var{string})}; then @var{mark} specifies how to
|
|
mark the date in the calendar, and @var{string} is the description of
|
|
the event. If @var{mark} is a single-character string, that character
|
|
appears next to the date in the calendar. If @var{mark} is a face
|
|
name, the date is displayed in that face. If @var{mark} is
|
|
@code{nil}, that specifies no particular highlighting for the date.
|
|
|
|
Suppose you get paid on the 21st of the month if it is a weekday, and
|
|
on the Friday before if the 21st is on a weekend. Here is how to write
|
|
a sexp diary entry that matches those dates:
|
|
|
|
@smallexample
|
|
&%%(let ((dayname (calendar-day-of-week date))
|
|
(day (car (cdr date))))
|
|
(or (and (= day 21) (memq dayname '(1 2 3 4 5)))
|
|
(and (memq day '(19 20)) (= dayname 5)))
|
|
) Pay check deposited
|
|
@end smallexample
|
|
|
|
The following sexp diary entries take advantage of the ability (in the fancy
|
|
diary display) to concoct diary entries whose text varies based on the date:
|
|
|
|
@findex diary-sunrise-sunset
|
|
@findex diary-phases-of-moon
|
|
@findex diary-day-of-year
|
|
@findex diary-iso-date
|
|
@findex diary-julian-date
|
|
@findex diary-astro-day-number
|
|
@findex diary-hebrew-date
|
|
@findex diary-islamic-date
|
|
@findex diary-french-date
|
|
@findex diary-mayan-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 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
|
|
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.
|
|
@item %%(diary-astro-day-number)
|
|
Make a diary entry with today's equivalent astronomical (Julian) day number.
|
|
@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.
|
|
@item %%(diary-french-date)
|
|
Make a diary entry with today's equivalent date on the French Revolutionary
|
|
calendar.
|
|
@item %%(diary-mayan-date)
|
|
Make a diary entry with today's equivalent date on the Mayan calendar.
|
|
@end table
|
|
|
|
@noindent
|
|
Thus including the diary entry
|
|
|
|
@example
|
|
&%%(diary-hebrew-date)
|
|
@end example
|
|
|
|
@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.)
|
|
|
|
These functions can be used to construct sexp diary entries based on
|
|
the Hebrew calendar in certain standard ways:
|
|
|
|
@cindex rosh hodesh
|
|
@findex diary-rosh-hodesh
|
|
@cindex parasha, weekly
|
|
@findex diary-parasha
|
|
@cindex candle lighting times
|
|
@findex diary-sabbath-candles
|
|
@cindex omer count
|
|
@findex diary-omer
|
|
@cindex yahrzeits
|
|
@findex diary-yahrzeit
|
|
@table @code
|
|
@item %%(diary-rosh-hodesh)
|
|
Make a diary entry that tells the occurrence and ritual announcement of each
|
|
new Hebrew month.
|
|
@item %%(diary-parasha)
|
|
Make a Saturday diary entry that tells the weekly synagogue scripture reading.
|
|
@item %%(diary-sabbath-candles)
|
|
Make a Friday diary entry that tells the @emph{local time} of Sabbath
|
|
candle lighting.
|
|
@item %%(diary-omer)
|
|
Make a diary entry that gives the omer count, when appropriate.
|
|
@item %%(diary-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}.)
|
|
@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}.
|
|
|
|
|
|
@node Index
|
|
@unnumbered Index
|
|
|
|
@printindex cp
|
|
|
|
@bye
|
|
|
|
@ignore
|
|
arch-tag: 75c33f13-32c6-41b6-9537-847a312e2e49
|
|
@end ignore
|