Document calendar-month-header

[bpt/emacs.git] / doc / emacs / cal-xtra.texi

@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 printed version) or in the main Emacs manual (for the on-line version).

@c Moved here from the Emacs Lisp Reference Manual, 2005-03-26.
@node Advanced Calendar/Diary Usage
@section More advanced features of the Calendar and Diary

  This section describes some of the more advanced/specialized
features of the calendar and diary.  It starts with some of the
many ways in which you can customize the calendar and diary to suit
your personal tastes.

@menu
* Calendar Customizing::   Calendar layout and hooks.
* Holiday Customizing::    Defining your own holidays.
* Date Display Format::    Changing the format.
* Time Display Format::    Changing the format.
* Diary Customizing::      Defaults you can set.
* 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-month-header
  The variable @code{calendar-month-header} controls the text that
appears above each month in the calendar.  By default, it shows the
month and year.

@vindex calendar-holiday-marker
@vindex diary-entry-marker
@vindex calendar-today-marker
  The variable @code{calendar-holiday-marker} specifies how to mark a
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.  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
  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 calendar-initial-window-hook
  Starting the calendar runs the normal hook
@code{calendar-initial-window-hook}.  Recomputation of the calendar
display does not run this hook.  But if you leave the calendar with the
@kbd{q} command and reenter it, the hook runs again.@refill

@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
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
@smallexample
(add-hook 'calendar-today-visible-hook 'calendar-mark-today)
@end smallexample

@vindex calendar-today-invisible-hook
@noindent
  A similar normal hook, @code{calendar-today-invisible-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
@subsection Customizing the Holidays

@vindex calendar-holidays
@vindex holiday-oriental-holidays
@vindex holiday-solar-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
not show the associated holidays.

@vindex holiday-general-holidays
@vindex holiday-local-holidays
@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
@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
@vindex calendar-islamic-all-holidays-flag
  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{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}.

@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 argument @var{string} is always the 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}
      &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.

@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 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.

@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 (i.e., the fourteenth day of the seventh month).  You
can do this as follows:

@smallexample
(setq holiday-other-holidays '((holiday-fixed 7 14 "Bastille Day")))
@end smallexample

  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).