Source Code 1992 March/Source_Code_CD-ROM_Walnut_Creek_March_1992.iso/usenet/altsrcs/2/2110

Internet Message Format | 1990-12-28 | 36KB

From: [e-mail] (David F. Skoll)
Newsgroups: alt.sources
Subject: REMIND 2.2 04/05
Message-ID: <dfs.658781298@yar>
Date: 16 Nov 90 18:48:18 GMT


#!/bin/sh
# This is part 04 of Remind-2.2
if touch 2>&1 | fgrep 'amc' > /dev/null
 then TOUCH=touch
 else TOUCH=true
fi
# ============= remind.1 ==============
if test X"$1" != X"-c" -a -f 'remind.1'; then
    echo "File already exists: skipping 'remind.1'"
else
echo "x - extracting remind.1 (Text)"
sed 's/^X//' << 'SHAR_EOF' > remind.1 &&
X.TH REMIND 1 "25 October 1990"
X.UC 4
X.SH NAME
Xremind \- a sophisticated reminder service
X.SH SYNOPSIS
X.B remind
X[\fB\-d\fR | \fB\-p\fR | \fB\-c\fR\fIn\fR [\fB\-w\fR\fIn\fR | \fB\-s\fR]]
X[\fB\-voraq\fR]
X.I filename
X[\fIdate\fR]
X.SH DESCRIPTION
X.B remind
Xreads the supplied
X.I filename
Xfor a list of reminders, and then issues reminders appropriate for
Xthe current date.
XEach reminder can consist of a message sent to standard output, or
Xa program to be executed.
X.SH OPTIONS
X.TP
X.B \-d
XThe
X.B \-d
Xflag causes
X.B remind
Xto enter a debugging mode.
XIn this mode, each reminder in the reminder file is examined and its
Xtrigger date is printed to standard output.  Also, some consistency
Xchecking is done, and warnings are issued about constructs which could
Xresult in slow execution times.
X.TP
X.B \-p
XThe
X.B \-p
Xflag causes
X.B remind
Xto go into
X.I purge
Xmode.  This mode is incompatible with the
X.B \-d
Xflag.  It causes
X.B remind
Xto scan the reminder file and echo all reminders which have not expired
Xto the standard output.  All expired reminders are echoed to the standard
Xerror stream.
X.TP
X.B \-c\fR\fIn\fR
XThe
X.B \-c
Xflag causes \fBremind\fR to generate a calendar with reminders indicated on
Xthe calendar.  The calendar printout is formatted and sent to standard output.
XIf you supply a number \fIn\fR from 1 to 12,
Xthen a calendar will be generated for
X\fIn\fR months, starting with the current month.  The default is to
Xproduce a calendar for one month only.  The
X.B \-c
Xoption is not compatible with the \fB\-p\fR or \fB\-d\fR options.
X.TP
X.B \-w\fR\fIn\fR
XThe \fB\-w\fR flag causes \fBremind\fR to format the calendar for a device
Xwhose output width is \fIn\fR columns.  The default is to produce a calendar
Xfor an 80-column device.
X.TP
X.B \-s
XThe \fB\-s\fB flag causes \fBremind\fR to send an unformatted "simple
Xcalendar" listing to standard output.  This can be used if you wish to
Xformat the calendar with another program rather than using \fBremind\fR's
Xbuilt-in calendar format.
X.TP
X.B \-v
XThe
X.B \-v
Xflag causes the debugging messages caused by
X.B \-d
Xto be printed in a verbose manner.  Also, any error messages issued by
X.B remind
Xare printed in verbose format.
X.TP
X.B \-o
XThe
X.B \-o
Xflag causes
X.B remind
Xto ignore any
X.B ONCE
Xdirectives in the reminder file.
X.TP
X.B \-r
XThe
X.B \-r
Xflag causes
X.B remind
Xto ignore any
X.B RUN
Xdirectives in the reminder file.
X.TP
X.B \-a
XThe
X.B \-a
Xoption causes
X.B remind
Xnot to issue
X.B AT
Xreminders when the reminder file is read and processed, providing the
X.B AT
Xreminders would normally be queued.  This allows you to have
X.B remind
Xqueue
X.B AT
Xreminders without triggering them when it reads the file.
X.TP
X.B \-q
XThe
X.B \-q
Xflag causes
X.B remind
Xnot to queue
X.B AT
Xreminders for triggering later in the day.  This prevents
X.B remind
Xfrom running as a daemon and popping up reminders as they are triggered.
X.PP
XIf you supply a
X.I date
Xon the command line, it must consist of
X.I day month year
Xwhere
X.I day
Xis the day of the month,
X.I month
Xis (at least the first three letters of) the English name of the month,
Xand
X.I year
Xis a year (all 4 digits) from 1990 to 2075.  These components can appear
Xin any order, but must be separated by spaces.  If a date is supplied,
X.B remind
Xuses it rather than the actual system date as its notion of "today."  You
Xcan use this feature to test how reminders will appear in the future, or
Xto produce a calendar for any month you choose.
X.SH REMINDER FILES
X.B Remind
Xuses scripts called
X.I reminder files
Xto control its operation.  A sample reminder file is shown below:
X.PP
X.nf
X    #!/usr/local/bin/remind
X    # Sample file
X    BANNER Hi there.  Here are your reminders:
X
X    # First some birthdays
X    REM 6 Jan MSG David's birthday.
X    REM 23 Nov +10 MSG El's birthday is %a.
X
X    # Next some housekeeping
X    REM 1 -1 OMIT Sat Sun RUN do_backup
X
X    # Introduce some holidays
X    OMIT 25 Dec        # Christmas
X    OMIT  1 July        # Canada Day
X    OMIT 22 Nov 1990    # American Thanksgiving
X
X    # Business things
X    REM 23 Nov 1990 +2 AT 10:00 +30 *15 MSG \\
X    %"Meeting with Bill%" %1%_Bring papers!
X
X.fi
X.PP
XNote that
X.B remind
Xignores blank lines and lines beginning with "#".  If the character '\\'
Xis the LAST character on the line, it is treated as a continuation
Xcharacter.  You can string many lines together using this character.
XNote that if you use line continuation, then
X.B remind
Xuses the line number of the last line when printing diagnostic messages.
X.PP
XCommands, names of months, etc. can be typed in any
Xmixture of upper- and lower-case.  The convention I use is to
Xuse upper-case for
X.B remind
Xtokens like
X.I
XMSG, OMIT,
Xetc., and mixed case for other words like
X.I January
Xand
X.I Sunday.
X.SH THE REM COMMAND
XThe most-used command in a reminder file is the
X.I REM
Xcommand.  This command is used to denote a reminder.  There are many
Xforms of the
X.I REM
Xcommand; they are represented by:
X.PP
X.RS
XREM [ONCE] [\fIdate_spec\fR]
X[\fIdelta\fR]
X[\fIback\fR]
X[\fIrepeat\fR]
X[OMIT \fIomit_list\fR]
X[AT \fItime\fR [\fItdelta\fR] [\fItrepeat\fR]]
X[MSG | RUN]
X.I body
X.RE
X.PP
XThe
X.I date_spec, delta, back
Xand
X.I repeat
Xcan be specified in any order.  The
X.I OMIT,
Xif present, must follow these three
Xitems.  The
X.I AT,
Xif present, must follow the
X.I OMIT
Xand the other items.  The
X.I MSG
Xor
X.I RUN
Xmust be the last item before the
X.I body.
X.SH DATE SPECIFICATIONS
XThe
X.I date_spec
Xconsists of zero to four parts.  These parts are
X.I day
X(day of month),
X
X
X
X
X
X
X.I month
X(month name),
X.I year
Xand
X.I weekday.
X.I Month
Xand
X.I weekday
Xare the English names of months and weekdays.  At least the first three
Xcharacters must be used.  Case is irrelevant.  The following are examples
Xof the various parts of a
X.I date_spec:
X.TP
X.I day:
X1, 22, 31, 14, 3
X.TP
X.I month:
XJANUARY, feb, March, ApR, may, Aug
X.TP
X.I year:
X1990, 1993, 2030, 95 (interpreted as 1995).  The year can range
Xfrom 1990 to 2075.
X.TP
X.I weekday:
XMonday, tue, Wed, THU, Friday, saturday, sundAy
X.PP
XNote that there can be several
X.I weekday
Xcomponents separated by spaces in a
X.I date_spec.
X.PP
X.B INTERPRETATION OF DATE SPECIFICATIONS
X.PP
XThe following examples show how date specifications are interpreted.
X.PP
X1. Null date specification - the reminder is triggered every day.
XThe trigger date for a specific run is simply the current system date.
X.PP
X2. Only
X.I day
Xpresent.  The reminder is triggered on the specified day of each month.
XThe trigger date for a particular run is the closest such day to the
Xcurrent system date.  For example:
X.nf
X    REM 1 MSG First of every month.
X    REM 31 MSG 31st of every month that has 31 days.
X.fi
X.PP
X3. Only
X.I month
Xpresent.  The reminder is triggered every day of the specified month.
XExample:
X.nf
X    REM Feb MSG Every day in February
X.fi
X.PP
X4.
X.I day
Xand
X.I month
Xpresent.  Examples:
X.nf
X    REM 6 Jan MSG Every 6th of January
X    REM Feb 29 MSG Every 29th of February
X.fi
X.PP
X5.  Only
X.I year
Xpresent. Example:
X.nf
X    REM 1991 MSG Every day in 1991
X.fi
X.PP
X6.
X.I year
Xand
X.I day
Xpresent.  Examples:
X.nf
X    REM 1 1990 MSG 1st of every month in 1990
X    REM 1992 23 MSG 23rd of every month in 1992
X.fi
X.PP
X7.
X.I year
Xand
X.I month
Xpresent.  Examples:
X.nf
X    REM Feb 1991 MSG Every day in Feb 1991
X    REM 1992 September MSG Every day in Sept 1992
X.fi
X.PP
X8.
X.I year, month
Xand
X.I day
Xpresent.  Examples:
X.nf
X    REM 8 Jan 1991 MSG 8th January 1991.
X    REM 1992 March 9 MSG 9th March 1992.
X.fi
X.PP
X9.
X.I weekday
Xonly.  Examples:
X.nf
X    REM Sat MSG Every Saturday
X    REM Mon Tue Wed Thu Fri MSG Every working day
X    REM Monday Wednesday MSG Every Monday and Wednesday
X.fi
X.PP
X10.
X.I weekday
Xand
X.I day
Xpresent.  Examples:
X.nf
X    REM Sat 1 MSG First Saturday of every month
X    REM Mon Tue Wed Thu Fri MSG 1st working day after 15th of every month
X.fi
X.PP
X11.
X.I weekday
Xand
X.I month
Xpresent.  Examples:
X.nf
X    REM Mon March MSG Every Monday in March
X    REM Mon Tue Wed Thu Fri Feb MSG Every working day in February
X.fi
X.PP
X12.
X.I weekday, month
Xand
X.I day
Xpresent.  Examples:
X.nf
X    REM Mon 1 March MSG First Monday in March
X    REM Sat Sun 15 July MSG First Sat or Sun on or after 15 July
X.fi
X.PP
X13.
X.I weekday
Xand
X.I year
Xpresent.  Example:
X.nf
X    REM Sat Sun 1991 MSG Every Saturday and Sunday in 1991
X.fi
X.PP
X14.
X.I weekday, day
Xand
X.I year
Xpresent.  Examples:
X.nf
X    REM Mon 15 1990 MSG 1st Mon after 15th of every month in 1990
X    REM Mon Tue Wed Thu Fri 1 1990 MSG 1st working day of every
X        month in 1990
X.fi
X.PP
X15.
X.I weekday, month
Xand
X.I year
Xpresent.  Example:
X.nf
X    REM Mon Wed 1991 Feb MSG Every Mon and Wed in Feb 1991.
X.fi
X.PP
X16.
X.I weekday, day, month
Xand
X.I year
Xpresent.  Example:
X.nf
X    REM Mon Tue Wed Thu Fri 28 Oct 1990 MSG 1st working day
X        on or after 28 October 1990.
X.fi
X.PP
XNote that when
X.I weekday
Xand
X.I day
Xare specified,
X.B remind
Xchooses the first date on or after the specified
X.I day
Xwhich also satisfies the
X.I weekday
Xconstraint.  It does this by picking the first date on or after the specified
X.I day
Xwhich is listed in the list of
X.I weekdays.
XThus, a reminder like:
X.PP
X.nf
X    REM Mon Tue 28 Oct 1990 MSG Hi
X.fi
X.PP
Xwould be issued only on Monday, 29 October, 1990.  It would not be issued
Xon Tuesday, 30 October, 1990, since the 29th is the first date to satisfy
Xthe
X.I weekday
Xconstraints.
X.PP
X.B BACKWARD SCANNING
X.PP
XSometimes, you need to incorporate "backward scanning" into your date
Xspecification.  This is accomplished with the
X.I back
Xpart of the reminder specification.  If present, the
X.I back
Xis specified as a negative number.  This causes
X.B remind
Xto compute the trigger date as usual, and then move back the specified
Xnumber of days.  For example:
X.PP
X.nf
X    REM Mon 1 -7 MSG Last Monday of every month.
X.fi
X.PP
XThis works by finding the first Monday of every month, and then moving
X"back" seven days.  This results in the last Monday of the previous
Xmonth.  (Warning:  If you have global
X.I OMITs,
Xthis might not work - see
Xthe
X.I OMIT
Xcommand.)
X.PP
XAnother example is:
X.PP
X.nf
X    REM 1 -1 MSG Last day of every month.
X.fi
X.PP
XSince we don't know how many days are in a month, to get to the last day
Xof a month, we go to the first day of the next month and then move back
Xone day.
X.PP
X.B Remind
Xwill automatically scan forwards and backwards until it finds a suitable
Xtrigger date.  Note that large
X.I back
Xvalues can lead to a lot of backtracking and slow the execution of
X.B remind.
X.PP
X.B ADVANCE WARNING
X.PP
X.B Remind
Xcan warn you of an upcoming reminder as far in advance as you desire.  This
Xis specified by a
X.I delta,
Xwhich is a positive number preceded by a "+" sign.  For example:
X.PP
X.nf
X    REM 8 Jan 1992 +3 MSG Test1
X    REM 1 +1 MSG Test2
X.fi
X.PP
XThe reminder "Test1" will be triggered on the 8th of January, 1992, as well
Xas the 3 days preceding it.  All told, "Test1" will be triggered on the
X5th through the 8th of January, 1992.
X.PP
XThe reminder "Test2" will be triggered on the first day of every month, as
Xwell as the day before.  In effect, "Test2" will be triggered on the first
Xand last day of every month.
X.PP
X.I Delta
Xand
X.I back
Xcan be combined:
X.PP
X.nf
X    REM Mon 1 -7 +3 MSG Test3
X.fi
X.PP
XThe reminder "Test3" will be triggered on the last Monday of every month,
Xas well as the three days preceding it.
X.PP
X.B REPEATING REMINDERS
X.PP
XThe
X.I repeat
Xcomponent in a reminder is a number preceded by an asterisk; for example,
X"*14".  The
X.I repeat
Xis used to remind you of events which occur regularly after a specified
Xstart date.  For example, suppose you get paid every second Thursday,
Xand that your last payday was 8 November 1990.  The following reminder
Xwould remind you of each payday 3 days in advance:
X.PP
X.nf
X    REM 8 Nov 1990 *14 +3 MSG Payday is %b!
X.fi
X.PP
XThe
X.I repeat
Xcomponent of "*14" would cause the reminder to be triggered every 14
Xdays from the start date.
X.PP
XIn order to use a
X.I repeat,
Xyou must fully specify the start date.  That means that if
Xyou use a
X.I repeat,
Xyou must specify the
X.I month, day
Xand
X.I year.
XYou can also specify
X.I weekday, back
Xand
X.I local OMITs
Xbut these only affect the calculation of the start date.  Once the
Xstart date is calculated, the reminder is issued regularly every
X.I repeat
Xdays.  Note, in particular, that once the start date is calculated,
X.B remind
Xignores local and global
X.I OMITs
Xwhen calculating the trigger date.  The final trigger date is strictly
Xa multiple of
X.I repeat
Xdays from the start date.
X.PP
X.B THE MSG KEYWORD
X.PP
XThe
X.I MSG
Xkeyword causes the remaining part of the line to be passed through a
Xsubstitution filter and then printed to standard output whenever the
Xreminder is triggered.  See the section "Substitution" for more information
Xabout the substitution filter.
X.PP
X.B THE RUN KEYWORD
X.PP
XThe
X.I RUN
Xkeyword causes the remaining part of the line to be passed through the
Xsubstitution filter and then passed to the default shell for execution
Xwhenever the reminder is triggered.  If the
X.B \-r
Xcommand-line option is specified, all
X.I REM
Xcommands with the
X.I RUN
Xkeyword are ignored.
X.PP
X.B
XGETTING REMINDED ONLY ONCE PER DAY
X.PP
XIf you run
X.B remind
Xfrom your
X.I .login
Xscript, you may only want certain reminders to be run once per day, not
Xonce per login.  Typically, this is used to control
X.I RUN
Xcommands so that they only execute once per day.  To specify this,
Xplace the
X.I ONCE
Xkeyword in the reminder file.  When
X.B remind
Xencounters a
X.I ONCE
Xkeyword, it checks the last-access date of the reminder file.  If it is
Xequal to the current date,
X.B remind
Xassumes that the reminder file has already been run once, and ignored the
Xreminder.  If you start
X.B remind
Xwith the
X.B \-o
Xcommand-line option,
X.B remind
Xignores the
X.I ONCE
Xkeyword.
X.PP
X.B LOCALLY OMITTING WEEKDAYS
X.PP
XA
X.I REM
Xcommand containing the
X.I OMIT
Xkeyword followed by a list of weekdays causes the
X.I delta
Xand
X.I back
Xto ignore the specified weekdays when counting days.  This is called a
X.I local OMIT.
XFor example:
X.PP
X.nf
X    REM 1 +1 OMIT Sat Sun MSG Test4
X.fi
X.PP
XThis reminder prints "Test4" on the first day of every month, as well
Xas the previous day.  If, however, the first day of the month falls on
Xa Sunday or Monday, the reminder is also triggered on the previous
XFriday, since the
X.I delta
Xof +1 does not count Saturdays or Sundays when moving backwards.  Here's
Xanother example:
X.PP
X.nf
X    REM 1 -1 +1 OMIT Sat Sun MSG Test5
X.fi
X.PP
XThis reminder is triggered on the last working day of each month, as well
Xas the working day preceding it.  Let's look at it in detail:
X.PP
XThe
X.I day
Xof "1" specifies the first day of each month.  The
X.I back
Xof "-1" tells
X.B remind
Xto go backwards by one day, not counting Saturday and Sunday as it moves.
XThis takes us the the last working day of the preceding month, which is the
Xtrigger date.  The
X.I delta
Xof "+1" ensures that the reminder will be triggered on the day preceding
Xthis trigger date also.  Finally, if the trigger date happens to be
Xa Monday, the
X.I delta
Xcombined with the
X.I local OMIT
Xcauses the reminder to be triggered on the Friday (and Saturday and Sunday)
Xpreceding the trigger date.
X.PP
X.B THE AT KEYWORD
X.PP
XReminders with the
X.I AT
Xkeyword are called "timed reminders" or "AT reminders."  The
X.I AT
Xkeyword must be followed by a
X.I time,
Xwhich is a time in 24-hour format, from 0:00 to 23:59.  The
X.I time
Xmust be of the form \fIhh\fR:\fImm\fR.
XAlso, after the
X.I AT
Xkeyword, you can supply a
X.I tdelta
Xand a
X.I trepeat.
XThese have the same form as a
X.I delta
Xand a
X.I repeat.
XIn other words, a
X.I tdelta
Xis a number preceded by a "+" sign, and a
X.I trepeat
Xis a number preceded by an asterisk.
X.PP
XWhen
X.B remind
Xencounters a timed reminder, it examines the actual trigger date.  This
Xis the date specified by the date_spec, not counting any
X.I delta
Xwhich may be present.  If the trigger date is the same as the current
Xdate, the timed reminder will be placed on a queue in addition to
Xbeing triggered like a normal reminder.  (If you supply the
X.B \-a
Xcommand-line option, a timed reminder which would be queued will not
Xbe triggered like a normal reminder.)  After
X.B remind
Xhas finished processing the reminder file, it starts up a background
Xprocess to trigger all the queued timed reminders.  As each reminder's
Xtrigger time is reached, it is triggered.  Thus, you can have
X.B remind
Xissue reminders just before important meetings or time-sensitive tasks.
X.PP
XThe
X.I tdelta
Xand
X.I trepeat
Xare interpreted in minutes.  This is how they work:
X.PP
X.nf
X    REM AT 17:00 +60 *15 MSG Hello!
X.fi
X.PP
XThis timed reminder has a trigger time of 5:00pm.  It is also triggered
Xone hour before 5:00pm (because of the
X.I tdelta
Xof +60)
Xand every 15 minutes thereafter until 5:00pm (because of the
X.I trepeat
Xof +15.)  All told, the reminder would be triggered at 4:00pm, 4:15pm,
X4:30pm, 4:45pm and 5:00pm.
X.PP
X.nf
X    REM Fri AT 17:00 +45 *30 MSG Work ends at 5!!
X.fi
X.PP
XThis timed reminder would be placed on the queue every Friday.  It
Xwould be triggered at 4:15pm, 4:45pm and 5:00pm every Friday.  Note
Xthat a timed reminder is always triggered at the time specified
Xafter the
X.I AT
Xkeyword, even if the
X.I tdelta
Xis not a multiple of
X.I trepeat.
X.PP
XIf a reminder has a regular
X.I delta,
Xit will not be queued unless the current system date equals the actual
Xtrigger date.  Thus:
X.PP
X.nf
X    REM Fri +1 AT 17:00 MSG Go home at 5:00!
X.fi
X.PP
XOn Thursdays, this reminder would simply be treated as a regular reminder
Xand printed.  On Fridays, however, it would be queued for timed triggering.
XNote that the
X.B \-q
Xcommand-line option causes
X.B remind
Xto treat timed reminders as normal reminders, and not queue them.
X.SH THE OMIT COMMAND
X.I OMIT
Xexists as a separate command as well as a keyword within a
X.I REM
Xstatement.  When used as a separate command, it is called a
X.I global OMIT,
Xand has the following form:
X.RS
XOMIT
X.I day
X.I month
X[
X.I year
X]
X.RE
XThe arguments can be specified in any order.
X.PP
XThe form without the
X.I year
Xcomponent is used for holidays which fall on the same date each year.
XFor example:
X.PP
X.nf
X    OMIT 25 December    # Christmas
X    OMIT  1 January        # New Year's Day
X.fi
X.PP
X(Note that
X.I OMIT
Xcan have a following comment on the same line, unlike the
X.I REM
Xcommand.)
X.PP
XThe form with the
X.I year
Xcomponent is used for holidays which vary from year to year.  For example:
X.PP
X.nf
X    OMIT 12 October 1990    # Columbus Day 1990
X    OMIT 22 November 1990    # Thanksgiving Day 1990
X.fi
X.PP
XIn its debugging messages,
X.B remind
Xcalls the first form a
X.I partially-specified global OMIT
Xand the second form a
X.I fully-specified global OMIT.
X.PP
XThe dates specified by
X.I global OMITs
Xare omitted by the
X.I back
Xand
X.I delta
Xportions of a reminders, in addition to any
X.I local OMITs.
XFor example:
X.PP
X.nf
X    OMIT 25 December
X    REM 26 +1 OMIT Sat Sun MSG Test6
X.fi
X.PP
XThis would issue a reminder on the 26th of each month, as well as the
Xpreceding working day.  Also, on the 24th of December 1990, the reminder
Xwould be issued.  Even though the 25th of December 1990 is a Tuesday, the
X.I global OMIT
Xwould cause the
X.I delta
Xto skip it.
X.PP
X.I Global OMITs
Xare in force for all reminders following them in the reminder file.  Thus,
Xyou could have a series of reminders for which
X.I global OMITs
Xare inappropriate (such as birthdays or reminders which rely on
X.I back
Xto get to a specific weekday) ahead of any
X.I global OMITs,
Xwith business reminders (for which omission of holidays is appropriate)
Xfollowing the
X.I global OMITs.
X.SH THE INCLUDE COMMAND
XThe
X.I INCLUDE
Xcommand has the following form:
X.RS
XINCLUDE
X.I filename
X.RE
XThis causes
X.B remind
Xto suspend the current file and read the contents of the specified
X.I filename.
XOnce that file has been read,
X.B remind
Xcontinues reading the original file from where it left off.
X.I INCLUDE
Xcommands can be nested to a depth of 10.
X.PP
X.I INCLUDE
Xallows you or someone else to maintain a file of holidays or system-wide
Xreminders that everyone should get.  For example, your reminder file could
Xlook something like this:
X.PP
X.nf
X    #!/usr/local/bin/remind
X    #
X    # Place personal stuff here - birthdays, etc.
X
X    # Now get system-wide global OMITS (holidays)
X    INCLUDE /usr/share/holidays
X
X    # and system-wide reminders
X    INCLUDE /usr/share/reminders
X
X    # Place local business stuff here.
X.fi
X.PP
XThe
X.I ONCE
Xkeyword operates on the last-access date of the top-level file.
XThe access dates of
X.I INCLUDEd
Xfiles are not used to control the operation of the
X.I ONCE
Xkeyword.
X.SH SUBSTITUTION
XBefore being processed, the body of a
X.I REM
Xcommand is passed through a substitution filter.  The filter scans for
Xsequences "%x" where "x" is any letter and certain other characters,
X and performs substitutions as
Xshown below.  (All dates refer to the trigger date of the reminder.)
X.TP
X.B %a
Xis replaced with "on \fIweekday, day month, year\fR"
X.RS
XFor example, consider the reminder:
X.PP
XREM 18 Oct 1990 +4 MSG Meeting with Bob %a.
X.PP
XOn 16 October 1990, it would print "Meeting with Bob on Thursday, 18 October,
X1990."
X.PP
XOn 17 October 1990, it would print "Meeting with Bob tomorrow."
X.PP
XOn 18 October 1990, it would print "Meeting with Bob today."
X.RE
X.TP
X.B %b
Xis replaced with "in \fIdiff\fR day's time" where
X.I diff
Xis the
X.B actual
Xnumber of days between the current date and the trigger date.
X(\fIOMITs\fR have no effect.)
X.RS
XFor example, consider:
X.PP
XREM 18 Oct 1990 +4 MSG Meeting with Bob %b.
X.PP
XOn 16 October 1990, it would print "Meeting with Bob in 2 days' time."
X.PP
XOn 17 October 1990, it would print "Meeting with Bob tomorrow."
X.PP
XOn 18 October 1990, it would print "Meeting with Bob today."
X.RE
X.TP
X.B %c
Xis replaced with "on \fIweekday\fR"
X.RS
XExample: REM 18 Oct 1990 +4 MSG Meeting with Bob %c.
X.PP
XOn 16 October 1990, it would print "Meeting with Bob on Thursday."
X.PP
XOn 17 October 1990, it would print "Meeting with Bob tomorrow."
X.PP
XOn 18 October 1990, it would print "Meeting with Bob today."
X.RE
X.TP
X.B %d
Xis replaced with "\fIday\fR", the day of the month.
X.TP
X.B %e
Xis replaced with "on \fIdd/mm/yyyy\fR"
X.TP
X.B %f
Xis replaced with "on \fImm/dd/yyyy\fR"
X.TP
X.B %g
Xis replaced with "on \fIweekday, day month\fR"
X.TP
X.B %h
Xis replaced with "on \fIdd/mm\fR"
X.TP
X.B %i
Xis replaced with "on \fImm/dd\fR"
X.TP
X.B %j
Xis replaced with "on \fIweekday, month day-th, year\fR"  This form appends the
Xcharacters "st", "nd", "rd" or "th" to the day of the month, as appropriate.
X.TP
X.B %k
Xis replaced with "on \fIweekday, month day-th\fR"
X.TP
X.B %l
Xis replaced with "on \fIyyyy/mm/dd\fR"
X.TP
X.B %m
Xis replaced with "\fImonth\fR", the name of the month.
X.TP
X.B %n
Xis replaced with the number (1 to 12) of the month.
X.TP
X.B %o
Xis replaced with " (today)" if and only if the current system date is the same
Xas the date being used by
X.B remind
Xas the current date.  Recall that you can specify a date for
X.B remind
Xto use on the command line.  This substitution is not generally useful in a
X.I REM
Xcommand, but is useful in a
X.I BANNER
Xstatement.  (See the section "The BANNER Command.)
X.TP
X.B %p
Xis replaced with "s" if the
X.I diff
Xbetween the current date and the trigger date is not 1.  You can use this
Xto construct reminders like:
X.RS
XREM 1 Jan +4 MSG %x day%p to go before New Year!
X.RE
X.TP
X.B %q
Xis replaced with "'s" if the
X.I diff
Xbetween the trigger date and the current date is 1.  Otherwise, it is replaced
Xwith "s'"  This can be used as follows:
X.RS
XREM 1 Jan +4 MSG New Year in %x day%q time!
X.RE
X.TP
X.B %r
Xis replaced with the day of the month (01 to 31) padded with a leading zero
Xif needed to pad to two digits.
X.TP
X.B %s
Xis replaced with "st", "nd", "rd" or "th" depending on the day of the month.
X.TP
X.B %t
Xis replaced with the number of the month (01 to 12) padded to two digits
Xwith a leading zero.
X.TP
X.B %u
Xis replaced with "on \fIweekday, day-th month, year\fR"  This is similar
Xto
X.B %a
Xexcept that "st", "nd", "rd" or "th" is added to the
X.I day
Xas appropriate.
X.TP
X.B %v
Xis replaced with "on \fIweekday, day-th month\fR"
X.TP
X.B %w
Xis replaced with "\fIweekday\fR", the name of the day of the week.
X.TP
X.B %x
Xis replaced with the
X.I diff
Xbetween the current date and the trigger date.  The
X.I diff
Xis defined as the actual number of days between these two dates;
X.I OMITs
Xare not counted.  (Strict date subtraction is performed.)
X.TP
X.B %y
Xis replaced with "\fIyear\fR", the year of the trigger date.
X.TP
X.B %z
Xis replaced with "\fIyy\fR", the last two digits of the year.
X.TP
X.B %_
X(percent-underscore) is replaced with a newline.  You can use this to
Xachieve multi-line reminders.
X.TP
X.B %1
Xis replaced with "now", "\fIm\fR minutes from now", "\fIm\fR minutes ago",
X"\fIh\fR hours from now", "\fIh\fR hours ago", "\fIh\fR hours and \fIm\fR
Xminutes from now" or "\fIh\fR hours and \fIm\fR minutes ago", as appropriate
Xfor a timed reminder.  Note that unless you specify the \fB\-a\fR option,
Xtimed reminders will be triggered like normal reminders, and thus a timed
Xreminder which occurred earlier in the day may be triggered.  This
Xcauses the need for the "...ago" forms.
X.TP
X.B %2
Xis replaced with "at \fIhh\fR:\fImm\fRam" or "..pm" depending on the
X.I AT
Xtime of the reminder.
X.TP
X.B %3
Xis replaced with "at \fIhh\fR:\fImm\fR" in 24-hour format.
X.TP
X.B %4
Xis replaced with "\fImm\fR" where \fImm\fR is the number of minutes between
X"now" and the time specified by \fIAT\fR.  If the \fIAT\fR time is
Xearlier than the current time, then the result is negative.
X.TP
X.B %5
Xis replaced with "\fIma\fR" where \fIma\fR is the absolute value of the number
Xproduced by \fB%4\fR.
X.TP
X.B %6
Xis replaced with "ago" or "from now", depending on the relationship between
Xthe \fIAT\fR time and the current time.
X.TP
X.B %7
Xis replaced with the number of hours between the \fIAT\fR time and the
Xcurrent time.  It is always non-negative.
X.TP
X.B %8
Xis replaced with the number of minutes between the \fIAT\fR time and
Xthe current time, after the hours (\fB%7\fR) have been subtracted out.
XThis is a number ranging from 0 to 59.
X.TP
X.B %9
Xis replaced with "s" if the value produced by \fB%8\fR is not 1.
X.TP
X.B %0
Xis replaced with "s" if the value produced by \fB%7\fR is not 1.
X.TP
X.B %!
Xis replaced with "is" if the current time is before the \fIAT\fR time,
Xor "was" if it is after.
X.TP
X.B
X%"
X(percent-doublequote) is removed.  This sequence is not
Xused by the substitution filter,
Xbut is used to tell \fBremind\fR which text to include in a calendar
Xentry when the \fB\-c\fR option is chosen.  See the section "Producing
Xa Calendar"
X.PP
XNotes:
X.TP
Xo
X.B Remind
Xnormally prints a blank line after each reminder; if the last character
Xof the body is '%', the blank line will not be printed.
X.TP
Xo
XSubstitutions a, b, c, e, f, g, h, i, j, k, l, u and v all are replaced
Xwith "today" if the current date equals the trigger date, or "tomorrow"
Xif the trigger date is one day after the current date.  Thus, they are
X.B not
Xthe same as substitutions built up from the simpler %w, %y, etc.
Xsequences.
X.TP
Xo
XAny of the substitutions dealing with time (0 through 9 and '!')
Xproduce undefined results if used in a reminder which does not have
Xan \fIAT\fR keyword.  Also, if a reminder has a \fIdelta\fR and may
Xbe triggered on several days, the time substitutions ignore the date.  Thus,
Xthe \fB%1\fR substitution may report that a meeting is in 15 minutes, for
Xexample, even though it may only be in 2 days time, because a \fIdelta\fR has
Xtriggered the reminder.  It is recommended that you use the time substitutions
Xonly in timed reminders with no \fIdelta\fR which are designed to be
Xqueued for timed activation.
X.TP
Xo
XCapital letters can be used in the substitution sequence, in which case
Xthe first character of the substituted string is capitalized (if it is
Xnormally a lower-case letter.)
X.TP
Xo
XAll other characters following a "%" sign are simply copied.  In particular,
Xto get a "%" sign out, use "%%" in the body.  To start the body of a reminder
Xwith a space, use "% ", since
X.B remind
Xnormally scans for the first non-space character after a
X.I MSG
Xor
X.I RUN
Xtoken.
X.SH PRODUCING A CALENDAR
XIf you provide the \fB\-c\fR option, the \fBremind\fR will scan your
Xreminder file and produce a calendar with your reminders entered on the
Xappropriate dates.
X.PP
XWhen you produce a calendar, \fBremind\fR will \fBnot\fR pass the text
Xthrough the substitution mechanism.  Thus, you must indicate to \fBremind\fR
Xwhich portions of the text should be placed in the calendar.  This is done
Xwith the \fB%"\fR sequence.  Here's an example:
X.PP
X.nf
X    REM 6 Jan +6 MSG %"David's birthday%" is %a.
X.fi
X.PP
XWhen you run \fBremind\fR normally, it executes the reminder as if the
X.B
X%"
Xsequences were not there.  When you produce a calendar with the \fB\-c\fR
Xoption, however, only the text "David's birthday" is entered into the
Xcalendar.  For convenience, timed reminders are sorted by time before
Xbeing entered into the calendar, and the time of each reminder is printed
Xbefore the reminder text.
X.PP
XNote that only \fIMSG\fR reminders are included in the calendar; \fIRUN\fR
Xreminders are ignored.  If you indicate empty text for the calendar entry
Xwith the sequence \fB%"%"\fR, then the reminder is ignored when producing
Xthe calendar.
X.SH THE BANNER COMMAND
XWhen
X.B remind
Xissues reminders, it normally prints a message saying:
X.PP
X"Reminders for \fIweekday, day-th month, year\fR (today):"
X.PP
X(If you supply a date on the command line different from the system date,
Xthe "(today)" portion is omitted.)
X.PP
XYou can change this default to anything you want with the
X.I BANNER
Xcommand.  It should appear in the reminder file before any
X.I REM
Xcommands.  (This is not enforced, but a
X.I BANNER
Xcommand encountered after a reminder has been triggered will be ignored.)
X.PP
XThe format of
X.I BANNER
Xis:
X.PP
XBANNER
X.I string
X.PP
XThe
X.I string
Xis passed through the substitution mechanism described before, using the
Xcurrent date and time for substitution.  The standard banner is described by:
X.PP
X.nf
X    BANNER Reminders for %w, %d%s %m, %y%o:
X.fi
X.PP
XYou can have a blank banner by using:
X.PP
X.nf
X    BANNER %
X.fi
X.PP
X.SH PURGING REMINDER FILES
XYou should periodically purge your reminder file of "expired"
X.I REM
Xcommands and global
X.I OMITs.
XThese are reminders which took place in the past and can never occur
Xagain, or
X.I OMITs
Xwhich are for past years.  Of course, only
X.I REMs
Xand
X.I OMITs
Xwith the
X.I year
Xspecified can ever expire.
X.PP
XTo purge your reminder file, run
X.B remind
Xin
X.I purge
Xmode.  This mode simply echoes non-expired lines to standard output, and
Xexpired lines to standard error.  Thus, to purge a file, you could type:
X.PP
X.nf
X    REMIND -p notes.old > notes.new
X.fi
X.PP
XThe file "notes.new" would contain all non-expired lines from "notes.old."
XAll expired lines are echoed to the screen.
X.I INCLUDEd
Xfiles are read and processed, but not purged.  You must purge each
X.I INCLUDEd
Xfile separately.
X.PP
XYou can supply a date on the command line when purging, but beware:  If you
Xsupply a date in the future, you may inadvertently purge lines which have not
Xreally expired yet.
X.SH DEBUGGING A REMINDER FILE
XThe debug command-line option \-d is used to debug reminder files.  It tells
Xyou useful information about the reminder file.  It displays the trigger date
Xof each reminder, and places an asterisk by those which would be issued
Xon the current date.  It also informs you of
X.I OMITs
Xwhich have expired, and gives warnings about situations which could lead
Xto long execution times or unexpected results.
X.PP
XAll debugging messages are sent to standard error.
X.SH EXAMPLES OF REMINDERS
XThis section is a sampling of what you can do with \fBremind\fR.
X.PP
X.nf
X    REM 5 Feb 1991 AT 14:00 +45 *30 \\
X    RUN mail -s "Meeting %2" $LOGNAME </dev/null
X.fi
X.PP
XOn 5 Februrary, 1991, this reminder will mail
Xyou reminders of a 2:00pm meeting at 1:15,
X1:45 and 2:00.  The subject of the mail message will be "Meeting at 2:00pm"
Xand the body of the message will be blank.
X.PP
X.nf
X    REM AT 17:00 RUN echo "5:00pm - GO HOME!" > /tmp/rem.$$; \\
X    xterm -g 80x25+0+0 -e view /tmp/rem.$$; rm -f /tmp/rem.$$
X.fi
X.PP
XThis reminder will pop up an xterm at 5:00pm every day.  The xterm
Xwill execute view (read-only "vi") on a file which reads "5:00pm - GO HOME!"
X.PP
X.nf
X    remind -c12 /dev/null 1 Jan 1991
X.fi
X.PP
XThis invocation of \fBremind\fR will cause it to print a calendar for
X1991, with all entries left blank.
X.SH AUTHOR
XDavid F. Skoll
X.SH BUGS
X.B Remind
Xwas originally written for MS-DOS and ported to UNIX.  It does some things
Xin an ungainly way.
X.PP
XDate calculation algorithms are fairly "brute force."
X.PP
XThe MS-DOS version of \fBremind\fR does not support queuing or timed
Xactivation of reminders.  It does, however, support the other semantics
Xof the \fIAT\fR keyword.
SHAR_EOF
$TOUCH -am 1116130390 remind.1 &&
chmod 0600 remind.1 ||
echo "restore of remind.1 failed"
set `wc -c remind.1`;Wc_c=$1
if test "$Wc_c" != "32451"; then
    echo original size 32451, current size $Wc_c
fi
fi
# ============= remind.mak ==============
if test X"$1" != X"-c" -a -f 'remind.mak'; then
    echo "File already exists: skipping 'remind.mak'"
else
echo "x - extracting remind.mak (Text)"
sed 's/^X//' << 'SHAR_EOF' > remind.mak &&
X# Simple-minded MAKE file.
X
XHEADERS = globals.h protos.h defines.h
XWARN = /W3
Xmain.obj: main.c $(HEADERS)
X   cl $(WARN) /AS /Fomain.obj /c main.c
X
Xnextdate.obj: nextdate.c $(HEADERS)
X   cl $(WARN) /AS /Fonextdate.obj /c nextdate.c
X
Xdorem.obj: dorem.c $(HEADERS)
X   cl $(WARN) /AS /Fodorem.obj /c dorem.c
X
Xinit.obj: init.c $(HEADERS)
X   cl $(WARN) /AS /Foinit.obj /c init.c
X
Xdosubst.obj: dosubst.c
X   cl $(WARN) /AS /Fodosubst.obj /c dosubst.c
X
Xfiles.obj: files.c
X   cl $(WARN) /AS /Fofiles.obj /c files.c
X
Xcalendar.obj: calendar.c
X   cl $(WARN) /AS /Focalendar.obj /c calendar.c
X
Xcache.obj: cache.c
X   cl $(WARN) /AS /Focache.obj /c cache.c
X
Xremind.exe: main.obj nextdate.obj dorem.obj init.obj dosubst.obj files.obj calendar.obj cache.obj
X   cl /Feremind.exe main.obj nextdate.obj dorem.obj init.obj dosubst.obj files.obj calendar.obj cache.obj
X
SHAR_EOF
$TOUCH -am 1116093790 remind.mak &&
chmod 0600 remind.mak ||
echo "restore of remind.mak failed"
set `wc -c remind.mak`;Wc_c=$1
if test "$Wc_c" != "847"; then
    echo original size 847, current size $Wc_c
fi
fi
echo "End of part 4, continue with part 5"
exit 0