NAME

reminder - remind user of events

SYNOPSIS

reminder [-f, --force] [--home DIR] [-m, --mail ADDR]

reminder -?, -h, --help | --man

reminder -V, --version

DESCRIPTION

This program issues notifications about user-defined events. The events have to be specified in the event file (see EVENT FILE) and consist of a date, a list of triggers and an arbitrary text. The text contains the message describing the event. The triggers define on which days a reminder notification is to be issued.

reminder is meant to be run automatically on a regular basis, e.g. every hour as a cron job. It is also possible to execute it manually, but this is not a typical use case for a program like this.

reminder processes the events once a day, as early as possible. If called more than once on the same day it will simply do nothing and exit silently. The above mentioned cron job interval of about one hour is recommended for desktop systems that are switched off from time to time because this way you can be sure to receive pending notifications quite soon after start-up. For systems that are running 24/7 a daily execution will suffice, of course.

On the other hand, if the program is not executed for one or even more days it will nevertheless send notifications that were due to be issued on one of these skipped days. Thus, no reminder will be lost, but it could be too late then, depending on the triggers chosen.

There are two types of notification delivery: via email or simply on standard output.

When running reminder as a cron job it is recommended to specify the --mail parameter instead of printing to standard output. In this mode notifications are sent by mail. There are two good reasons for preferring this way of transport: (1) by convention, cron jobs should be `silent' and only print output when there are errors. This output is then sent to the user via email. (2) Each reminder message will be sent in a seperate email so that the user can delete those reminders that are not needed anymore while keeping others in his mailbox. Moreover, the mail subject contains all the necessary information about the event. In that way the reminders are visible merely by looking at the inbox and without the need to read the mail body.

EVENT FILE

When running reminder for the first time it will not find an event file and therefore create a template that contains some examples and can be customized (see FILES). The format of a valid line in the event file is as follows:

  <year> <month> <day> <triggering_days> <arbitrary_text>

The fields are seperated by spaces with the exception that arbitrary_text is allowed to contain spaces. year must be a 4-digit number. month and day are allowed but not required to have a leading zero. Each of the first three fields can be an asterisk (*) which means that the event takes place every year, month, or day.

triggering_days consists of triggers seperated by commas (no spaces!). Each trigger consists either of a plain number or a span of numbers (1-4 is equivalent to 1,2,3,4). A trigger represents the number of days before the event's date when a reminder notification is to be issued. These numbers need not to be ordered in any way.

The following example creates a notification for the event every year on May 15 as well as on May 21 and 22:

  * 05 23 8,1-2 some text message

OPTIONS

-?, -h, --help

Prints the possible options and exits.

--man

Prints the whole manual and exits.

-f, --force

Forces another evaluation of the event file. The normal behaviour is to run only once a day. Forcing a run may result in reminding of events that were already reported during the last (unforced) run.

This switch should only be used when calling the program interactively from the command line. Using it for a cron job is quite useless.

--home DIR

Usually, the files mentioned in section FILES are assumed to be in the directory specified by the environment variable $HOME. For the unlikely case that $HOME is not defined it falls back to the current working directory. With the --home parameter you can override all this and set the directory where reminder looks for or creates the configuration files.

-m, --mail ADDR

Instead of printing reminder messages line by line, for each message a mail is sent to ADDR. This assumes that your system has the unix `mail' command. ADDR can be a comma-seperated list of addresses without blanks between them. The mail subject and body both contain the reminder message.

-V, --version

Prints the program version and exits.

FILES

$HOME/.reminder_events, $HOME/.reminder_lastrun

COPYRIGHT AND LICENCE

This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA