Txt2Agn

======================================================================== (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 ========================================================================