kal - displays various calendar data
SYNOPSIS
kal [month/[day/]]year
kal [[num]:][year]
kal [[week].][year]
kal -y[year]
kal -j[[month/[day/]]year]
kal -i[[month/[day/]]year]
kal [-j]month/day/year+|-num
kal [-j][%]month1/day1/year1,[month2/day2/year2]
kal -m[month/day/year | juliandate]
kal [-E year] [-G year] [-J year]
kal [-o [month/]year] [-p [month/]year] [-t [month/]year]
kal [-s=sitename] [-l=style] [-g=year] [-f=n]
kal [-c] [-v] [-h]
DESCRIPTION
The default calendar of kal is a commonly used combined
Julian-Gregorian calendar. The admissible dates for that
calendar range from January 1 1 to December 31 9999. The
Gregorian Reformation is assumed to have occurred on
either October 5 1582 or September 3 1752, depending on
the flags that were set at compilation of the kal binary.
(The active settings are shown by the option `-v', see
below.) The Julian calendar is actually assumed to have
been introduced on March 1 4, which seems to be histori-
cally correct. As a consequence, kal considers the year 4
not as a leap year. For more details concerning the his-
tory of calendars see the references given below.
kal also fully supports the Hebrew calendar. The admissi-
ble Hebrew dates range from Tishri 1 1 to Elul 29 13760.
This covers the supported range of the default calendar
whose beginning and end correspond to the Hebrew dates
Tevet 17 3761 and Heshvan 28 13760, respectively. The
option `-j' causes kal to switch to the Hebrew calendar.
kal's Islamic calendar is a tabular calendar as described
calendars of this type are not generally accepted in the
Islamic world and the actual Islamic date may therefore
differ from the prediction derived from this model.
The admissible Islamic dates range from Muharram 1 1 to
Dhu al-Hijjah 30 9665, corresponding to the dates July 16
622 and October 1 9999, respectively. The option `-i'
causes kal to switch to the Islamic calendar.
If invoked without arguments, kal displays a calendar of
the current month. If the use of colors is enabled, the
current day appears highlighted in red. The date changes
at 0:00:00 (12 p.m.) local time.
kal accepts non-option arguments of the following form:
year Displays a calendar of that year.
(year = 1,...,9999).
month/year
Displays a calendar of the specified month.
(month/year = 1/1,...,12/9999).
month/day/year
Displays some data for the specified day:
The first line shows the day of the week, the
numerical format, and the week number for the
default calendar. (The numerical format of a date
is represented as a pair num:year which means day
#num of year.)
The second and the third line render the corre-
sponding Hebrew and Islamic date. If the date does
not correspond to an admissible Islamic date, the
line referring to the Islamic calendar is omitted.
The fourth line displays the associated Julian day
number, commonly referred to as the Julian date.
The Julian date is mainly used in connection with
astronomical time scales. Here it can be seen as a
time reference for the calendar conversion, which
is required to relate Gregorian days uniquely to
Hebrew days and vice versa. By definition, the
Julian date of a certain point of time is the time
elapsed since ``12:00:00 GMT January 1 -4712''
(i.e., 4713 B.C.), expressed in decimal days. Note
that the reference time is set to midnight, i.e.,
at the beginning of the Gregorian day and 6 hours
after the beginning of the Hebrew day.
Finally, the sun's and the moon's rise and set
times for the assigned site are displayed. Unless
information the Julian date of local noon and the
RFC-822 style numeric time zone are shown at the
bottom.
[[num]:][year]]
Returns the standard format of a date whose numeri-
cal format is num:year. The default for year is the
current year and the default for num is the current
numerical date. (Note that if a colon is entered
together with exactly one number then kal takes
that number for num, no matter whether the number
precedes or follows the colon.)
[[week].][year]]
Displays a week according to the ISO 8601 standard.
If colors are enabled, the days of the specified
week are shown highlighted in red. kal also states
the beginning of that week in an additional line.
The default for year is the current year and the
default for week is the current ISO week. (If a
period is entered together with exactly one number
then kal takes that number for week, no matter
whether the number precedes or follows the period.)
month/day/year+|-num
Displays the date ``month day year plus or minus
num days'', provided the result is an admissible
date. This type of argument is available for the
Hebrew calendar as an option parameter for `-j',
see below.
[%]month1/day1/year1,[month2/day2/year2]
Returns the difference of two admissible dates. If
only one date (preceded or followed by a comma) is
given, the current date is assumed as the second
date. Unless the argument is preceded or followed
by a `%' the result is returned in days, otherwise
it is expressed in years, months, and days. This
type of argument is available for the Hebrew calen-
dar as an option parameter for `-j', see below.
Moreover, kal recognizes the following option arguments:
-y[year]
Displays a calendar of the current year or the
specified year. (year = 1,...,9999).
-j[[month/[day]]/year]
If no option parameter for `-j' is given, a calen-
dar of the current Hebrew month is displayed. If
colors are enabled, the current day appears high-
lighted in red. The date changes at 18:00:00 (6
specified Hebrew year is displayed.
(year = 1,...,13760).
If the option parameter is a pair month/year, a
calendar of that Hebrew month is displayed.
(month/year = 1/1,...,12/13760).
If the option parameter is a triple month/day/year,
and if the specified Hebrew date corresponds to an
admissible date for the default calendar, say
m/d/y, then the output will be exactly the same as
for `kal m/d/y' as described above. Otherwise, if
m/d/y lies not within the supported range, only the
line referring to the Hebrew calendar and the
Julian day number are displayed.
-jmonth/day/year+|-num
Displays the Hebrew date ``month day year plus or
minus num days'', provided the result is an admis-
sible Hebrew date.
-j[%]month1/day1/year1,[month2/day2/year2]
Returns the difference of two admissible Hebrew
dates. If only one Hebrew date with a preceding or
trailing comma is specified, the second date
defaults to the current Hebrew date. Unless the
option parameter is preceded or followed by a `%'
the result is returned in days, else it is
expressed in (Hebrew) years, months, and days.
-i[[month/[day]]/year]
If no option parameter for `-i' is given, a calen-
dar of the current Islamic month is displayed. If
colors are enabled, the current day appears high-
lighted in red. The date changes at 18:00:00 (6
p.m.) local time.
If the option parameter is year, a calendar of the
specified Islamic year is displayed.
(year = 1,...,9665).
If the option parameter is a pair month/year, a
calendar of that Islamic month is displayed.
(month/year = 1/1,...,12/9665).
If the option parameter is a triple month/day/year
and m/d/y is the corresponding date for the default
calendar, then the output will be the same as for
`kal m/d/y' as described above.
-m[month/day/year | juliandate]
If no option parameter for `-m' is specified, kal
month/day/year, the assumed Julian date corresponds
to ``0:00:00 GMT month day year''.
If the option parameter is a decimal number, then
this value will be taken for a Julian day number.
The supported range corresponds to that of the
default calendar. That is, the admissible values
are those in the interval [1721424.5,5373484.5].
-E year
Returns the date of Easter Sunday for the specified
year (1-9999).
-G year
Returns the date of Greek Orthodox Easter Sunday
for the specified year (1-9999).
-J year
Returns the date of Jewish New Year for the speci-
fied (Gregorian/Julian) year. (year = 1,...,9999).
-o [month/]year
Prints a HTML-formatted calendar of the specified
month or year to stdout.
-p [month/]year
Prints a HTML-formatted calendar of the specified
month or year to a file. The output is written to
`year.html' or `year-month.html', respectively.
-t [month/]year
Prints a LaTeX-formatted calendar of the specified
month or year to a file. The output is written to
`year.tex' or `year-month.tex', respectively.
-s=sitename
Select a site from a sites file. See section FILES
below for a description of the sites files. Note
that the program won't exit on errors arising from
missing sites files or unidentified sitename. Just
a brief error message will be printed to stderr in
such case.
NOTE: In certain cases the string sitename will
require white spaces. E. g., suppose that both
`Los Alamos' and `Los Angeles' are defined in the
sites file and that the entries are alphabetically
ordered. One may use `-s="Los Angeles"' on the
command line to access the entry `Los Angeles'
(since simply `-s=Los' matches `Los Alamos'). How-
ever, using quotes or double quotes may fail if kal
is invoked from CGI. For this reason kal accepts
`-s=Los_Angeles' indeed matches `Los Angeles'.
-l=style
Calendar layout style. Admissible values for style
are "us" for American style calendars (weeks begin
with Sunday) and "eu" for European style calendars
(weeks begin with Monday). The week numbers of the
American style calendar correspond to numbering
returned by `date +%U' (the week 1 begins on the
first Sunday of a year.) The European style calen-
dar uses a week numbering conforming to ISO 8601 as
given by `date +%V'. This option overrides the
active default which can be viewed with `kal -v'.
-g=year
Gregorian Reformation. Admissible values for year
are "1582" and "1752". The Gregorian Reformation is
assumed to have occurred in October 1582 in the
first case, and in September 1752 in the second
case. This option overrides the active default set-
ting which can be viewed with `kal -v'.
-f=n Filter option. kal's default output channel depends
on the flags that were set at compilation: if
`more', `less -r', or `most' has been defined as a
default filter (i.e., pager), then kal sends its
output to that filter whenever it detects that
printing calendars of a year or showing the help
screen is demanded on the command line. Otherwise
the output is written to stdout. The option `-f'
overrides the default by prescribing an output
channel. The admissible values for n are:
0 stdout
1 `more'
2 `less -r'
3 `most'
The active defaults are shown with `-v'. Note that
the output of `-o' is not affected by `-f', i.e.,
the HTML output is written to stdout, independent
of the choice of the filter.
-c Color toggle. Normally kal uses some ANSI colors in
its output. Then colors can be disabled with this
option. Conversely, if kal is compiled with the
color default disabled, one can use `-c' to get
colored output. The active default is shown by the
option `-v'.
Since the pager `most' cannot handle ANSI colors,
the `-c' switch is ignored if used together with
-h Prints a help message.
GNU LONG OPTIONS
Option arguments can also be specified as long options. In
particular, parameters can be passed to an option argument
with `='. For example, `-m2440000.125', `-m=2440000.125',
and `-moon=2440000.125' are equivalent. Note that long
options can be abbreviated. The long options and their
corresponding short options are as follows:
-y, --year
-m, --moon
-s, --site
-j, --jewish
-i, --islamic
-E, --EasterSunday
-G, --GreekOrthodoxEasterSunday
-J, --JewishNewYear
-o, --output
-p, --print
-t, --tex
-l, --layout
-g, --gregorian
-f, --filter
-c, --color-toggle
-v, --version
-h, --help
FILES
kal requires a sites file kal-sites for the site specific
data (latitude, longitude, and time zone). A typical
installation provides a system sites file whose pathname
is shown by `kal -v'. A user may also keep a private sites
file $HOME/.kal-sites in his or her home directory. If
both the system and the private sites file are present,
the private sites file is searched first. kal stops
searching if a matching entry for sitename has been found.
An entry in a sites file has the form
sitename; latitude longitude zonefile [offset]
Example: For Helsinki, Finland, we have
Helsinki, Finland; 60:10:00N 24:50:00E Europe/Helsinki +2
Latitude and longitude are in deg:min:sec. A trailing
character N or S indicates northern or southern latitude,
system's zoneinfo directory. The offset field is optional.
Here the site's standard GMT offset (integer hours) can be
set which is to be used in case that the offset cannot be
determined from zonefile. If offset is not given, GMT+0 is
assumed.
ENVIRONMENT
kal's internal default site is `Greenwich, England'. This
default can be altered by setting the value of the vari-
able KAL_SITE to any sitename defined in the sites file.
Several other variables can be used to control the HTML
output:
KAL_BODYBG background color for body
KAL_BODYFG text color
KAL_YEARBG background color for the year
KAL_MONTHBG background color for the month names
KAL_DAYBG background color for the days
KAL_SUNDAYFG text color for Sundays
KAL_LINKBG background color for links
KAL_LINKFG text color for links
KAL_VLINKFG text color for visited links
KAL_ALINKFG text color for active links
KAL_TBLBORDER border width of the table
A detailed description how kal can print HTML calendars
with links is documented separately. However, this
involves two more environment variables, KAL_LOCATION and
KAL_LINK. To sketch the role of these variables, suppose
we are given a HTML document `dates.html' which, in the
widest sense, is arranged as a list of dates with possibly
some information to be displayed for each date. The only
formal condition is that a date mm/dd/yyyy is labeled by
an anchor tag <a name="mmddyyyy">. Now let the value of
KAL_LOCATION be the URL of `dates.html' and let the value
of KAL_LINK be a list of the labels mmddyyyy. Then the
command `kal -o yyyy' would give a HTML calendar with a
link <a href="URL#mmddyyyy"> set for each labeled day from
`dates.html'.
REMARKS
Rise and set times for the sun and the moon are, of
course, approximate and may differ a few minutes from the
prediction obtained from other sources, e.g., xephem. We
have done some testing against Steve Moshier's ephemeris
program aa-5.4d and it appears that kal's results are suf-
ficiently accurate for civil purposes within a time inter-
val of, say, 2000 years centered at the Unix Epoch 1970.
See the REFERENCES below for more information on the model
been adopted from John Walker's xmoontool; the above
statement concerning the accuracy holds correspondingly.
Version 1.3 of kal hence uses two different models to
determine the sun's and the moon's positions. This problem
can hopefully be overcome by a unified approach in upcom-
ing releases.
REFERENCES
The Hebrew calendar certainly profited from some
JavaScript code by John Walker, see
http://www.fourmilab.ch/documents/calendar/.
The algorithms for the Hebrew and the Islamic calendar are
straightforward implementations of the rules described in
the "Explanatory Supplement to the Astronomical Almanac",
P. Kenneth Seidelmann, ed., University Science Books. For
a reprinted version on the WWW see
http://astro.nmsu.edu/~lhuber/leaphist.html
For some background concerning the computation of rise and
set times the interested user is referred to Paul
Schlyter's home page:
http://hotel04.ausys.se/pausch/
Indeed, orbital elements and other astronomical constants
used in kal's calculations have been taken from there.
SEE ALSO
cal(1), date(1), xmoontool(1), xephem(1x)
AUTHORS
Frank W. Josellis (frank@dynamical-systems.org). HTML/CGI
design by Oliver Knill (oliver@dynamical-systems.org).