LE-NAG:
     LeverEdge NAG is a program to remind you of events before you
     miss them.  Events can be scheduled to occur once or repeat
     daily,weekly,monthly or yearly.  You can be alerted of the
     event in a number of ways from a screen flash to a message
     requester.

     ** The reqtools.library is not required but is recommended. **

     Shareware, binary only.
     Author: Craig M. Lever

Disclaimer:
     I will do my best to fix bugs as they appear and/or improve the
     program but I won't be held responsible for what is outside my
     control:

     I make no warrantee to the usefulness of this program nor can I
     be held responsible for any damage caused while using it.

Distribution:
     LeverEdge NAG is copywrite 1992 by Craig Lever, All Right
     Reserved.  This program can be distributed free of charge
     electronically or via disk collections.

     This program is shareware so if you feel inclined, send a
     contribution to the address below.  I suggest $5 but feel free to
     send me any amount.  I'll accept US & Can currency money orders or
     cheques drawn from a Canadian bank.  I'm even interested in
     collecting samples of foreign currency so if you don't want to go
     through the hassle of getting a money order and don't mind the
     risks of sending currency via mail then go for it.  The postal
     service may frown on you sending coins so I don't recommend that.

     This shareware version has a couple of things added to encourage
     contributions.  First it has two internal events, one alerts you
     with a requester which can be acknowledged immediately so it will
     only come up once and another which flashes the screen with a
     DisplayBeep every half hour.  Also the AmigaDOS execute alert
     will prompt you with a requester so you can confirm or abort the
     command.
     
     If you do send $5 Cdn. or more (and it is enough to cover the cost
     of a disk and postage) I'll send you the latest version with the
     shareware notices and the requester for the AmigaDOS execute alert
     removed.

Reaching me:
     I can be reached at the following mailing address:
          Craig Lever
          RR #1.
          Airdrie, Alberta, Canada.
          T4B 2A3

     I can also be reached through some of the Fido Amiga echoes
     or by Fido Netmail at:
          Craig Lever @ 1:134/27.0 - The AMUC Express
     or by UseNet Netmail at:
          cmlever@wwshop.cuc.ab.ca - The Wizard's Workshop

Instructions:
 A)  Startup

     The program can be started from the workbench by clicking on its
     icon or from the CLI.

     The format from the CLI is:
          LE_NAG [-t #] [-l #] [-h #] [-w #] [-m #] [-s #] [-d #] [-q #]
               -t sets the top edge of where the window opens
               -l sets the left edge of where the window opens
               -h sets the height of the window (0 = minimum)
               -w sets the width of the window  (0 = minimum)
               -m sets the check minutes value  (explained later)
               -s turns on or off Day Schedule  (0 = off, 1 = on)
               -d display a quick summary of the events for a # of days      
               -q quit immediately (0 = no, 1 = yes)
             nags once for the current time and closes down
               where # is an integer

     Therefore, the CLI input format allows you to configure the
     program a little more.  As well, it lets you set where its
     console is located if you run it with a script executed by
     NewShell or IconX (See your manuals for more info on this).

     If you wish to put LE-Nag in your startup sequence I recommend
     one of the following.

     If you aren't planning on using alerts which print to the
     console:
          cd <LE-Nag directory>
          run >nil: <nil: le-nag [arguements]
     If you do want console output:
          NewCLI con:280/10/360/60/LE-Nag s:Le-Nag.script
     and s:Le-Nag.script would be:
          cd <LE-Nag directory>
          le-nag [arguements]

     When the program runs it will open a window on the workbench
     screen.  For those of you without the benefit of WB 2.0's window
     sizing gadgets you can use the right mouse button to minimize and
     maximize the window.


 B)  Features

     The window is divided into a couple of regions of related
     gadgets described below.

     - Calendar

     The top left region is called the Calendar and includes gadgets
     to change the displayed year, month, day, hour and minute.  The
     calendar is used to enter times for events as well as setting a
     time used by other functions to test how events respond at a
     given time, to view a given day's events or to move to events
     scheduled for a given day.

     - Day Schedule

     To the right of this is the Day Schedule gadget.  If this gadget
     is selected it shows what times during the calendar day have
     events scheduled as well as highlighting days on the calendar
     where events with the Highlight Day alert occur.  Turning it on
     will slow down the response when changing the Calendar day, month
     or year since the events list must be rescanned.  For this reason,
     it can be toggled on and off with a mouse click.

     - Event Information Area

     The bottom of the window is the Event Information area.

     At the top of this area is the Event string gadget
     where the event can be described with up to 80 characters.

     Below this is the Execute type gadget and the Execute string
     gadget.  The Execute gadget cycles through the types of alerts
     events can generate, they include:
         Print:          Outputs to the console window.
         DisplayBeep:    Flashes the screen with DisplayBeep().
         AmigaDOS:       Executes and AmigaDOS command in C: or
                         the current directory.
                         Since the AmigaDOS execute is very powerful
                         and potentially dangerous, the shareware
                         version requires the reqtools.library to
                         function and puts up a requester to verify
                         the AmigaDOS command.
         Requester:      Opens a requester on the Workbench.
                         The requester is more flexible than any
                         other method of alert since it gives you
                         three choices of response:
                              Acknowledge
                              Acknowledge and then Save Events file
                              Get Out of My Face
                         Where GOMF just gets rid of the requester,
                         Acknowledge adjusts the acknowledge time
                         which is discussed later.  But basically an
                         acknowledged event won't come up again until
                         after the current eventtime passes.     
                         (or never again if the event does not repeat)
                         ** Requires the reqtools.library **
         SPEAK:          Talks using the AmigaDOS SPEAK: device which
                         has to be installed with MOUNT SPEAK:
                         SPEAK: requires the translator.library
                         and narrator.device in libs: and devs:
                         The AmigaDOS 2.0 & 1.3 manuals both describe
                         the options for changing the qualities of
                         the voice. (See speak-handler)          
                         And example on how to use options would be:
                         " \nopt/p300/r\Hello.\nopt/s100/p100/n\nBye."
                         Which would say "hello" with a high pitch
                         robotic voice and then "bye" in a slower,
                         lower and less robotic (normal) voice.
          Note:  SPEAK: does not return an error
                         message if it can't open its sound channel.
                         If it can't the output will just disappears.
         Play Sound:     Plays up to 4 IFF sound file simultaneously.
                         If an voice is unavailable the sound    
                         will not be played.  Also only the first
                         128K (131072 bytes) will be played if the
                         sample is longer.
         Highlight Day:  This is a special event that changes the
                         color of the day on the calendar.  It is
                         special in two ways.  First, it is only in
                         effect if the Day Schedule gadget is
                         selected.  And second, it is not affected by
                         the acknowledge time.

     The Execute string (up to 80 characters long) is used to provide
     information to be used in the alert, ie what is printed if Print
     is the Execute type, what is executed if the Execute type is
     AmigaDOS.
     There are some escape sequences supported when this string is
     expanded, these are:
          \t - expanded to a tab
          \n - expanded to a carriage return & line feed
          \r - expanded to a carriage return
          \\ - used to indicate a single \
     \n and \r can be used to seperate commands for the AmigaDOS
     alert and to seperate IFF sound files for the Play Sound alert.

     In addition to the escape sequences there are some conversion
     sequences which allow you to include information about the event
     and the time when the alert occurred, these are:
          %eX or %EX for info on the event time
          %cX or %CX for info on the current time
          %aX or %AX for info on the last acknowledge time
          %lY or %LY for info on the length
          %dY or %DY for info on the diff. between event & current time
          %s  or %S  for the event text
          %%  used to indicate a single %

          and X can be the folowing:
               c - century integer     ie 19
               C - century text        ie Nineteen
               y - year integer        ie 92
               Y - year text           ie NinetyTwo
               m - month integer       ie 2
               M - month text          ie February
               w - weekday             ie 4        (Sunday is 0)
               W - weekday text        ie Thursday
               d - day integer         ie 4
               D - day text            ie Fourth
               h - 12 hour integer     ie 5
               H - 12 hour text        ie Five
               i - 24 hour integer     ie 17
               I - 24 hour text        ie Seventeen
               p or P - AM/PM phase    ie PM
               n - minutes integer     ie 15
               N - minutes text        ie Fifteen
               s or S - seconds        ie 4030030303
          and Y can be the folowing:
               d - days integer        ie 493
               D - days text           ie NintyThree
                    note: the text only shows two digits of the integer
               h - hours integer       ie 6
               H - hours text          ie Six
               n - minutes integer     ie 15
               N - minutes text        ie Fifteen
               s or S - seconds        ie 4030030303

          If X or Y isn't in the list then the default is to print the
          seconds count.

          The % conversions can even use formatting information like
          field sizing and left right justification which C programmers
          are probably familiar with.  For those unfamiliar with these,
          here  is the format:
               %[flags][width][.precision]type

               where:
                    type is the sequences described above
                    flags can be -,+,# or <space>.  The most useful is
                         - which will left justified the number or text.
                    width is an integer specifying the minimum width
                         a leading zero causes numbers to be printed
                         with leading zeroes, ie 02
                    precision is an integer.  For text it specifies
                         the maximum # of character to display.
                         For numbers it works the same as width with
                         a leading zero.
     If the Execute string is empty then the Event string will be
     used in its place.

     Below the execute gadgets are a number of time gadgets which
     are set by selecting the time gadget and moving the Calendar
     gadgets to change its contents.
     Once the value is correct the gadget can be clicked again to
     unselect it or it is also unselected if another time gadget is
     selected.  The changes can also be cancelled with the Cancel
     gadget if the time gadget is still selected.
     There are two different types of time gadgets, some are absolute
     time gadgets which are tied to a date and some are relative time
     gadgets which measure an interval of time of some length.
     Here is a description of what each time gadget means:
          Event Time     - start time of the event or start time of
                           the first event if it repeats.  Absolute.
          Length         - length of the event. Relative, it is set
                           by moving the calendar to the end time of
                           the first event.
          Advance Notice - period of time before the event occurs
                           when it will generate alerts.  Relative.
          Interval       - controls how many times the alert will
                           occur between the advance notice and the
                           event time.  It sets how many minutes
                           are between alerts.  Relative.
          Acknowledge    - is the time this event was acknowledged.
                           If the next event time after the
                           acknowledge time is the same as the next
                           event time when the program is nagging
                           then no alert is generated.  Absolute.

     There is one more gadget in the area called Group.  This is a 4
     digit ASCII code you can assign to an event.  This allows you to
     link serval related events together.  If one gadget is
     acknowledged then all of the others will also have their
     acknowledge time updated.  For example perhaps you can watch the
     same TV program at 2 different times, if you see it the first
     time and acknowledge then you won't be alerted of the other time
     it is on.
     There is one exception, if group code is blank then these events
     are treated as ungrouped and acknowledging them does not effect
     all other gadgets that have a blank group.
     To the right of the time gadgets are the flags used to determine
     how the event will occur or repeat.
     Yearly Monthly and Weekly are used with the Repeat gadget value
     to determine when to event can occur if it repeats.
     The repeat gadget indicates the interval of weeks, months or
     years between events.  If Weekly is set it is the number of
     weeks, if Monthly is set (and Weekly isn't) then it is the number
     of months, if Yearly is set (and neither Weekly or Monthly are)
     then is is the number of years.
     If Weekly is set then the Monthly and Yearly gadgets indicate
     if the event can occur on a month or year not equal to that of
     the original event time.
     Similarly if Weekly isn't set and Monthly is then Yearly
     indicates if the repeating event can occur in months outside the
     year of the original event time.
     This approach allows you to set up events which repeat but stop
     when the month or year ends.

     Below the Yearly gadget is a gadget called D= and one for each
     day of the week.  The D= stands for Day Equals and means the
     event time must be one of the days set in the weekday gadgets.
     The most obvious use of this is to produce an event for Friday
     the 13th if your the superstitious type (or Tuesday the 12th if
     your worried about Friday the 13th viri)
     If the Day Equals gadget is not set and some of the weekday ones
     are then the whole week after the event time is checked and any
     days where the weekday gadget is set treated as events.
     This has two uses for me,  First to make events that repeat daily
     by making events that repeat weekly and setting all the weekday
     gadgets on.  And also to make events that occur on a particular
     day of the week in a particular week of every month, like my AMUC
     User's group meeting on the 3rd Wed of every month.  To set it up
     I just picked a month for the event to start, select the 15th of
     that month (the 3rd week can start no earlier than the 15th) and
     set the repeat count to 1, and turned on Yearly, Monthly. Weekly
     and Wednesday.
     There are two other flag gadget used to automate some options
     which can be performed after the alert occurs.  The first is
     Auto Ack or Auto Acknowledge and causes an acknowledge to occur
     after the event is processed.  It is useful if your not using the
     Requester alert where you can manually acknowledge.  What
     acknowledging does is prevent the event from occurring again
     until the time is past the event time which already generated
     an alert.  The other is AutoSave which saves the Events file
     after the alert occurs.  It is most useful when combined with
     Auto Ack so the change in the Acknowledge time is stored.
     
     Note the above description of acknowledging is a little week so
     here is a little more correct (but confusing) description.
     If the event does merit an alert the next thing that is done
     is the Acknowledge time is checked to see if it is related
     to the same event time as that which created the new alert and
     if it is the alert does not occur.
     
     - System Time

     In the upper right of the window there is a gadget displaying the
     current time.  It can be set the same as any time gadget by
     selecting it and changing the calendar and then unselecting it.

     - Check Minutes

     Below System Time is the Check Minutes gadget.  This determines
     how often the program checks to see if any events occur.  Note
     this is not quite like the interval time gadget as it effects all
     events.  With larger Check Minutes values there is also a bit
     greater risk of events being missed if something happens to the
     clock but it also reduces how often the program need the CPU.

     - Control Panel

     Below Check Minutes is a group of gadgets I call the Control Panel.

     Next and Previous move from one event to the next.

     Delete removes the currently displayed event.
          Note:  Currently deleted events are NOT recoverable.

     The New gadget is for creating a new blank event.

     Cancel has two functions, if a time gadget is selected it undoes
     the changes you have made to that time gadget. Otherwise it swaps
     the current event's information with an undo event.  This undo
     event is initially set to the information in the event when you
     first moved to it with Next/Previous.  If it is a new event then
     it equals the contents of the current event just before you
     create the new event. This is useful for making events which
     contain much of the same information, just enter the similar 
     information and hit New then Cancel.

     Next to Cancel is Save which saves the events to the file .Events
     in the current directory.  As an additional note .Event files can
     be joined together with JOIN (or TYPE) as .Event files are just a
     list of Events without any header or footer information.

     The next gadget is the Edit Mode gadget which effects the
     functions of Next/Previous and to a lesser extent, Delete and
     New.  It has three settings:
          Edit All   - Next and Previous simply move from the
                       current event to one immediately adjacent to it.
          Edit Day   - Next and Previous try to move to the
                       next/previous event which occurs on the day
                       shown in the Calendar area.  Delete will also
                       try to move to an event occurring on the
                       Calendar day but if it can't it will move to an
                       adjacent event.
          Edit Group - Next/Previous will only move to an event which
                       has the same group as the current event.  Delete
                       will try the same but if one doesn't exist it
                       will go to an adjacent Event.  New will also put
                       the Group of the current event into the new
                       event's Group.

     The last gadget is Goto and it is used with time gadgets to move
     the Calendar to the time values shown in them.  First Goto is
     selected and then a time gadget is selected.  Goto is cancelled
     if Goto,Cancel or something other than a time gadget is selected.
     Selecting absolute time gadgets after Goto will move to the time
     shown in them whereas relative time gadgets will move the Calendar
     to a position relative to the event time.  Interval, and Advance
     Notice move to before the event time and Length moves to after the
     event time, ie at the event end time.

     Thanks you for taking the time to look at these rather long docs.
     I hope it helps more than it hurts as you try to understand
     LE-NAG.

     This program has been tested with an 6M A3000 under 1.3 and 2.0,
     a 1M A500 under 1.3 and a 256K A1000 under 1.3 (WB loaded).

Many Thanks go to:
     Bryce McCormick, my alpha/beta/gamma tester, who directly and
     indirectly inspired changes to the program and made it more
     difficult for me to shelf for any great length of time.

     Stephen Vermuelen, what can I say, if there is a Amiga
     programming question that he doesn't know the answer to I haven't
     had to ask it yet.

     Bob Leivian who ported the calendar program found on Fish 34.
     It served its purpose as this program was being written and was a
     good model for this program.

     Anders Bjerin who's Amiga C Manual continues to be the source of
     the underlying interface monitoring code in anything I start.
     Thanks also for the EasySound IFF 8SVX player.

     Timm Martin who's timer device code cut down considerably the
     time necessary to get this program functional even if I did have
     to work the code over a bit.

     Leo Schwab who's process spawning code made this program
     multitask internally where it needed it most.

     Nico Francois who's ReqTools library made nagging with good 
     looking requesters only a function call away.

     And ofcourse Fred Fish for providing a reliable first source for
     the PD programs and the source code of programmers like those
     mentioned above.

ReqTools is Copyright (c) Nico Francois
