Black Box 4/BlackBox.cdr/desktop/rem22_05.arj/REMIND.DOC

Text File | 1990-12-19 | 44KB | 1,199 lines

                                    REMIND 2.2 #5

                                   By David Skoll

                               (C) 1990 by David Skoll

                                  19 December 1990



                  To print this document, type: COPY REMIND.DOC PRN





                                         Table of Contents


          1. INTRODUCTION  . . . . . . . . . . . . . . . . . . . . . . .   1

          2. THE FINE PRINT  . . . . . . . . . . . . . . . . . . . . . .   2

          3. USING REMIND  . . . . . . . . . . . . . . . . . . . . . . .   3
               3.1. Running REMIND . . . . . . . . . . . . . . . . . . .   3
               3.2. The REM Command  . . . . . . . . . . . . . . . . . .   4
                    3.2.1. Date specifications . . . . . . . . . . . . .   5
                    3.2.2. Backward Scanning . . . . . . . . . . . . . .   7
                    3.2.3. Advance Warning . . . . . . . . . . . . . . .   7
                    3.2.4. The MSG Keyword . . . . . . . . . . . . . . .   8
                    3.2.5. The RUN Keyword . . . . . . . . . . . . . . .   8
                    3.2.6. Getting Reminded only Once per Day  . . . . .   8
                    3.2.7. Locally Omitting Weekdays . . . . . . . . . .   8
                    3.2.8. Periodic Reminders  . . . . . . . . . . . . .   9
                    3.2.9. The AT Keyword  . . . . . . . . . . . . . . .   9
                    3.2.10. The BEFORE, SKIP and AFTER Keywords  . . . .  10
               3.3. The OMIT Command . . . . . . . . . . . . . . . . . .  10
               3.4. The INCLUDE Command  . . . . . . . . . . . . . . . .  11
               3.5. Substitution . . . . . . . . . . . . . . . . . . . .  12
               3.6. Producing a Calendar . . . . . . . . . . . . . . . .  16
               3.7. The BANNER Command . . . . . . . . . . . . . . . . .  16

          4. PURGING REMINDER FILES  . . . . . . . . . . . . . . . . . .  17

          5. DEBUGGING YOUR REMINDER FILE  . . . . . . . . . . . . . . .  18
               5.1. Format of Debugging and Error Messages . . . . . . .  18

          6. WISH LIST . . . . . . . . . . . . . . . . . . . . . . . . .  18

          7. WISHES LIST . . . . . . . . . . . . . . . . . . . . . . . .  19



















          REMIND 2.2   (19 December 1990)                             Page i





          1. INTRODUCTION

          REMIND version 2.2 is an enhanced reminder program.  It is similar
          to the Unix "calendar" program, only much more versatile and with
          enhanced features.

          REMIND reads a text file (which you create) containing a list of
          commands.  Most of these commands are "reminders" which are issued
          whenever the current date meets specified criteria.  The reminders
          can print a message to the console or run a program.

          Some features of REMIND include the following:

          o    Ability to issue a reminder any number of days in advance

          o    Ability to skip holidays and weekends when reminding in
               advance

          o    Ability to include standard files for system-wide reminders
               or standard sets of holidays

          o    Advanced date calculation

          o    Ability to run a program rather than display a message when a
               reminder is issued

          o    Ability to purge reminder file to remove obsolete reminders

          o    Ability to create a calendar with your reminders
               automatically filled in on the appropriate dates























          REMIND 2.2   (19 December 1990)                             Page 1





          2. THE FINE PRINT

          REMIND is yours to keep, use, distribute and enjoy.  However,
          there are some things you can't do:

          i)   You can't claim that you (or anyone other than I) wrote
               REMIND.

          ii)  You can't distribute REMIND for profit.

          iii) You can't distribute a modified version of REMIND, or a
               version of REMIND which is missing this document.

          REMIND is copyright (C) 1990 by David Skoll.

          If you wish to support the creation of software like REMIND, you
          can send me a donation.  Any amount would be appreciated; the
          suggested amount is $18.  Note that this is strictly voluntary. If
          you don't make a donation, you don't suffer any penalties.  If you
          make a donation, you don't get any special service for it.  But
          you will have helped support the creation of useful and
          reasonably-priced software.

          My mailing address is:

          David Skoll
          4-317 LeBreton Street
          Ottawa, Ontario
          K1S 4L4 Canada
          Tel. [phone]























          REMIND 2.2   (19 December 1990)                             Page 2





          3. USING REMIND

          The first thing you need to use REMIND is a reminder file.  This
          is a text file containing commands telling REMIND what to do.
          Here's a sample reminder file:

               # Sample file - by D. Skoll
               BANNER Hi, Dave!  Here are your reminders:

               # First some birthdays
               REM 6 Jan MSG David's birthday!
               REM 23 Nov +10 MSG El's birthday is %a.

               # Next some housekeeping stuff
               REM 1 -1 OMIT sat sun RUN dobackup.bat

               # Introduce some holidays
               OMIT 25 dec      # Christmas
               OMIT 1 jul       # Canada day
               OMIT 22 nov 1990 # American thanksgiving

               # Business things
               REM 23 nov 1990 +2 AT 14:00 MSG %"Meeting with Bill%" \
               at %2 %a.

          Note that REMIND ignores blank lines and lines beginning with "#".
          If the last character on a line is a backslash "\", then it is
          treated as a continuation character and the next line is read.
          You can string together several lines in this fashion, providing
          the total length does not exceed 510 characters.  Also, commands,
          names of months, etc. can be typed in any mixture of upper- and
          lower-case.  The convention I use is to use upper case for REMIND
          tokens like MSG, OMIT, etc. and mixed case for other words like
          January and Sunday.


          3.1. Running REMIND

          To run REMIND, simply type:

               REMIND rem_file

          where rem_file is the name of the reminder file.  The full form of
          the REMIND command line is:

          REMIND [-d | -p | -c [-w -s]] [-v] [-o] [-r] rem_file [date_spec]

          Items in square brackets are optional.  Note that you can use one
          of the -d and -p options, but not both.  The meanings of the
          options are:



          REMIND 2.2   (19 December 1990)                             Page 3





          -d   Debug mode - runs through the reminder file printing useful
               information to the standard error stream.

          -p   Purge mode - purges expired reminders from the reminder file.

          -c   Calendar mode - this causes REMIND to produce a calendar for
               the current month.  If you supply a number n from 1 to 12
               after the c (eg, -c6), then the calendar is produced for n
               months.

          -w   When used with the -c option, specify the width of the
               display device when producing a calendar.  The default is -
               w80; you can specify a different width. (Eg -w132 for a 132-
               column printer.)

          -s   When used with the -c option, produce a "simple" calendar
               listing rather than a formatted calendar.  This is useful if
               you wish to write a program which produces a "prettier"
               calendar than the REMIND default.

          -v   Verbose mode - prints long error and debugging messages.

          -o   Ignore the 'ONCE' directives in the reminder file.  (See the
               section "Getting Reminded only Once per Day")

          -r   Ignore the 'RUN' directives in the reminder file. (See the
               section "The RUN Keyword")

          date_spec Run the reminder file as if the current date were the
                    specified date.  This allows you to see what reminders
                    you'll get on a date in the future.  This date must be
                    specified in full - for example, "6 July 1992" or "Dec
                    12 1999"

          3.2. The REM Command

          The most-used command in the reminder file is the REM command.
          This command is used to denote a reminder.  The form of the REM
          command is:

          REM [ONCE] [BEFORE | AFTER | SKIP] [date_spec] [delta] [back]
               [repeat] [OMIT omit_list] [AT time [tdelta] [trepeat]] <MSG |
               RUN> body

          Note that these should all be on one line; the descriptions
          unfortunately are too long to fit on one line.  The date_spec,
          delta, back and repeat can be specified in any order.  The OMIT,
          if present, must follow these items.  The AT, if present, must
          follow the OMIT and the other items.  The MSG or RUN must be the
          last item.



          REMIND 2.2   (19 December 1990)                             Page 4





          3.2.1. Date specifications

          The date_spec consists of zero to four parts.  These parts are DAY
          (day of month), MONTH (month name), YEAR and WEEKDAY.  MONTH and
          WEEKDAY are the English names of months and weekdays.  At least
          the first three characters must be used.  Case is irrelevant.  The
          following are examples of the various parts of a date
          specification:

          DAY:      1, 22, 31, 14, 3

          MONTH:    JANUARY, feb, March, ApR, may, june, Jul, August

          YEAR:     1990, 1993, 2030, 95 (Interpreted as 1995)
                    The YEAR can range from 1990 to 2075.

          WEEKDAY:  Monday, tue, WED, Thu, Friday, saturday, sundAy

          Note that there can be several WEEKDAY components separated by
          spaces.  The interpretation of date specifications is discussed
          below.

          The date specification is used by REMIND to compute a TRIGGER
          DATE.  The trigger date is the date on which a reminder will take
          place.  Here are examples of how trigger dates are computed:

          1.   Null date_spec.  The reminder is triggered every day - the
               trigger date is simply the system date.

          2.   Only DAY present.  The reminder is triggered on the specified
               day of each month.  The trigger date is the closest such date
               to the system date.  For example:
               REM 1 MSG Triggered on first of every month.
               REM 31 MSG Triggered on 31st of every month with 31 days.

          3.   Only MONTH present:  Triggered every day of the specified
               month.  Example:
               REM feb MSG Triggered every day in February.

          4.   DAY and MONTH present.  Examples:
               REM 6 Jan MSG Triggered every 6th of January.
               REM 29 Feb MSG Triggered every 29th of February.

          5.   YEAR present. Example:
               REM 1990 MSG Triggered every day in 1990.

          6.   YEAR and DAY present. Examples:
               REM 1 1990 MSG Triggered on first of every month in 1990.
               REM 1991 23 MSG Triggered on 23rd of every month of 1991.




          REMIND 2.2   (19 December 1990)                             Page 5





          7.   YEAR and MONTH present. Examples:
               REM Feb 1990 MSG Triggered every day in February 1990.
               REM 1991 September MSG Triggered every day in September 1991.

          8.   YEAR, MONTH and DAY present. Examples:
               REM 8 January 1991 MSG Triggered on 8 Jan 1991 only.
               REM 1992 March 9 MSG Triggered on 9 March 1991 only.

          9.   WEEKDAY only.  Examples:
               REM Saturday MSG Triggered every Saturday.
               REM mon tue wed thu fri MSG Triggered every working day.
               REM mon wed MSG Triggered every Monday and Wednesday.

          10.  WEEKDAY and DAY.  Examples:
               REM Sat 1 MSG Triggered on the first Saturday of each month.
               REM Mon Tue Wed Thu Fri 15 MSG Triggered on the first working
                    day on or after the 15th of each month.

          11.  WEEKDAY and MONTH.  Examples:
               REM mon march MSG Triggered every Monday in March.
               REM mon tue wed thu fri feb MSG Triggered every working day
                    in February.

          12.  WEEKDAY, MONTH and DAY.  Examples:
               REM mon 1 March MSG Triggered on the first Monday in March
               REM sat sun 15 July MSG Triggered on the first Saturday or
                    Sunday on or after the 15th of July.

          13.  WEEKDAY and YEAR.  Example:
               REM sat sun 1991 MSG Triggered every Saturday and Sunday in
                    1991.

          14.  WEEKDAY, DAY and YEAR.  Examples:
               REM mon 15 1990 MSG First Monday after the 15th of every
                    month in 1990.
               REM mon tue wed thu fri 1 1990 MSG First working dat of
                    every month in 1990.

          15.  WEEKDAY, MONTH and YEAR.  Example:
               REM Mon Wednesday 1991 Feb MSG Every Monday and Wednesday in
                    February 1991.

          16.  WEEKDAY, DAY, MONTH and YEAR.  Example:
               REM mon tue wed thu fri 28 Oct 1990 MSG First working day on
                    or after 28 October 1990.

          Note that when WEEKDAY and DAY are specified, REMIND chooses the
          first date on or after the specified DAY which also satisfies the
          WEEKDAY constraint.  It does this by picking the first date on or
          after the specified DAY which is listed in the list of WEEKDAYs.
          Thus, a reminder like


          REMIND 2.2   (19 December 1990)                             Page 6





               REM Mon Tue 28 Oct 1990 MSG Hi

          would be issued only on Monday, 29 October, 1990.  It would not be
          issued on Tuesday, 30 October, 1990 since the 29th satisfies the
          constraints.

          3.2.2. Backward Scanning

          Sometimes, you need to incorporate "backward scanning" into your
          date specification.  This is accomplished with the "back" part of
          the reminder specification.  If present, the back is specified as
          a negative number.  This causes REMIND to compute the trigger date
          and then move back the specified number of days.  For example:

               REM Mon 1 -7 MSG The LAST Monday of every month.

          This works by finding the first Monday of every month and then
          moving "back" seven days.  This results in the last Monday of the
          previous month.  Another example:

               REM 1 -1 MSG The LAST day of every month.

          Since we don't know how many days are in a month, to get to the
          last day of a month, we go to the first day of the next month and
          then move back one day.

          Remind will automatically scan forwards and backwards until it
          finds a trigger date meeting the criteria.  Note that a back value
          greater than 7 can lead to excessive backtracking and long
          execution time.

          3.2.3. Advance Warning

          REMIND can warn you of an upcoming reminder as far in advance as
          you desire.  This is specified by a delta, which is a positive
          number prefaced with a "+" sign.  For example:

               REM 8 Jan 1992 +3 MSG This reminder is emitted starting 3
                    days before January 8 1992.

               REM 1 +1 MSG This reminder is emitted on the first of every
                    month, as well as the last day of the preceding month.

          In summary, a reminder with a delta is triggered on the usual
          date, as well as all days preceding the trigger date by up to
          "delta" days.  This is useful for being reminded of birthdays well
          in advance!

          Deltas and backs can be combined:

               REM Mon 1 -7 +3 MSG Emitted on the last Monday of every month
                    as well as the 3 days preceding it.

          REMIND 2.2   (19 December 1990)                             Page 7





          3.2.4. The MSG Keyword

          The MSG keyword causes the remaining part of the line to be
          printed to standard output when the reminder is triggered.  The
          line is first passed through a substitution routine before being
          printed.  See the section "Substitution" for details about
          substitution.

          3.2.5. The RUN Keyword

          The RUN keyword causes the remaining part of the line to be passed
          through the substitution routine, and then passed to the shell for
          execution as if you had typed the command at the shell prompt.

          3.2.6. Getting Reminded only Once per Day

          In some situations, you only want a reminder emitted once per day.
          This is useful if the reminder runs a program which should be run
          only once.  (Typically, such a reminder would have no delta.
          Otherwise, the program would be run once for each day within the
          delta preceding the trigger date.)

          When REMIND finishes processing a file, it marks the modification
          date of the file with the current system date.  When it is run the
          next time, if the file modification date and the system date are
          the same, it ignores reminders which contain the ONCE keyword.
          For example:

               REM ONCE 1 Mon RUN do_backup

          This reminder runs the program "do_backup" on the first Monday of
          each month.  It runs it only the first time REMIND is invoked.  If
          REMIND is subsequently invoked on the same day, this reminder is
          ignored.

          3.2.7. Locally Omitting Weekdays

          A reminder containing the keyword OMIT followed by a list of
          weekdays causes the delta and back to ignore the specified days
          when moving backwards.  This is called a "local omit." For
          example:

               REM 1 +1 OMIT sat sun MSG Hello there!

          This reminder prints the message "Hello there!" on the first day
          of each month, and the day before.  If, however, the first day of
          the month falls on a Sunday or Monday, the message is also issued
          on the preceding Friday, since the delta does not count Saturday
          and Sunday as it moves backwards.

               REM 1 -1 +1 OMIT sat sun MSG Hi there!


          REMIND 2.2   (19 December 1990)                             Page 8





          This one issues a reminder on the last working day of each month,
          as well as the preceding working day.  Let's look at it in detail:

          The "1" specifies the first of each month.  The "back" of -1 tells
          REMIND to go backwards by one day, not counting Saturday and
          Sunday as it moves.  This takes us to the last working day of the
          preceding month.  The delta of +1 ensures that the reminder will
          be emitted on the day preceding this day also.  Finally, if the
          last working day of the month happens to be a Monday, the delta
          combined with the local OMIT causes the reminder to be issued the
          Friday before.  Play around with deltas, backs and OMITs.  They
          can be very powerful and quickly become easy to understand.

          3.2.8. Periodic Reminders

          Sometimes reminders repeat periodically, where the repetition
          period is a specific number of days.  To create a repeating
          reminder, use the "repeat" item, which is a number preceded by an
          asterisk.  (Example: *14)  You supply a start date and the
          repetition factor, and REMIND will trigger the reminder
          periodically.  Note that to use a repetition factor, you must
          specify DAY, MONTH and YEAR in the date-spec.  You can use
          WEEKDAYS, deltas, backs and OMITS in the date-spec.  However,
          these are used ONLY in the calculation of the start date.  Once
          the start date has been calculated, OMITs are ignored and the
          reminder is triggered in strict multiples of the period after the
          start date.

          For example, suppose you get paid every second Thursday, and that
          8 November 1990 was a payday.  You can be reminded of your payday
          with this reminder:

               REM 8 Oct 1990 +3 *14 MSG Payday is %b.

          The delta of +3 means you'll be warned 3 days ahead of every
          payday.  The repeat of *14 means that the reminder will be
          triggered every 14 days starting from 8 October 1990.

          3.2.9. The AT Keyword

          The AT keyword specifies a time for reminders which have times
          associated with them.  You should follow the AT keyword with a
          time in 24-hour format, from 0:00 to 23:59.  The tdelta and
          trepeat items have the same format as delta and repeats for dates.
          They are used in the UNIX version of REMIND to specify how many
          minutes and over what interval to repeatedly pop up timed
          reminders.  These fields are accepted by the MS-DOS version of
          REMIND, but do not serve any useful purpose.  The AT keyword does,
          however, cause reminders to be sorted by time when placed on the
          calendar listing.  Here are examples of how to use AT:

          REM AT 17:00 MSG Work ends at %2!

          REMIND 2.2   (19 December 1990)                             Page 9





          REM 8 July 1991 AT 10:00 MSG Meeting with Bill %1.

          3.2.10. The BEFORE, SKIP and AFTER Keywords

          Normally, if a reminder falls on a holiday (see "The OMIT
          Command"), the reminder is still issued.  This can cause some
          strange effects.  Consider the following:

          OMIT 25 Dec    # Xmas Holiday
          OMIT 1 Jan     # New Year's Day
          REM Tue MSG Departmental meeting.

          The reminder "Departmental meeting"  would be issued every
          Tuesday, including 25 December, 1990, and 1 January, 1991, even
          though those days are holidays.  If, however, you use the SKIP
          keyword:

          REM SKIP Tue MSG Departmental meeting.

          then the reminder would be issued every Tuesday, except on those
          Tuesdays which happen to be holidays.  The BEFORE keyword would
          cause the reminder to be issued on Tuesdays, unless the Tuesday is
          a holiday.  In that case, the reminder would be issued the Monday
          before.  The AFTER keyword is similar, except that the reminder
          would be issued on the Wednesday following any holidays occurring
          on Tuesday.

          In summary:  The SKIP keyword causes reminder which happen to fall
          on globally or locally omitted days not to be issued.  The BEFORE
          keyword moves reminders to the first non-omitted day prior to the
          holiday.  The AFTER keyword moves them to the first non-omitted
          day after the holiday.  Here are some examples:

          REM AFTER 1 OMIT Sat Sun RUN Backup_on_first_working_day_of_month
          REM SKIP Tue MSG Weekly Meeting
          REM BEFORE 4 Dec 1991 *14 MSG Payday on every second Tuesday;\
               Monday if that Tuesday happens to be a holiday.


          3.3. The OMIT Command

          In addition to being part of a REM command, the OMIT keyword can
          act as a command in its own right.  When used this way, it is
          called a "global omit" and is used to specify holidays.  The OMIT
          command has two forms:

               OMIT month day
               OMIT year month day

          The components can be in any order.  For convenience, you can also
          specify a DELTA and a RUN or MSG, as with the REM command.  This
          is used to avoid duplication.  For example, the command:

          REMIND 2.2   (19 December 1990)                            Page 10






               OMIT 25 Dec +3 MSG %"Christmas%" is %a.

          is exactly equivalent to:

               OMIT 25 Dec
               REM 25 Dec +3 MSG %"Christmas%" is %a.

          The first format is used for holidays which fall on the same day
          each year.  For example:

               OMIT 25 December  # Christmas
               OMIT 1  January   # New year's day.

          The second format is used for holidays which move from year to
          year.  For example:

               OMIT 12 October 1990 # Columbus day 1990
               OMIT 22 November 1990 # Thanksgiving day 1990

          These dates are omitted by the "back" and "delta" portions of a
          reminder, in addition to any local omits.  For example:

               OMIT 25 December
               REM 26 +1 OMIT sat sun MSG Test2

          This would issue the reminder on the 26th of each month, as well
          as the working day preceding it.  Also, on the 24th of December,
          1990, the reminder would be issued.  Even though Christmas 1990 is
          on a Tuesday, the global OMIT would cause the delta to skip it.

          Global OMITS are in force for all reminders following them in the
          reminder file.  Thus, you could have a series of reminders like
          birthdays, etc. for which global omits may not be necessary.  You
          can then place the global holiday list in your file, followed by
          business reminders for which omission of holidays would be
          appropriate.


          3.4. The INCLUDE Command

          The INCLUDE command takes the following form:

               INCLUDE filename

          This causes REMIND to suspend the current file and read the
          contents of the specified filename.  Once that file has been read,
          REMIND continues reading the original file from the line after the
          INCLUDE command.  INCLUDEs can be nested to a maximum level of 10.

          INCLUDE allows you or someone else to maintain a file of standard
          holidays (global OMITS) or system-wide reminders that everyone

          REMIND 2.2   (19 December 1990)                            Page 11





          should get.  For example, your local reminder file could look like
          this:

               # Example shown for MS-DOS
               INCLUDE \etc\holidays.sys  # System-wide holidays
               INCLUDE \etc\remind.sys    # Standard system-wide reminders

               # Now my private reminders go here.

          When you're PURGING a file (See the section "Purging Reminder
          Files" ) only the top-level file is used for purging.  Any
          INCLUDEd files are read and processed, but not purged.

          The ONCE keyword operates on the modification date of the top-
          level file.  The modification dates of INCLUDEd files are not used
          to control the operation of the ONCE keyword.

          3.5. Substitution

          Before being processed, the body of a RUN or MSG command is run
          through a substitution filter.  This filter makes certain
          substitutions in the body.  The substitutions are marked by a '%'
          symbol followed by a letter.  Whenever these sequences occur, they
          are replaced with text as determined below.  All dates referred to
          are the trigger date of the specified reminder.

          %a * Replaced with "on WKDAY, DAY MONTH, YEAR"

               For example, consider the reminder:
               "REM 18 Oct 1990 +4 MSG Meeting with Bob %a."

               If reminder were run on 16 October 1990, this would print:
               "Meeting with Bob on Thursday, 18 October, 1990."

               On 17 October 1990, the message would be:
               "Meeting with Bob tomorrow."

               On 18 October 1990, it would be:
               "Meeting with Bob today."

          %b * Replaced with "in DIFF days' time"

               Example:  "REM 18 Oct 1990 +4 MSG Meeting with Bob %b."

               16 Oct 1990: "Meeting with Bob in 2 days' time."
               17 Oct 1990: "Meeting with Bob tomorrow."
               18 Oct 1990: "Meeting with Bob today."

               Note that the number printed is the ACTUAL number of days
               between the current date and the trigger date.  The OMIT
               lists have no effect on this number.


          REMIND 2.2   (19 December 1990)                            Page 12





          %c * Replaced with "on WKDAY"

               Example:  "REM 18 Oct 1990 +4 MSG Meeting with Bob %b."

               16 Oct 1990: "Meeting with Bob on Thursday."
               17 Oct 1990: "Meeting with Bob tomorrow."
               18 Oct 1990: "Meeting with Bob today."

          %d   Replaced with the day of the month.

          %e * Replaced with "on dd/mm/yyyy"

          %f * Replaced with "on mm/dd/yyyy"

          %g * Replaced with "on WKDAY, DAY MONTH"

          %h * Replaced with "on dd/mm"

          %i * Replaced with "on mm/dd"

          %j * Replaced with "on WKDAY, MONTH DAYth, YEAR"

               This is replaced with things of the form "on Monday, October
               8th, 1990" or "on Sunday, October 21st, 1990" with the "st",
               "nd", "rd", "th" as appropriate after the day of the month.

          %k * Replaced with "on WKDAY, MONTH DAYth"

          %l * Replaced with "on yyyy/mm/dd"

          %m   Replaced with the name of the month.

          %n   Replaced with the number (1 - 12) of the month.

          %o   Replaced with " (today)" if and only if the current system
               date is the same as the date used by REMIND as the current
               date.  Recall that you can specify a date for REMIND to use
               on the command line.  This substitution is not generally
               useful in a REMinder, but is useful in a BANNER statement.
               See the section 'The BANNER Command'.

          %p   Replaced with "s" if the DIFF between the current date and
               the trigger date is not 1.  You can use this to construct
               reminders like:

               REM 1 Jan +4 MSG %x day%p to go before New Year's Day!







          REMIND 2.2   (19 December 1990)                            Page 13





          %q   Replaced with "'s" if the DIFF between the current date and
               trigger date is 1.  Otherwise, replaced with "s'"  This can
               be used as follows:

               REM 1 Jan +4 MSG New Year's Day in %x day%q time!

          %r   Replaced with the day of the month (01-31) with leading zero
               if needed to pad to two digits.

          %s   Replaced with "st", "nd", "rd" or "th" depending on the day
               of the month.  Example:

               REM 1 Mon +3 MSG First Monday of %m is the %d%s.

               For October, 1990, this would print:
               "First Monday of October is the 1st."

               For November, 1990, it would print:
               "First Monday of November is the 5th."

          %t   The number of the month (01 - 12) padded to two digits with
               leading zero if necessary.

          %u * Replaced with "on WKDAY, DAYth MONTH, YEAR"
               This is the same as %a except "st", "nd", etc. is added to
               the day of the month.

          %v * Replaced with "on WKDAY, DAYth MONTH"

          %w   Replaced with "WKDAY", the name of the day of the week.

          %x   Replaced with the DIFF between the current date and the
               trigger date.  The DIFF is defined as the number of days
               between the current date and the trigger date.  OMITs are not
               counted; strict date subtraction is performed.

          %y   Replaced with "YEAR", the year of the trigger date.

          %z   Replaced with "yy", the last two digits of the year.

          %_   (Percent-underscore) replaced with a newline.  You can use
               this to achieve multi-line reminders.

          %1   Replaced with "now", "m minutes from now", "m minutes ago",
               "h hours from now", "h hours and m minutes from now", etc.,
               as appropriate for a timed reminder.  Note that timer
               reminders are triggered like normal reminders - only the date
               portion is considered.  This causes the need for the "...ago"
               forms.

          %2   Replaced with "hh:mm" followed by "am" or "pm" as
               appropriate.

          REMIND 2.2   (19 December 1990)                            Page 14





          %3   Replaced with "hh:mm", the AT time in 24-hour format.

          %4   Replaced with "mm", where mm is the number of minutes between
               "now" and the time specified by AT.  If the AT time is
               earlier than the current time, this number is negative.

          %5   Replaced with "ma", where ma is the absolute value of the
               number produced by %4.

          %6   Replaced with "ago" or "from now", depending on the
               relationship between the AT time and the current time.

          %7   Replaced with the number of hours between the current time
               and the AT time.  This number is always non-negative.

          %8   Replaced with the number of minutes between the current time
               and the AT time, after the hours (%7) have been subtracted
               out.  This is a number from 0 to 59.

          %9   Replaced with "s" if the number produced by "%8" is not 1.

          %0   Replaced with "s" if the number produced by "%7" is not 1.

          %!   Replaced with "is" if the current time is before the AT time,
               or "was" if it is after.

          %"   (percent-doublequote) is removed.  This sequence is not used
               by the substitution filter, but is used to tell REMIND which
               text to include in a calendar entry when the -c option is
               chosen.  See the section "Producing a Calendar"

          Notes:

          o    REMIND normally prints a blank line after each reminder.
               However, if the last character of the body is "%", then the
               blank line will not be printed.

          o    All substitution sequences marked with "*" are replaced with
               "today" if the current date equals the trigger date, or
               "tomorrow" if the trigger date is one day after the current
               date.

          o    Any of the substitutions dealing with time (0 though 9 and
               "!") produce undefined results if used in a reminder without
               the AT keyword.  Also, if a reminder has a delta and may be
               triggered on several days, the time substitutions ignore the
               date.  Thus, the "%1" substitution may report that a meeting
               is in 15 minutes, for example, even though it may only be in
               2 days time.  It is recommended that you use the "%1"
               substitution only on reminders with no delta.



          REMIND 2.2   (19 December 1990)                            Page 15





          o    Capital letters can be used, in which case the first letter
               of the substituted text is capitalized.

          o    All other characters following a "%" sign are simply copied.
               In particular, to get a "%" sign out, use "%%" in the body.
               To start a body with a space, use "% " since REMIND normally
               scans for the first non-space character after the MSG or RUN
               token.

          3.6. Producing a Calendar

          REMIND can be used to create a calendar based on the contents of
          your reminder file.  This is done by invoking REMIND with the -c
          option.

          When you produce a calendar, REMIND will not pass the text through
          the subsititution mechanism.  Thus, you must indicate to REMIND
          which portions of the text should be placed in the calendar.  This
          is done with the %" sequence.  Here's an example:

               REM 6 Jan +6 MSG %"David's birthday%" is %a.

          When you run REMIND normally, it triggers the reminder as if the
          %" sequences were not there.  When you produce a calendar with the
          -c option, however, only the text "David's birthday" is placed
          into the calendar.  For convenience, timed reminders are sorted by
          time before being entered into the calendar, and the time of each
          reminder is printed before the text.

          Note that only MSG reminders are included in the calendar; RUN
          reminders are ignored.  If you indicate empty text for the
          calendar entry with the sequence %"%" in the reminder body, then
          the reminder will be ignored when producing the calendar.

          3.7. The BANNER Command

          When REMIND issues reminders, it normally prints a message saying:

               "Reminders for WKDAY, DAYth MONTH, YEAR (today):"

          if it is running with the current date equal to the system date.
          If it is running with a different date supplied via the command
          line, it leaves out the " (today):"

          You can change this default to anything you want with the BANNER
          command.  It should appear in the reminder file before any REM
          commands.  (This is not enforced, but a BANNER command encountered
          after a reminder has been issued will be ignored.)

          The format of BANNER is:  BANNER string

          The string is passed through the substitution mechanism described

          REMIND 2.2   (19 December 1990)                            Page 16





          above, using the current date for substitution.  The standard
          banner is described by:

               BANNER Reminders for %w, %d%s %m, %y%o:

          You can have a blank banner by using:

               BANNER %

          4. PURGING REMINDER FILES

          You should periodically purge your reminder file of "expired" REM
          commands and OMITs.  These are reminders which took place in the
          past and can never happen again, or OMITs which are for past
          years.  Of course, only REMs and OMITs with the YEAR specified can
          ever expire.

          To purge your file, run REMIND in purge mode.  This mode simply
          echoes non-expired lines to standard output, and expired lines to
          standard error.  Thus, to purge a file, you could type:

               REMIND -p notes.old > notes.new

          The file "notes.new" would contain all non-expired lines from
          notes.old.  All expired lines would be echoed to the screen.
          INCLUDEd files are read and processed, but are not purged.  You
          must purge each INCLUDEd file separately.

          Note that reminders which do not specify a YEAR, as well as
          repeating reminders, can never expire.

          You can supply a date on the command line when purging, but
          beware:  If you supply a date in the future, you may inadvertantly
          purge lines which have not really expired yet.



















          REMIND 2.2   (19 December 1990)                            Page 17





          5. DEBUGGING YOUR REMINDER FILE

          The debug flag (-d) is used to debug reminder files (not the
          REMIND program!)  It tells you all sorts of useful information
          about the reminder file.  It displays the trigger date of each
          reminder, and places an asterisk by those which would be issued on
          the current date.  It also informs you of OMITs which have
          expired, and gives several warnings about situations which could
          lead to long execution time or unexpected results.

          If you have a long reminder file, you may want to redirect the
          standard error stream.  In Unix, this is accomplished easily.  In
          MS-DOS, you can use the E2O program supplied with REMIND.

          5.1. Format of Debugging and Error Messages

          REMIND prints the filename, followed by the line number in
          brackets, followed by the error or debugging message.  If the
          verbose flag (-v) is supplied, it echoes the line from the file as
          well.


          6. WISH LIST

          o    REMIND has been ported to Unix.  The source has been posted
               on alt.sources on the usenet.  It's also available in the
               file /pub/remind-2.2.tar.Z via anonymous ftp from
               alfred.ccs.carleton.ca (134.117.1.1)

          o    Faster algorithms for date calculation.  Most of the
               algorithms are fairly "brute force", but they execute
               reasonably quickly.  The "back" feature especially leads to a
               lot of backtracking.

          o    A prettier interface - maybe some snazzy pop-up windows, with
               centered messages, colors and so on... hell, if you really
               want that, use REMIND as a back-end and do some post-
               processing on its output.  Easy from Unix, slow from MS-DOS.

          o    Automatic purging of reminder files.  Could be useful or
               dangerous, depending on your perspective.












          REMIND 2.2   (19 December 1990)                            Page 18





          7. WISHES LIST

          I hope you enjoy using REMIND.  If you have any suggestions,
          comments, bugs, problems, donations :-) or kudos, send them to:

          David Skoll
          4-317 Lebreton Street
          Ottawa, Ontario
          K1S 4L4  CANADA
          Tel. [phone]

          I can be reached by e-mail at [e-mail].









































          REMIND 2.2   (19 December 1990)                            Page 19