  ========================================================================
    (c) Martin N Dunstan  (mnd@dcs.st-andrews.ac.uk)  January 22nd, 1996
  ========================================================================

Program:
   Txt2Agn


Version:
   1.00


Platforms:
   Psion 3a, 3c and Siena. Also runs on the Acorn Pocketbook II.


Purpose:
   Convert a plain text file of dates and events into an Agenda file.
   Examples of use include converting rota sheets prepared in a spreadsheet
   or simply processing a timetable from work. An example of the input file
   (using dd/mm/yy format) is:

      14/2/97 Valentines day
      25/12/97 Christmas day
      25/12/1997 Visit parents

   Invalid dates are detected and can be corrected by the user or
   automatically by the program. A variety of preference settings are
   available to control the conversion process and context-sensitive help is
   accessible at all times.


Author:
   Martin N Dunstan (mnd@dcs.st-andrews.ac.uk)
       (http://www-theory.dcs.st-andrews.ac.uk/~mnd/)


Txt2Agn is available from:
   http://www-theory.dcs.st-andrews.ac.uk/~mnd/export/txt2agn
   ftp://www-theory.dcs.st-andrews.ac.uk/user/mnd/txt2agn


Registration:
   This program is shareware - if you find it useful please register
   your copy by sending your name and a UK cheque for 5 to the
   address below. Please include your email address (if you have one)
   so that I can inform you of your code which will remove the nag
   screens and the "annoying window".

      Martin Dunstan
      1 Cupar Mills,
      Cupar,
      Fife KY15 5EH
      U.K.

   If you live outside the UK you might want to use a service such as Ruesch
   International Financial Services (details of this can be found on the
   Web page http://www.os.qub.ac.uk/nifhs/ruesch.html) to obtain a UK cheque
   relatively cheaply. 


Installation:
   1) Create a \APP\TXT2AGN directory on the internal drive (M:)
   2) Copy TXT2AGN.OPA into a \APP directory
   3) Copy TXT2AGN.AGN into a \APP\TXT2AGN directory (note that PsiWin may
      complain that this is non-standard - continue anyway!)
   4) Create a \TXT directory
   5) Place any files to be converted into \TXT
   6) Choose "Install" from the "Apps" menu (Psion-I) and
      select Txt2Agn. Press ENTER to install it.

   You can place TXT2AGN.OPA in a \APP directory on any drive. You can also
   place TXT2AGN.AGN in a \APP\TXT2AGN directory on any drive.


Memory usage:
   Txt2Agn.opa ....  22K
   Txt2Agn.rsc .....  0K
   Txt2Agn.agn .....  0K
   User memory ..... 12K
   System memory ... 30K
   Total ........... 64K


Tutorial:
   This section briefly describes the use of Txt2Agn on the demo file
   DEMO.TXT that accompanies the distribution. It assumes you have
   installed the application as described in the previous section and copied
   the DEMO.TXT file in a \TXT directory. Note that this file has a number of
   faulty entries for the purposes of example.

   1) From the system screen highlight the DEMO file listed under the Txt2Agn
      icon (try pressing the System button if it can't be seen). Press ENTER
      to start the application.

   2) A title screen will appear followed by a window asking you to register.
      Try pressing the Help key - this will normally bring up context
      sensitive help at other dialogs. If you have been sent your
      registration code press R otherwise press C to continue.

   3) Having pressed C an "annoying window" will appear - this will not be
      present in registered versions. After a brief pause the preferences
      dialog will appear. The settings here are stored ready for the next
      time you use the program.

   4) Use the up and down arrow keys to move between the options and the left
      and right arrow keys to cycle through the choices for each option. To
      leave the program at this point press Escape. Dealing with each of the
      options in turn:

      a) Errors: this controls how the program behaves when an error is found
         in the input file (an illegal date).

         Ignore:   any illegal entries will be skipped.
         Auto-fix: the program will try and guess what date you really meant
                   when an illegal entry is found.
         Ask user: Illegal entries will be displayed in a dialog box for the
                   user to correct or skip over.

         I will assume "Ask user" is selected.

      b) Dates: choose the date format used in the input file. This may be
         either dd/mm/yy or mm/dd/yy.

      c) Logfile: if set to "On" then any errors will be written to the
         logfile specified on the next two lines.

   5) Press M to get more options and another dialog box will appear. The two
      choices are:

      a) Partial dates: assuming we are using the dd/mm/yy date format then a
         partial date is one which has the year or even the month missing. If
         partial dates are allowed then the program uses the current year and
         month to fill in the missing information. Thus if today is January
         22nd, 1997 then 25/4 stands for April 25th 1997 and 28 stands for
         January 28th 1997. If partial dates are not allowed then they are
         considered to be an error and the program will act accordingly
         (ignore them, fix them or ask the user).

      b) Logfile: use this setting to control what happens if logging is
         turned on and the logfile already exists. If "always overwrite" is
         selected then the logfile will be deleted without asking or telling
         the user.

      Press Enter when you've set things up the way you want and you will be
      returned to the previous dialog. Press Enter to move on to the next
      dialog. If the logfile already exists and you haven't chosen the
      "always overwrite" mode you will be asked if you want to overwrite it.
      Pressing N will return you to the preferences dialog so that you can
      you can choose another filename.

   6) At this dialog you are requested to provide the name of the Agenda file
      you want to create. The program will supply a default name based on the
      name of the input file. Thus converting DEMO.TXT will mean DEMO.AGN is
      the default Agenda filename. Either type in a new name or press TAB and
      use the Psion file selector to overwrite an existing file. Press Escape
      to quit the program.

   7) Press ENTER when you have selected a file - if it already exists you
      will be asked if you wish to overwrite it. Pressing N will return you
      to the file selection dialog; Escape will quit the program.

   8) A progress indicator (sliderbar) will appear on the screen with the
      title "Creating Agenda file". There will be an initial pause of about 7
      seconds while the indicator is 1/3 filled and then it will quickly
      reach the filled state. Pressing Escape will pause the program and you
      will be asked if you want to quit. Pressing N will allow the conversion
      to continue while Y will stop the program. Note that the program will
      be slow to react to the key press so you should press Escape firmly
      once and then wait for a second or two.

   9) The first indicator will be replaced by a second which shows how much
      of the input file has been processed. I you are converting the demo
      file with error mode set to "Ask user" then about 3/4 of the way
      through the input file a dialog box will appear asking you to fix the
      mistake.

      Press Escape to skip the entry otherwise correct it by using the arrow
      keys to select the faulty date and typing the correct one in it's
      place. Part of the line that was causing the problem is shown for
      reference at the top of the window. Press Enter when you are satisfied
      with the entry.

  10) Another faulty entry will appear (assuming "ask user" mode which should
      be dealt with as before.

  11) Once the whole file has been processed the program checks to see if any
      errors were noted in the logfile (i.e. error logging was on and at
      least one error occurred). If so a window will appear informing the
      user of this.

  12) Finally, if the program is unregistered you will be given the
      opportunity to do so!

  13) If errors were found you should check the logfile for details. This
      file is plain text and can be examined using the Word application or
      any other text reader.


Hints:
   * Make sure the program always has logging turned on if you are converting
     files in "ignore" or "auto-fix" mode and check the logfile afterwards to
     see what happened if any errors occurred.

   * Run in "ask user" mode - usually there would be no errors and thus no
     need for user intervention. If any errors do appear then it is probably
     quicker to fix them during conversion rather than do it later in Agenda.

   * If you already have a \TXT directory which you use to keep other text
     files in try using the "Create new list" option from the "Special" menu
     on the system screen. Refer to the Psion User Guide for details.


Frequently asked questions:
   Q) How can I control the settings of the Agenda files produced by Txt2Agn
      (e.g. diamond list, printing)?
   A) Use Agenda to load \APP\TXT2AGN\TXT2AGN.AGN and change any settings you
      want. Make sure the file is saved and quit Agenda. The next time you
      use Txt2Agn the new settings will be used.

      An alternative method is to open an Agenda file which has already been
      configured and use the "Merge" option in Agenda.

   Q) Why can't I enter dates after the year 2049 or before 1970?
   A) This is due to limits imposed by the Psion OS. The text converter will
      recognise dates outside this range but the Agenda program may not be
      able to display them!

   Q) Why doesn't auto-fix mode work very well?
   A) It is extremely difficult (impossible generally!) to correctly guess
      what date the user actually meant. Thus the program simply works back
      to find the first valid date prior to the illegal one. Hence 12/13/98
      is guessed as being 12/12/98 and 31/09/04 is guessed as 30/09/04.

   Q) Can I use four figure years such as 1997 instead of 97?
   A) Yes but you are only allowed years between 1970 and 2069.

   Q) How can I quit from the program once it has started?
   A) From the main dialogs you can leave the program by pressing the Escape
      key. If the program is actually creating the Agenda file or processing
      the input file Escape will pause the program and give you the chance to
      quit.

      If you really need to stop the program urgently hold down the Psion key
      and press Escape. If this fails choose "Kill Application" from the
      "Apps" menu on the system screen. If you use any of these emergency
      exits you should remove the Agenda file that was being created as it
      will be corrupted and might crash the Agenda program if you try to use
      it inadvertently.

  ========================================================================
    (c) Martin N Dunstan  (mnd@dcs.st-andrews.ac.uk)  January 22nd, 1996
  ========================================================================

