Re: hbday

[http://www.trudge.engr.sgi.com/~mja (Mike Abbott)]

> Hi!  How are you?

Great.  Have you adjusted to being back on the east coast?

> I lost the man page to hbday

Enclosed below.

> there's no facility to have "floating" holidays skip back over "fixed"
> holidays.  You haven't added anything like this to hbday, have you?

Nope.  Please feel free to add it and send me the patches.  I last
touched hbday in April 1997.  I guess the "revised" date in the code is
wrong.

---- hbday.1 ----
.TH HBDAY 1 "23 Feb 1989"
.SH NAME
hbday \- holiday and birthday reminder service
.SH SYNOPSIS
.B hbday
[ \-behln ] [ \-f
.B database
] [
.B daysahead
]
.SH DESCRIPTION
.I Hbday
examines some number of databases and displays current and upcoming holidays,
birthdays, and anniversaries.  Its invocation is usually included in users'
.I \&.login
files (see
.IR csh(1))
to remind them of important dates when they log in.
.PP
In its normal mode of operation,
.I hbday
examines the files /usr/lib/hbdays and $HOME/.hbdays and lists only the
holidays, birthdays, and anniversaries for the current date, or prints
nothing if there are none.  Holiday names are printed exactly as they appear
in the database; birthday boys and girls are wished a "Happy Birthday" and,
if the person's year of birth is given, his or her age is also displayed.
Anniversaries are treated similarly to birthdays.  When a numeric
.I daysahead
argument is given, advance notice will be given under the heading "Coming
up" for up to
.I daysahead
days prior to the date of the event.  (It is not possible to list events in
the past.)  Advance notice is given only of upcoming birthdays and
anniversaries unless the
.I \-h
argument is also specified, enabling advance notice of upcoming holidays as
well.  The
.I \-e
option restricts
.I hbday
to list only today's events and those events occurring exactly
.I daysahead
days in the future;
.I \-b
inhibits ringing the bell for today's birthdays; these options are good for
mailed notices.  Use of
.I \-l
prevents examination of /usr/lib/hbdays; similarly
.I \-n
for the .hbdays file in the user's home directory.  Other databases may be
specified using the
.I \-f
.I database
feature.  Up to sixteen total databases may be read at once, including the
default ones unless -l and/or -n are specified.
.PP
The database files contain all the information on events.  Each non-blank
line of the file is either a comment or a holiday, birthday, or anniversary
entry.  Blank lines are ignored.  The first non-separator character of a
line (where the separators throughout the entries are space, tab, comma,
slash, and hyphen) specifies the type of entry:  b (or B) for birthday, h
(or H) for holiday, a (or A) for anniversary.  All other lines are treated
as comments, except that holiday entries having a c (or C) before the h
specifier are treated as countdowns (their entries are always listed,
regardless of command line options and days ahead; this is useful when, for
example, you will graduate in a few months and are counting the days to
commencement) and that holiday entries having an n (or N) before the h
specifier are not printed in the coming-up section, only on the day of the
event (useful for reminders).
.br
Next on the line must be the date of the event, month first, then day, then
optionally the year.  The month may be a number (1 for January), a (possibly
abbreviated) name (like jan), or either of the words `all' or `every.'  The
day may be a number, or of the form "#ND", "~ND", "@N", "<N" and ">N" for
`floating' holidays.  When a year is given in a holiday entry, it is the
year on which the holiday occurs; that holiday will not be listed once it
has passed.  A year in a birthday or anniversary entry is the year of the
person's birth or marriage.  After the date comes the name of the birthday
person / anniversary people, or the name of the holiday.
.PP
.I Hbday
supports several kinds of `floating' holidays, that is, holidays that change
date from year to year.  (Note that birthdays and anniversaries don't
`float.')  The first kind is defined as, say, "the first Monday of September
is Labor Day."  This type of floating holiday is specified in the database
using the "#ND" form mentioned above.  The # is mandatory and literal; N is
either a digit from 1 to 5 or the symbol $ (for "the last"), and D is a day
of the week (one of u, m, t, w, h, f, s or UMTWHFS).  So, for example, "#3m"
defines an event on the third Monday of the month, and "#$u" specifies the
last Sunday.
.PP
The second kind of floating holiday supports events such as, "Washington's
birthday is observed on the Monday of the week in which it lies."  For this
type, use the "~ND" form, where the ~ is mandatory and literal, N is the day
of the month on which the event "really" occurs, and D is the day of the
week on which the holiday is observed.  So, for example, "~22m" defines an
event on the Monday of the week of the 22nd.
.PP
A third kind of floating holiday covers events restricted to weekdays.  This
is useful for reminder-type holidays, such as "we get paid on the weekday
closest to the 15th and last day of each month."  This would be entered as
two holidays, "NH every @15 Payday" and "NH every @$ Payday".  When either
of these days (the 15th or the last) fall on a weekday, that is the day
used.  But if either falls on a weekend, the nearest weekday within the
month (Friday for Saturday and Monday for Sunday) is used instead.
.PP
The fourth and fifth kinds of floating holidays are related to the third;
these restrict events to previous or successive weekdays.  To follow on the
last example, pretend instead that payday is always the Friday before the
15th and the last day.  Then instead of using @, use <.  If instead it's on
the Monday following, use >.  As before, when the event falls on a real
weekday, that day is used.  But if the event falls on a weekend, these will
force either a Friday (<) or Monday (>) event.
.SH EXAMPLES
Consider the following database called ".hbdays" in the user's home
directory.  (Assume /usr/lib/hbdays is empty.)
.PP
.nf
* Holidays
H Jan 1		New Year's Day
H Jan #3m		Martin Luther King's birthday
H Feb 2		Groundhog Day
H Feb 12		Lincoln's birthday
H Feb ~22m		Washington's birthday observed
H May #$m		Memorial Day
H Sep #1m		Labor Day
C H May 28, 1989	Commencement

* Birthdays
B Feb 7, 1917	Grandpa
B Mar 29		Dad

* Anniversaries
A Jun 21, 1989	Biffy and Buffy
.fi
.PP
Say today is February 2nd, 1989.
.PP
.nf
% hbday 7
Groundhog Day
Coming up:
Feb  7:  Grandpa's 72nd birthday.  (in 5 days)
May 28:  Commencement.  (in 115 days)
.PP
Say today is December 30th, 1989.
.PP
% hbday -h 7
Coming up:
Jan  1:  New Year's Day.  (in 2 days)
.PP
.fi
The following self-perpetuating script for
.I at(1)
mails notices of birthdays to you five days in advance.
.br
.nf
hbday -eb 5 > hb.temp
if (! -z hb.temp) mail -s 'birthdays' $user < hb.temp
rm hb.temp
sleep 600
at -c 0320 $0
.SH AUTHOR
Michael J. Abbott '89 (LSRHS '85) at Cornell University.
.SH FILES
.nf
/usr/lib/hbdays		System-wide database
$HOME/.hbdays			Personal database per user
.SH "SEE ALSO"
at(1), calendar(1), csh(1)
-----------------

--
Michael J. Abbott        http://www.sgi.com/~mja        http://reality.sgi.com/mja